glassjar 0.1.0 → 0.2.1

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/README.md CHANGED
@@ -15,6 +15,22 @@ npm install glassjar
15
15
  > Cross-Origin-Opener-Policy: same-origin
16
16
  > ```
17
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
+
18
34
  ---
19
35
 
20
36
  ## Quick start
@@ -46,6 +62,12 @@ await engine.run();
46
62
 
47
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`.
48
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
+
49
71
  ---
50
72
 
51
73
  ## Full API
@@ -54,9 +76,12 @@ await engine.run();
54
76
  const engine = await Engine.create('c'); // 'c' | 'python'
55
77
 
56
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
57
81
  engine.stdout; // Stdout — .on('data', (chunk: Uint8Array) => …) / .off(...)
58
82
  engine.stderr; // Stdout
59
83
  engine.stdin; // Stdin — .write(string | Uint8Array): Promise<void>
84
+ engine.hostDevice; // Optional C/C++ and Python duplex byte device — see below
60
85
  engine.debugger; // Debugger — DAP interface; set .enabled = false to skip the handshake
61
86
  engine.lang; // Lang
62
87
 
@@ -75,6 +100,39 @@ See [Presentation filtering (Python)](./docs/integration.md#presentation-filteri
75
100
 
76
101
  ---
77
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
+
78
136
  ## Wiring stdin
79
137
 
80
138
  `engine.stdin.write()` accepts a UTF-8 string or `Uint8Array`. Programs read via `cin`, `scanf`, `read()`, etc.
@@ -86,6 +144,20 @@ await engine.stdin.write(new TextEncoder().encode('42\n'));
86
144
 
87
145
  ---
88
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
+
89
161
  ## Example project
90
162
 
91
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.
@@ -103,6 +175,17 @@ npm run build # wasm-pack build --target web && vite build
103
175
  npm run dev # local development
104
176
  ```
105
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
+
106
189
  To test against the reference IDE, clone [debugger-sh/debugger.sh](https://github.com/debugger-sh/debugger.sh) alongside this repo and link:
107
190
 
108
191
  ```bash