GLASSBOX

A program, made visible. Demo 03 of Matthew Berman’s AI capability showcase.

GLASSBOX is a complete, local compiler workbench. The source editor feeds a handwritten lexer, recursive-descent parser, lexical compiler, and bounded stack VM. The token stream, syntax tree, bytecode, operand stack, variables, call frames, execution trace, and canvas all come from the current program. There is no eval, host-language code generation, network dependency, model call, or simulated compiler output.

Launch

Requires Node.js 20+ and Python 3. No dependency installation is necessary.

cd /Users/matthewberman/Documents/Codex/2026-09-02/demo-03-glassbox/outputs/glassbox
npm run build
npm start

Open http://localhost:43103. The server binds only to 127.0.0.1, refuses to choose a different port, and serves the built dist/ directory. Keep one server. If it is already running, reuse it. The build command uses the showcase’s shared resource-slot wrapper.

Single-line launch command:

cd /Users/matthewberman/Documents/Codex/2026-09-02/demo-03-glassbox/outputs/glassbox && npm run build && npm start

For a copy outside this showcase environment, the dependency-free build itself is node scripts/build.mjs; the resource wrapper path in package.json is specific to this machine.

A 60-second demonstration

  1. 0–15 seconds: Click Watch a program come alive. Follow actual source through tokens, syntax, and bytecode. Watch the sunflower grow as the VM executes drawing calls.
  2. 15–25 seconds: Click Edit the angle, replace 137.5 with 127, and stop typing. Auto-run rebuilds and redraws the pattern. Select Tokens or Tree to see the changed value in the compilation.
  3. 25–35 seconds: Drag the time travel slider toward the beginning. Shapes disappear while variables, operands, and the trace rewind. Click Run to continue from that state, or the rightmost history button to return to the latest checkpoint.
  4. 35–50 seconds: Select Case 01: the extra bar. The canvas has six bars although the brief asks for five. Click Break at loop, inspect i and bars, then use Run to revisit the loop condition. At i = 5, i <= bars still admits a sixth iteration. The optional hint explains this boundary.
  5. 50–60 seconds: Remove the breakpoint by clicking line 6, replace <= with <, and let auto-run finish. The output becomes 5, the sixth bar disappears, and the debugger case reports the fix.

For the safety demonstration, select Case 02: the runaway loop. It stops at exactly 60,000 instructions with a source-linked diagnostic. Change true to ticks < 240 and run again.

Controls

Action Control
Run / pause Run button; Command / Control + Enter
Pause immediately Escape
One bytecode instruction Step; F9
Next source statement Step line; F10
Reset execution, keeping source Reset; Shift + F10
Breakpoint Click any source line number; execution stops at executable statement markers
Rewind Timeline, history arrows, or a retained trace entry
Restore original program Restore in the editor header
Inspect a caller’s locals In scope → Inspect call frame
Indent Control + ] inserts two spaces; Tab stays available for focus navigation
Export a drawing Arrow in the Live canvas header; downloads a PNG

Auto-run edits compiles after 280 ms of inactivity and respects breakpoints. Turning it off still recompiles valid source but leaves the VM ready to step. Editing invalid source clears stale compiled output and shows a diagnostic. Reset never changes source; Restore reloads the original example.

Five studies and two debugger cases

Program Language feature Default result
Phyllotaxis Variables, loops, polar coordinates 240 sunflower seeds
Harmonic weave Functions, arithmetic, trigonometry 360 connected line segments
Recursive canopy Recursion, lexical globals, early return 255 branches
Orbital notation Nested loops and rotation 657 points across nine ellipses
Signal garden Branches, strict booleans, short circuit 529 grid marks
The extra bar An intentionally incorrect inclusive boundary Six bars; edit the comparison to get five
The runaway loop An intentionally unbounded loop A safe instruction-budget error

Validation

npm test
npm run check

The behavioral suite covers precedence, right-associative power, short circuit and side effects, lexical scope, nested branching/loops, hoisted and recursive calls, call arity, early return, unknown names, invalid syntax locations, runtime types, finite arithmetic, instruction/call/drawing/output bounds, breakpoints, frame yielding, reset, snapshot immutability, coalesced-history replay, all five studies, and the intentional debugger cases. Browser QA evidence and screenshots are recorded in QA.md and the demo manifest.

Read the implementation

The Under the glass dialog contains a source-linked architecture diagram. Source and tests are served locally with the app.

Deliberate limits

Glass has numbers, booleans, and strings. It has no arrays, objects, imports, closures, input devices, files, networking, or mutable host objects. Functions are top-level and access their lexical globals. Strings support output and colors; arithmetic does not concatenate them.

Execution is limited to 60,000 instructions, 32 call frames, 2,000 active shapes, and 300 printed values. Source has character, token, and nesting limits. At most 1,600 exact snapshots are retained; old checkpoints are progressively sampled, so every historical instruction is not available after a long run. Resuming in the past intentionally discards the future. The VM is cooperative on the browser thread in small batches, not a worker. The drawing grid is a renderer reference overlay, not program-generated geometry.

Edits and runtime state last for the current page session; refreshing restores the first study. Nothing is uploaded or published. Local completion is a request for the showcase coordinator’s acceptance.

# GLASSBOX

A program, made visible. Demo 03 of Matthew Berman’s AI capability showcase.

GLASSBOX is a complete, local compiler workbench. The source editor feeds a handwritten lexer, recursive-descent parser, lexical compiler, and bounded stack VM. The token stream, syntax tree, bytecode, operand stack, variables, call frames, execution trace, and canvas all come from the current program. There is no `eval`, host-language code generation, network dependency, model call, or simulated compiler output.

## Launch

Requires Node.js 20+ and Python 3. No dependency installation is necessary.

```sh
cd /Users/matthewberman/Documents/Codex/2026-09-02/demo-03-glassbox/outputs/glassbox
npm run build
npm start
```

Open **http://localhost:43103**. The server binds only to `127.0.0.1`, refuses to choose a different port, and serves the built `dist/` directory. Keep one server. If it is already running, reuse it. The build command uses the showcase’s shared resource-slot wrapper.

Single-line launch command:

```sh
cd /Users/matthewberman/Documents/Codex/2026-09-02/demo-03-glassbox/outputs/glassbox && npm run build && npm start
```

For a copy outside this showcase environment, the dependency-free build itself is `node scripts/build.mjs`; the resource wrapper path in `package.json` is specific to this machine.

## A 60-second demonstration

1. **0–15 seconds:** Click **Watch a program come alive**. Follow actual source through tokens, syntax, and bytecode. Watch the sunflower grow as the VM executes drawing calls.
2. **15–25 seconds:** Click **Edit the angle**, replace `137.5` with `127`, and stop typing. Auto-run rebuilds and redraws the pattern. Select **Tokens** or **Tree** to see the changed value in the compilation.
3. **25–35 seconds:** Drag the **time travel** slider toward the beginning. Shapes disappear while variables, operands, and the trace rewind. Click **Run** to continue from that state, or the rightmost history button to return to the latest checkpoint.
4. **35–50 seconds:** Select **Case 01: the extra bar**. The canvas has six bars although the brief asks for five. Click **Break at loop**, inspect `i` and `bars`, then use Run to revisit the loop condition. At `i = 5`, `i <= bars` still admits a sixth iteration. The optional hint explains this boundary.
5. **50–60 seconds:** Remove the breakpoint by clicking line 6, replace `<=` with `<`, and let auto-run finish. The output becomes `5`, the sixth bar disappears, and the debugger case reports the fix.

For the safety demonstration, select **Case 02: the runaway loop**. It stops at exactly 60,000 instructions with a source-linked diagnostic. Change `true` to `ticks < 240` and run again.

## Controls

| Action | Control |
| --- | --- |
| Run / pause | Run button; Command / Control + Enter |
| Pause immediately | Escape |
| One bytecode instruction | Step; F9 |
| Next source statement | Step line; F10 |
| Reset execution, keeping source | Reset; Shift + F10 |
| Breakpoint | Click any source line number; execution stops at executable statement markers |
| Rewind | Timeline, history arrows, or a retained trace entry |
| Restore original program | Restore in the editor header |
| Inspect a caller’s locals | In scope → Inspect call frame |
| Indent | Control + ] inserts two spaces; Tab stays available for focus navigation |
| Export a drawing | Arrow in the Live canvas header; downloads a PNG |

Auto-run edits compiles after 280 ms of inactivity and respects breakpoints. Turning it off still recompiles valid source but leaves the VM ready to step. Editing invalid source clears stale compiled output and shows a diagnostic. Reset never changes source; Restore reloads the original example.

## Five studies and two debugger cases

| Program | Language feature | Default result |
| --- | --- | --- |
| Phyllotaxis | Variables, loops, polar coordinates | 240 sunflower seeds |
| Harmonic weave | Functions, arithmetic, trigonometry | 360 connected line segments |
| Recursive canopy | Recursion, lexical globals, early return | 255 branches |
| Orbital notation | Nested loops and rotation | 657 points across nine ellipses |
| Signal garden | Branches, strict booleans, short circuit | 529 grid marks |
| The extra bar | An intentionally incorrect inclusive boundary | Six bars; edit the comparison to get five |
| The runaway loop | An intentionally unbounded loop | A safe instruction-budget error |

## Validation

```sh
npm test
npm run check
```

The behavioral suite covers precedence, right-associative power, short circuit and side effects, lexical scope, nested branching/loops, hoisted and recursive calls, call arity, early return, unknown names, invalid syntax locations, runtime types, finite arithmetic, instruction/call/drawing/output bounds, breakpoints, frame yielding, reset, snapshot immutability, coalesced-history replay, all five studies, and the intentional debugger cases. Browser QA evidence and screenshots are recorded in [QA.md](QA.md) and the demo manifest.

## Read the implementation

- [Language reference](docs/LANGUAGE.md)
- [Architecture and invariants](docs/ARCHITECTURE.md)
- [Lexer](src/language/lexer.js), [parser](src/language/parser.js), [compiler](src/language/compiler.js), [VM](src/language/vm.js)
- [Drawing and math builtins](src/language/builtins.js), [canvas renderer](src/renderer.js)
- [Workbench controller](src/app.js), [examples](src/examples.js), [behavioral tests](tests/language.test.mjs)

The **Under the glass** dialog contains a source-linked architecture diagram. Source and tests are served locally with the app.

## Deliberate limits

Glass has numbers, booleans, and strings. It has no arrays, objects, imports, closures, input devices, files, networking, or mutable host objects. Functions are top-level and access their lexical globals. Strings support output and colors; arithmetic does not concatenate them.

Execution is limited to 60,000 instructions, 32 call frames, 2,000 active shapes, and 300 printed values. Source has character, token, and nesting limits. At most 1,600 exact snapshots are retained; old checkpoints are progressively sampled, so every historical instruction is not available after a long run. Resuming in the past intentionally discards the future. The VM is cooperative on the browser thread in small batches, not a worker. The drawing grid is a renderer reference overlay, not program-generated geometry.

Edits and runtime state last for the current page session; refreshing restores the first study. Nothing is uploaded or published. Local completion is a request for the showcase coordinator’s acceptance.