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 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
- # 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
+ ---
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