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 +21 -0
- package/README.md +195 -2
- package/assets/cpp-exceptions/runtime.tar.gz +0 -0
- package/dist/assets/worker-BCwwQmAD.js +1112 -0
- package/dist/compiler-module-cache.d.ts +54 -0
- package/dist/compiler-module-cache.d.ts.map +1 -0
- package/dist/cpp-object-cache.d.ts +55 -0
- package/dist/cpp-object-cache.d.ts.map +1 -0
- package/dist/debugger.d.ts +46 -0
- package/dist/debugger.d.ts.map +1 -0
- package/dist/engine-worker.d.ts +3 -0
- package/dist/engine-worker.d.ts.map +1 -0
- package/dist/engine_bg.wasm +0 -0
- package/dist/glassjar.js +2207 -0
- package/dist/glassjar.umd.cjs +2 -0
- package/dist/host-device.d.ts +35 -0
- package/dist/host-device.d.ts.map +1 -0
- package/dist/index.d.ts +249 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/stock-cache-certificates.json.d.ts +4 -0
- package/dist/toolchain-manifest.d.ts +13 -0
- package/dist/toolchain-manifest.d.ts.map +1 -0
- package/dist/util.d.ts +9 -0
- package/dist/util.d.ts.map +1 -0
- package/dist/verified-toolchain.d.ts +31 -0
- package/dist/verified-toolchain.d.ts.map +1 -0
- package/dist/wasm-source.d.ts +11 -0
- package/dist/wasm-source.d.ts.map +1 -0
- package/dist/worker.d.ts +2 -0
- package/dist/worker.d.ts.map +1 -0
- package/package.json +65 -4
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
|
-
#
|
|
1
|
+
# glassjar
|
|
2
2
|
|
|
3
|
-
|
|
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
|
+
```
|
|
Binary file
|