glassjar 0.0.0-stage → 0.1.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 +112 -2
- package/dist/debugger.d.ts +41 -0
- package/dist/debugger.d.ts.map +1 -0
- package/dist/engine_bg.wasm +0 -0
- package/dist/glassjar.js +2314 -0
- package/dist/glassjar.umd.cjs +912 -0
- package/dist/index.d.ts +112 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/util.d.ts +9 -0
- package/dist/util.d.ts.map +1 -0
- package/dist/worker.d.ts +2 -0
- package/dist/worker.d.ts.map +1 -0
- package/package.json +62 -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,113 @@
|
|
|
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
|
+
---
|
|
19
|
+
|
|
20
|
+
## Quick start
|
|
21
|
+
|
|
22
|
+
```ts
|
|
23
|
+
import { Engine } from 'glassjar';
|
|
24
|
+
|
|
25
|
+
const engine = await Engine.create('c');
|
|
26
|
+
|
|
27
|
+
// Virtual filesystem — the program sees these as real files
|
|
28
|
+
engine.fs = {
|
|
29
|
+
'main.cpp': `
|
|
30
|
+
#include <iostream>
|
|
31
|
+
int main() {
|
|
32
|
+
std::cout << "Hello, world!" << std::endl;
|
|
33
|
+
return 0;
|
|
34
|
+
}
|
|
35
|
+
`
|
|
36
|
+
};
|
|
37
|
+
|
|
38
|
+
// stdout / stderr chunks arrive as Uint8Array (UTF-8)
|
|
39
|
+
const decoder = new TextDecoder();
|
|
40
|
+
const print = (chunk: Uint8Array) => process.stdout.write(decoder.decode(chunk));
|
|
41
|
+
engine.stdout.on('data', print);
|
|
42
|
+
engine.stderr.on('data', print);
|
|
43
|
+
|
|
44
|
+
await engine.run();
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
> 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`.
|
|
48
|
+
|
|
49
|
+
---
|
|
50
|
+
|
|
51
|
+
## Full API
|
|
52
|
+
|
|
53
|
+
```ts
|
|
54
|
+
const engine = await Engine.create('c'); // 'c' | 'python'
|
|
55
|
+
|
|
56
|
+
engine.fs; // DirNode — virtual filesystem, set before run()
|
|
57
|
+
engine.stdout; // Stdout — .on('data', (chunk: Uint8Array) => …) / .off(...)
|
|
58
|
+
engine.stderr; // Stdout
|
|
59
|
+
engine.stdin; // Stdin — .write(string | Uint8Array): Promise<void>
|
|
60
|
+
engine.debugger; // Debugger — DAP interface; set .enabled = false to skip the handshake
|
|
61
|
+
engine.lang; // Lang
|
|
62
|
+
|
|
63
|
+
engine.run(); // Promise<RunResult> — { type: 'completed', exitCode } | { type: 'stopped' } | { type: 'error', error }
|
|
64
|
+
engine.stop(); // void — kills the worker; run() resolves with { type: 'stopped' }
|
|
65
|
+
|
|
66
|
+
engine.debugger.send(message); // DAP request, returns response synchronously
|
|
67
|
+
engine.debugger.on('event', fn); // async DAP events
|
|
68
|
+
engine.debugger.on('artifact', fn); // download artifacts emitted by the engine
|
|
69
|
+
|
|
70
|
+
// Python only — hide bridge/bdb frames from stackTrace (set before run())
|
|
71
|
+
engine.debugger.filterInternals = true;
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
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.
|
|
75
|
+
|
|
76
|
+
---
|
|
77
|
+
|
|
78
|
+
## Wiring stdin
|
|
79
|
+
|
|
80
|
+
`engine.stdin.write()` accepts a UTF-8 string or `Uint8Array`. Programs read via `cin`, `scanf`, `read()`, etc.
|
|
81
|
+
|
|
82
|
+
```ts
|
|
83
|
+
await engine.stdin.write('42\n');
|
|
84
|
+
await engine.stdin.write(new TextEncoder().encode('42\n'));
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
---
|
|
88
|
+
|
|
89
|
+
## Example project
|
|
90
|
+
|
|
91
|
+
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.
|
|
92
|
+
|
|
93
|
+
---
|
|
94
|
+
|
|
95
|
+
## Contributing / building from source
|
|
96
|
+
|
|
97
|
+
> Requires [Cargo 1.91+](https://crates.io/), [wasm-pack](https://rustwasm.github.io/wasm-pack/), and Node v22+.
|
|
98
|
+
|
|
99
|
+
```bash
|
|
100
|
+
cargo install wasm-pack
|
|
101
|
+
npm install
|
|
102
|
+
npm run build # wasm-pack build --target web && vite build
|
|
103
|
+
npm run dev # local development
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
To test against the reference IDE, clone [debugger-sh/debugger.sh](https://github.com/debugger-sh/debugger.sh) alongside this repo and link:
|
|
107
|
+
|
|
108
|
+
```bash
|
|
109
|
+
npm link # in this repo
|
|
110
|
+
cd ../debugger.sh
|
|
111
|
+
npm link glassjar
|
|
112
|
+
npm run dev
|
|
113
|
+
```
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
import { default as EventEmitter } from 'events';
|
|
2
|
+
import { Internals } from './util';
|
|
3
|
+
type DebuggerEventMap = {
|
|
4
|
+
event: [unknown];
|
|
5
|
+
artifact: [Artifact];
|
|
6
|
+
};
|
|
7
|
+
export declare class Artifact {
|
|
8
|
+
readonly name: string;
|
|
9
|
+
readonly data: Uint8Array;
|
|
10
|
+
constructor(name: string, data: Uint8Array);
|
|
11
|
+
download(): void;
|
|
12
|
+
}
|
|
13
|
+
export declare class Debugger extends EventEmitter<DebuggerEventMap> {
|
|
14
|
+
/**
|
|
15
|
+
* Access to internal properties of the debugger.
|
|
16
|
+
* These are put under a special symbol so that they cannot be accessed by
|
|
17
|
+
* clients of the library.
|
|
18
|
+
*/
|
|
19
|
+
[Internals]: {
|
|
20
|
+
attach(worker: Worker): void;
|
|
21
|
+
};
|
|
22
|
+
private readonly dap;
|
|
23
|
+
/**
|
|
24
|
+
* Whether or not debugging is enabled.
|
|
25
|
+
* Changes will takes effect during the next call to {@link Engine.run}.
|
|
26
|
+
*/
|
|
27
|
+
enabled: boolean;
|
|
28
|
+
/**
|
|
29
|
+
* When true, internal frames (bdb, bridge) are omitted from DAP `stackTrace`
|
|
30
|
+
* responses. Internal frames are always tagged with `presentationHint: "subtle"`
|
|
31
|
+
* regardless, so raw clients can filter themselves.
|
|
32
|
+
* Must be set before calling {@link Engine.run}.
|
|
33
|
+
*/
|
|
34
|
+
set filterInternals(value: boolean);
|
|
35
|
+
constructor();
|
|
36
|
+
send(message: unknown): unknown;
|
|
37
|
+
private attach;
|
|
38
|
+
private onMessage;
|
|
39
|
+
}
|
|
40
|
+
export {};
|
|
41
|
+
//# sourceMappingURL=debugger.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"debugger.d.ts","sourceRoot":"","sources":["../src/ts/debugger.ts"],"names":[],"mappings":"AAAA,OAAO,YAAY,MAAM,QAAQ,CAAC;AAKlC,OAAO,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AAEnC,KAAK,gBAAgB,GAAG;IACtB,KAAK,EAAE,CAAC,OAAO,CAAC,CAAC;IACjB,QAAQ,EAAE,CAAC,QAAQ,CAAC,CAAC;CACtB,CAAC;AAEF,qBAAa,QAAQ;IACnB,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,SAAgB,IAAI,EAAE,UAAU,CAAC;gBAErB,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU;IAKnC,QAAQ;CAYhB;AAED,qBAAa,QAAS,SAAQ,YAAY,CAAC,gBAAgB,CAAC;IAC1D;;;;OAIG;IACH,CAAC,SAAS,CAAC,EAAE;QACX,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;KAC9B,CAAC;IAEF,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAa;IAEjC;;;OAGG;IACI,OAAO,EAAE,OAAO,CAAQ;IAE/B;;;;;OAKG;IACH,IAAW,eAAe,CAAC,KAAK,EAAE,OAAO,EAGxC;;IAaM,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO;IAKtC,OAAO,CAAC,MAAM;IASd,OAAO,CAAC,SAAS;CAGlB"}
|
|
Binary file
|