glassjar 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Jacob Roberts-Baca
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,196 @@
1
- # Temporary Holding Version
1
+ # glassjar
2
2
 
3
- 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.
3
+ A browser-based execution engine powered by WebAssembly. Compile and run C/C++ and Python programs entirely in the browser with a built-in debugger.
4
+
5
+ ## Installation
6
+
7
+ ```bash
8
+ npm install glassjar
9
+ ```
10
+
11
+ > **Requires** these response headers (the engine uses `SharedArrayBuffer` for stdin):
12
+ >
13
+ > ```
14
+ > Cross-Origin-Embedder-Policy: require-corp
15
+ > Cross-Origin-Opener-Policy: same-origin
16
+ > ```
17
+
18
+ ### Hosting the engine Wasm
19
+
20
+ By default the engine loads its own `engine_bg.wasm` (about 9 MB) from jsDelivr, at
21
+ the exact version you installed, and its worker script from `dist/assets/` next to the
22
+ package, which bundlers pick up automatically. To serve the Wasm from your own site
23
+ instead, copy `node_modules/glassjar/dist/engine_bg.wasm` into your static files and
24
+ pass its URL:
25
+
26
+ ```ts
27
+ const engine = await Engine.create('c', { wasmUrl: '/engine_bg.wasm' });
28
+ ```
29
+
30
+ Relative URLs resolve against the page, and only `http:`/`https:` are accepted. The
31
+ file must come from the same package version. A page loads the engine Wasm once, so
32
+ every `Engine.create` on a page must pass the same `wasmUrl`.
33
+
34
+ ---
35
+
36
+ ## Quick start
37
+
38
+ ```ts
39
+ import { Engine } from 'glassjar';
40
+
41
+ const engine = await Engine.create('c');
42
+
43
+ // Virtual filesystem — the program sees these as real files
44
+ engine.fs = {
45
+ 'main.cpp': `
46
+ #include <iostream>
47
+ int main() {
48
+ std::cout << "Hello, world!" << std::endl;
49
+ return 0;
50
+ }
51
+ `
52
+ };
53
+
54
+ // stdout / stderr chunks arrive as Uint8Array (UTF-8)
55
+ const decoder = new TextDecoder();
56
+ const print = (chunk: Uint8Array) => process.stdout.write(decoder.decode(chunk));
57
+ engine.stdout.on('data', print);
58
+ engine.stderr.on('data', print);
59
+
60
+ await engine.run();
61
+ ```
62
+
63
+ > Programs compile in **debug mode** by default, so a [DAP](https://microsoft.github.io/debug-adapter-protocol/) handshake is required before `run()` will proceed — see the [integration guide](./docs/integration.md#debugger-dap). To skip it, set `engine.debugger.enabled = false`.
64
+
65
+ C++ source `throw`/`catch` and RAII work in Run and Debug. Prebuilt libc++ error
66
+ helpers can still abort instead of throwing. The worker embeds a small LLVM
67
+ exception supplement; compiler/sysroot URLs stay unchanged. Exact upstream
68
+ notices and payload provenance are in `share/licenses/cpp-exceptions/` inside
69
+ [runtime.tar.gz](./assets/cpp-exceptions/runtime.tar.gz).
70
+
71
+ ---
72
+
73
+ ## Full API
74
+
75
+ ```ts
76
+ const engine = await Engine.create('c'); // 'c' | 'python'
77
+
78
+ engine.fs; // DirNode — virtual filesystem, set before run()
79
+ engine.binaryFiles; // Record<string, Uint8Array> — optional C/C++ binary files
80
+ engine.cppArtifacts; // Optional selected sources, archives, and precompiled header
81
+ engine.stdout; // Stdout — .on('data', (chunk: Uint8Array) => …) / .off(...)
82
+ engine.stderr; // Stdout
83
+ engine.stdin; // Stdin — .write(string | Uint8Array): Promise<void>
84
+ engine.hostDevice; // Optional C/C++ and Python duplex byte device — see below
85
+ engine.debugger; // Debugger — DAP interface; set .enabled = false to skip the handshake
86
+ engine.lang; // Lang
87
+
88
+ engine.run(); // Promise<RunResult> — { type: 'completed', exitCode } | { type: 'stopped' } | { type: 'error', error }
89
+ engine.stop(); // void — kills the worker; run() resolves with { type: 'stopped' }
90
+
91
+ engine.debugger.send(message); // DAP request, returns response synchronously
92
+ engine.debugger.on('event', fn); // async DAP events
93
+ engine.debugger.on('artifact', fn); // download artifacts emitted by the engine
94
+
95
+ // Python only — hide bridge/bdb frames from stackTrace (set before run())
96
+ engine.debugger.filterInternals = true;
97
+ ```
98
+
99
+ See [Presentation filtering (Python)](./docs/integration.md#presentation-filtering-python) in the integration guide for stack `presentationHint`, frame naming (`__main__` vs `main`), and dunder local filtering.
100
+
101
+ ---
102
+
103
+ ## Precompiled C++ inputs
104
+
105
+ Set `binaryFiles` to bytes keyed by absolute virtual paths. Set `cppArtifacts`
106
+ to select source files, link archives, or use a precompiled header:
107
+
108
+ ```ts
109
+ engine.binaryFiles = { '/support.a': archiveBytes, '/headers.pch': headerBytes };
110
+ engine.cppArtifacts = {
111
+ sources: ['/main.cpp'],
112
+ archives: ['/support.a'],
113
+ precompiledHeader: '/headers.pch'
114
+ };
115
+ ```
116
+
117
+ All fields are optional. Without `sources`, the engine compiles every source in
118
+ `engine.fs`. Selected sources must exist and cannot be empty; archive and PCH
119
+ paths must have matching bytes in `binaryFiles`. Binary paths must be absolute,
120
+ cannot contain empty, `.` or `..` components, and cannot replace existing files.
121
+ The engine snapshots the binary bytes and artifact options when a run starts.
122
+ Clear them before reusing an engine for an ordinary source-only run.
123
+
124
+ Build artifacts with the same compiler, sysroot, and flags as the engine. A PCH
125
+ also needs its original header files at their original virtual paths. These
126
+ inputs work in Run and Debug for C/C++ only; Python and Rust reject them.
127
+
128
+ After building, run the browser regression with an existing Playwright installation:
129
+
130
+ ```bash
131
+ PLAYWRIGHT_MODULE=/absolute/path/to/playwright/index.mjs node tools/cpp-artifacts/run.mjs --exceptions
132
+ ```
133
+
134
+ ---
135
+
136
+ ## Wiring stdin
137
+
138
+ `engine.stdin.write()` accepts a UTF-8 string or `Uint8Array`. Programs read via `cin`, `scanf`, `read()`, etc.
139
+
140
+ ```ts
141
+ await engine.stdin.write('42\n');
142
+ await engine.stdin.write(new TextEncoder().encode('42\n'));
143
+ ```
144
+
145
+ ---
146
+
147
+ For C/C++ or Python host I/O, set `engine.hostDevice` to a synchronous opener receiving
148
+ `{ signal, onData, write }`; return an optional synchronous cleanup function. The guest opens
149
+ `HOST_DEVICE_PATH` with `O_RDWR` for blocking reads/writes; polling is unsupported.
150
+ `write` snapshots bytes; await each write. Stop/exit aborts the per-run signal,
151
+ rejects pending writes and calls cleanup once. Terminal I/O stays separate.
152
+
153
+ Python uses the same device through `os.open("/dev/debugger-sh-host", os.O_RDWR)`,
154
+ `os.read(fd, size)`, and `os.write(fd, data)`. Reads and writes may be partial;
155
+ loop until a complete application-defined message has transferred. The device
156
+ is a byte stream: framing, request/response matching, and graphics or AI behavior
157
+ belong to the application. It is absent when no opener is supplied.
158
+
159
+ Test after building: `npx -y bun tools/host-device/run.ts`.
160
+
161
+ ## Example project
162
+
163
+ For a full reference integration, see the [debugger.sh IDE](https://github.com/debugger-sh/debugger.sh) — a Next.js + MUI app wiring up CodeMirror 6, xterm.js, and `debugger-sh` into a working in-browser IDE.
164
+
165
+ ---
166
+
167
+ ## Contributing / building from source
168
+
169
+ > Requires [Cargo 1.91+](https://crates.io/), [wasm-pack](https://rustwasm.github.io/wasm-pack/), and Node v22+.
170
+
171
+ ```bash
172
+ cargo install wasm-pack
173
+ npm install
174
+ npm run build # wasm-pack build --target web && vite build
175
+ npm run dev # local development
176
+ ```
177
+
178
+ After building, run the stdin browser regression checks with an installed Playwright
179
+ module and Chromium browser:
180
+
181
+ ```bash
182
+ PLAYWRIGHT_MODULE=/absolute/path/to/playwright/index.mjs node tools/stdin/run.mjs
183
+ ```
184
+
185
+ The checks cover an empty read without input, sequential Python input across reruns,
186
+ stopping blocked input, and C++ input. Pass a built or unpacked release's
187
+ `dist/glassjar.js` as the first argument to test that artifact.
188
+
189
+ To test against the reference IDE, clone [debugger-sh/debugger.sh](https://github.com/debugger-sh/debugger.sh) alongside this repo and link:
190
+
191
+ ```bash
192
+ npm link # in this repo
193
+ cd ../debugger.sh
194
+ npm link glassjar
195
+ npm run dev
196
+ ```