Java-Chan Interpreter — Architecture & Build Plan

Branch: feature/java-interpreter
Tagged baseline: v1.0 (Phase 1 — 75 lessons, pattern-based validation, full cosmetics)
Author: Alberto Felix Status: Active Development — Tasks 1–9 complete (interpreter core done, SandboxEditor wired, Milestone 1 fixtures green); Task 10a complete (sandbox mode props + close button fix); editor features complete (syntax highlighting, bracket auto-pair, auto-indent, Tab key). Direction change after Task 9 — lesson migration (Task 10) replaced by the Global Sandbox. See Current Task Queue and Direction Change: The Global Sandbox.

Why This Exists

Java-Chan's Phase 1 validation is pattern-based. patternMatcher.js and blankValidator.js check whether student code contains the right keywords or fills in the right blanks. This works — and it ships fast and offline — but it has a ceiling.

The ceiling: a student can write System.out.println("hello") and pass Phase 3 even if the surrounding logic is completely wrong. We're checking structure, not behavior. We're validating that the student typed the right words, not that the code actually does what it's supposed to do.

The goal of this update is to build a Java subset interpreter in JavaScript — a real executor that lives entirely in the browser, has zero external dependencies, needs no server, and runs the student's code against a real output expectation. When a student's for loop produces 1 2 3 4 5 but the expected output is 0 1 2 3 4, Java-Chan knows. She can say so. She reacts accordingly.

This is not a JVM. It is not a compiler. It is a tree-walking interpreter that supports a carefully chosen subset of Java — exactly the subset that appears in the CS22301 curriculum across Units 1 through 4. That scope limitation is intentional and is a product decision, not a shortcut. JavaFX (Unit 5) and multithreading (Unit 4 later lessons) are explicitly out of scope for reasons explained below.

What a Tree-Walking Interpreter Is

For contributors who haven't built one before, here's the mental model.

A tree-walking interpreter works in three stages:

Source code (string)
      ↓
  [ LEXER ]  →  Token stream
      ↓
  [ PARSER ] →  Abstract Syntax Tree (AST)
      ↓
[ EVALUATOR] →  Output / side effects

The Lexer (also called a tokenizer) reads raw characters and groups them into meaningful tokens. int x = 5 + 3; becomes [KEYWORD(int), IDENTIFIER(x), EQUALS, NUMBER(5), PLUS, NUMBER(3), SEMICOLON]. It doesn't understand what the code means — it just recognizes shapes.

The Parser reads the token stream and builds a tree that represents the code's structure. 5 + 3 becomes a BinaryExpression node with a left child NumberLiteral(5), an operator +, and a right child NumberLiteral(3). The tree captures nesting, operator precedence, and block scoping that a flat token list can't express.

The Evaluator walks the AST recursively and executes each node. It knows that a BinaryExpression with operator + means "evaluate the left side, evaluate the right side, add them." It tracks variables in an environment (a scope chain — a map from name to value). It handles control flow by deciding which branches of the tree to walk. It captures everything sent to System.out.println and assembles it into an output string that the UI can compare to expectedOutput.

This is called "tree-walking" because the evaluator literally walks the tree — visits each node, evaluates it, moves to children, returns a value up the chain.

The canonical reference for building exactly this is Robert Nystrom's Crafting Interpreters (free at craftinginterpreters.com). The "Lox" language he builds is a dynamically-typed scripting language, but the architecture is identical to what we're building here. Reading Part I (the tree-walking interpreter) is strongly recommended before touching any code in this module.

Scope: What Gets Interpreted

This is the most important design decision in the whole document. We do not try to interpret all of Java. We interpret the Java that appears in Java-Chan's lessons. The curriculum drives the interpreter's feature set, not the other way around.

In Scope — Unit 1 (OOP & Java Fundamentals)

These features are needed from day one. Every lesson in Unit 1 that has a Phase 3 coding exercise uses some combination of these.

Feature	Example	Notes
Primitive types	`int`, `double`, `boolean`, `char`	Full value semantics
String literals	`"Hello"`	Immutable, concatenation via `+`
Variable declaration & assignment	`int x = 5;`	Typed declarations, no inference
Arithmetic operators	`+`, `-`, `*`, `/`, `%`	Integer and double
Comparison operators	`==`, `!=`, `<`, `>`, `<=`, `>=`	Returns boolean
Logical operators	`&&`, `\|\|`, `!`	Short-circuit evaluation
String concatenation	`"Age: " + age`	Mixed-type `+` where one side is String
`if` / `else if` / `else`	Standard branching	Nested supported
`switch` / `case` / `break` / `default`	Integer and String switches	Fall-through supported
`for` loop	`for (int i = 0; i < 10; i++)`	Classic three-part form
Enhanced for-each	`for (int n : array)`	1D arrays; `break`/`continue` supported
`while` loop	`while (condition)`	Standard
`do-while` loop	`do { } while (condition)`	Standard
`break` / `continue`	Loop control	Both supported
1D arrays	`int[] arr = new int[5];`	Fixed size, index access
Array initializer	`int[] arr = {1, 2, 3};`	1D and 2D initializer syntax
2D arrays	`int[][] grid = new int[3][3];`	Row/column access
`System.out.println`	Standard output	Newline after
`System.out.print`	Standard output	No newline
Static method declaration	`static int add(int a, int b)`	Within the main class
Static method calls	`add(5, 3)`	Within the same class
Return values	`return result;`	All primitive and String types
Type casting	`(int) 3.7`	Explicit narrowing casts
Ternary operator	`condition ? a : b`	Right-associative; nesting supported
`Math` methods	`Math.PI`, `Math.sqrt()`, `Math.abs()`, `Math.max()`, `Math.min()`, `Math.pow()`	Static method dispatch

In Scope — Unit 2 (Inheritance & Interfaces), Phase 2 of Interpreter

These features come after the scripting subset is stable. They are harder — they require the interpreter to model an object system.

Feature	Notes
Class definitions with fields	Instance variables typed and declared
Constructors	`new ClassName(args)`
Instance method calls	`obj.method()`
`this` keyword	Refers to the current object
Inheritance (`extends`)	Single inheritance, no diamond problem
`super()` constructor call	Delegating to parent constructor
Method overriding	Dynamic dispatch — the child's version runs
`instanceof`	Type checking expression
Static members	`static` fields and methods
`final` keyword	Constants
Enums	Simple value enums, no methods

Explicitly Out of Scope (Forever)

These features will never be interpreted by this engine. When a lesson involves them, the old pattern-matching / fill-in-the-blank validation handles Phase 3, and Phase 4 self-challenge handles the "try it in your own IDE" piece.

Feature	Why
Multithreading (`Thread`, `synchronized`, `Executor`)	Cannot be safely modeled in a single-threaded JS environment. Race conditions, deadlocks, and timing-dependent behavior have no faithful representation.
JavaFX / Swing / AWT	GUI rendering requires a display context. Out of scope by design — these lessons use the self-challenge model.
File I/O (`FileReader`, `FileWriter`, `Scanner` with files)	No filesystem access in browser sandbox.
`Scanner` with `System.in`	Interactive stdin is out of scope. Lessons that need user input will use pre-seeded input values specified in lesson JSON.
Serialization	No meaningful browser equivalent.
Networking	Out of scope.
Reflection	Too deep — requires runtime type metadata the interpreter doesn't track.
Generics (beyond syntax tolerance)	The interpreter ignores generic type parameters (`<T>`) — they parse but carry no semantic weight.
Exception handling (`try/catch/finally/throw`)	Phase 2 target. The interpreter will surface runtime errors as interpreter errors, not as catchable Java exceptions.
Anonymous classes / lambdas	Complex parse surface for low curriculum coverage.

Architecture: File Structure

All interpreter code lives in a new directory: src/interpreter/. It is completely self-contained. Nothing in the existing codebase changes to add interpreter support — the integration is additive.

src/
├── interpreter/
│   ├── index.js              ← public API — the only file the rest of the app touches
│   ├── Lexer.js              ← tokenizer: source string → token array
│   ├── Parser.js             ← token array → AST
│   ├── Evaluator.js          ← AST → output + side effects
│   ├── Environment.js        ← scope chain for variable lookup
│   ├── JavaObject.js         ← runtime representation of a Java object (Phase 2)
│   ├── StandardLibrary.js    ← Math, String methods, System.out
│   ├── InterpreterError.js   ← structured error type (runtime vs compile-time)
│   └── __tests__/
│       ├── lexer.test.js
│       ├── parser.test.js
│       ├── evaluator.test.js
│       └── fixtures/         ← sample Java snippets for test cases
│
├── components/
│   └── lesson/
│       ├── SandboxEditor.jsx   ← NEW: full-code editor panel for interpreter lessons
│       └── SandboxEditor.css
│
├── utils/
│   └── patternMatcher.js     ← UNCHANGED — still handles MCQ and fill-in-the-blank
│
└── data/
    └── lessons/              ← lesson JSON gets new optional fields (see below)

`src/interpreter/index.js` — the public API

This is the only file LessonCanvas or any other component ever imports from the interpreter. Everything else is internal.

/**
 * run(sourceCode, options) → ExecutionResult
 *
 * @param {string} sourceCode    — the Java source string to execute
 * @param {object} options
 * @param {string[]} [options.stdin]  — pre-seeded input lines for Scanner
 * @param {number}  [options.timeout] — max execution time in ms (default: 3000)
 *
 * @returns {ExecutionResult}
 * {
 *   stdout: string,         — everything printed via System.out
 *   stderr: string,         — compiler/runtime error message if any
 *   success: boolean,       — true if execution completed without error
 *   errorType: string|null, — 'LexError' | 'ParseError' | 'RuntimeError' | null
 *   errorLine: number|null, — line number of the error, if known
 * }
 */
export function run(sourceCode, options = {}) { ... }

That's the entire contract. run() in, ExecutionResult out. No state. No side effects outside the return value. Pure function.

Architecture: The Three Modules in Detail

1. Lexer (`Lexer.js`)

The lexer takes a source string and returns an array of Token objects.

Token shape:

{ type: TokenType, value: any, line: number }

Token types to implement (exhaustive for Phase 1 scope):

// Literals
NUMBER, STRING, BOOLEAN, NULL, CHAR,

// Identifiers & keywords
IDENTIFIER,
KEYWORD_INT, KEYWORD_DOUBLE, KEYWORD_BOOLEAN, KEYWORD_CHAR,
KEYWORD_STRING, KEYWORD_VOID, KEYWORD_RETURN,
KEYWORD_IF, KEYWORD_ELSE, KEYWORD_FOR, KEYWORD_WHILE, KEYWORD_DO,
KEYWORD_BREAK, KEYWORD_CONTINUE,
KEYWORD_NEW, KEYWORD_CLASS, KEYWORD_STATIC, KEYWORD_PUBLIC,
KEYWORD_PRIVATE, KEYWORD_FINAL, KEYWORD_THIS, KEYWORD_SUPER,
KEYWORD_EXTENDS, KEYWORD_IMPLEMENTS, KEYWORD_INTERFACE,
KEYWORD_SWITCH, KEYWORD_CASE, KEYWORD_DEFAULT,
KEYWORD_NULL, KEYWORD_TRUE, KEYWORD_FALSE,

// Operators
PLUS, MINUS, STAR, SLASH, PERCENT,
EQUALS, EQUALS_EQUALS, BANG_EQUALS, BANG,
LESS, LESS_EQUALS, GREATER, GREATER_EQUALS,
AND_AND, PIPE_PIPE,
PLUS_EQUALS, MINUS_EQUALS, STAR_EQUALS, SLASH_EQUALS,
PLUS_PLUS, MINUS_MINUS,

// Delimiters
LEFT_PAREN, RIGHT_PAREN,
LEFT_BRACE, RIGHT_BRACE,
LEFT_BRACKET, RIGHT_BRACKET,
SEMICOLON, COMMA, DOT, COLON, QUESTION,

// Meta
EOF

The lexer skips whitespace and comments (// and /* */). It tracks the current line number so every token carries a line for error reporting.

Key implementation notes:

String literals need escape handling: \", \\, \n, \t
Char literals use single quotes: 'A', '\n'
Numbers: distinguish int from double by the presence of . in the literal
++ and -- are single tokens, not two PLUS tokens — order of matching matters
Keywords are recognized by checking the identifier's value against a Set after lexing it as an IDENTIFIER

2. Parser (`Parser.js`)

The parser takes the token array and returns an AST. The root node of a well-formed Java-Chan program is always a Program node containing a list of class declarations.

AST node types (Phase 1 scope):

Program
  └── ClassDeclaration (name, members[])
        └── MethodDeclaration (name, params[], returnType, body)
              └── BlockStatement (statements[])
                    ├── VariableDeclaration (type, name, initializer?)
                    ├── AssignmentStatement (target, operator, value)
                    ├── ExpressionStatement (expression)
                    ├── IfStatement (condition, thenBranch, elseBranch?)
                    ├── ForStatement (init, condition, update, body)
                    ├── EnhancedForStatement (varType, varName, iterable, body)
                    ├── WhileStatement (condition, body)
                    ├── DoWhileStatement (body, condition)
                    ├── SwitchStatement (discriminant, cases[])
                    ├── ReturnStatement (value?)
                    ├── BreakStatement
                    └── ContinueStatement

Expression nodes:
  BinaryExpression (left, operator, right)
  UnaryExpression (operator, operand, prefix)
  LogicalExpression (left, operator, right)
  TernaryExpression (condition, consequent, alternate)
  AssignmentExpression (target, operator, value)
  CallExpression (callee, args[])
  MemberExpression (object, property)
  ArrayAccessExpression (array, index)
  ArrayCreationExpression (type, size)
  ArrayInitializerExpression (elements[])
  NewExpression (className, args[])
  CastExpression (type, expression)
  Identifier (name)
  NumberLiteral (value)
  StringLiteral (value)
  BooleanLiteral (value)
  CharLiteral (value)
  NullLiteral

The parser uses recursive descent — one function per grammar rule, each calling downward into the rules it depends on. Operator precedence is handled by the ordering of expression parsing functions (assignment → logical-or → logical-and → equality → comparison → addition → multiplication → unary → postfix → primary), not by a precedence table. This is the standard approach and produces very readable code.

Key implementation notes:

The parser must handle both int x = 5; (declaration) and x = 5; (assignment) — these look identical in the first few tokens and need lookahead to distinguish
Type names (int, String, int[]) are parsed as a distinct TypeAnnotation node, not as expressions
System.out.println(...) parses as a chain of member accesses ending in a call: MemberExpression(MemberExpression(Identifier("System"), "out"), "println") — the evaluator recognizes this pattern and routes it to the standard library
Array declarations: int[] arr = new int[5] — the [] after the type is part of the type node, and new int[5] is an ArrayCreationExpression
Generic type parameters (ArrayList<String>) are parsed and attached to the type node but carry no semantic weight in Phase 1 — the evaluator ignores them

3. Evaluator (`Evaluator.js`)

The evaluator walks the AST and executes it. It maintains an Environment (scope chain) and captures output.

Environment (Environment.js):

class Environment {
  constructor(parent = null) {
    this.vars = new Map();
    this.parent = parent;      // enclosing scope
  }

  get(name) {
    if (this.vars.has(name)) return this.vars.get(name);
    if (this.parent) return this.parent.get(name);
    throw new InterpreterError(`Variable '${name}' is not defined`, 'RuntimeError');
  }

  set(name, value) {
    if (this.vars.has(name)) { this.vars.set(name, value); return; }
    if (this.parent) { this.parent.set(name, value); return; }
    throw new InterpreterError(`Variable '${name}' is not defined`, 'RuntimeError');
  }

  define(name, value) {
    this.vars.set(name, value);   // always defines in current scope
  }
}

When entering a block ({}), a new child Environment is created. When leaving, it's discarded. This gives correct block scoping without any manual cleanup.

Execution control (break/continue/return):

Java's break, continue, and return are non-local control flow — they jump out of the middle of recursive evaluation. The standard approach is to use a sentinel value (a special JS object) that propagates up the call stack until something catches it:

const BREAK_SIGNAL    = { __signal: 'break' };
const CONTINUE_SIGNAL = { __signal: 'continue' };
class ReturnSignal { constructor(value) { this.value = value; } }

When the evaluator encounters break, it returns BREAK_SIGNAL. The for-loop evaluator checks its result after each iteration and exits if it sees BREAK_SIGNAL. Same for continue. return works the same way — the ReturnSignal carries the return value and propagates up until the method-call evaluator catches it and unwraps .value.

Timeout protection:

Student code can contain infinite loops. The evaluator must not hang the browser tab. The approach: track an operation counter that increments on every statement execution and every loop iteration. If it exceeds a configurable threshold (default: 100,000 operations), throw a RuntimeError with message "Execution timed out — check for an infinite loop." Java-Chan reacts with her frustrated expression.

class Evaluator {
  constructor(options = {}) {
    this.output = [];
    this.opCount = 0;
    this.opLimit = options.timeout || 100_000;
  }

  tick() {
    this.opCount++;
    if (this.opCount > this.opLimit) {
      throw new InterpreterError(
        "Execution timed out — check for an infinite loop~ 😓",
        'RuntimeError'
      );
    }
  }
}

Call this.tick() at the top of every loop iteration and every statement evaluation.

Standard Library (StandardLibrary.js):

Rather than trying to implement a real Java standard library, we implement only the methods that appear in CS22301 lessons. The standard library is a plain JS object that the evaluator consults when it sees a CallExpression on a known receiver.

⚠️ Doc outdated vs implementation (Task 6 done): The pseudocode below shows raw JS values as arguments. The real StandardLibrary.js uses JavaValue wrappers ({ value, javaType }) throughout — all args arrive as JavaValues, all return values are JavaValues, and javaToString reads .javaType to format correctly. The mkInt/mkDouble/etc. constructors and raw() helper are exported from StandardLibrary.js. See the source file for the canonical implementation.

export const STD = {
  'System.out.println': (args, output) => {
    output.push(args.map(javaToString).join('') + '\n');
  },
  'System.out.print': (args, output) => {
    output.push(args.map(javaToString).join(''));
  },
  'Math.sqrt':  ([x]) => Math.sqrt(x),
  'Math.abs':   ([x]) => Math.abs(x),
  'Math.max':   ([a, b]) => Math.max(a, b),
  'Math.min':   ([a, b]) => Math.min(a, b),
  'Math.pow':   ([a, b]) => Math.pow(a, b),
  'Math.floor': ([x]) => Math.floor(x),
  'Math.ceil':  ([x]) => Math.ceil(x),
  'Math.round': ([x]) => Math.round(x),
  'String.valueOf': ([x]) => javaToString(x),
  // String instance methods — called as obj.method()
  '.length':    (str) => str.length,
  '.charAt':    (str, [i]) => str[i] ?? '',
  '.substring': (str, [a, b]) => b !== undefined ? str.slice(a, b) : str.slice(a),
  '.toUpperCase': (str) => str.toUpperCase(),
  '.toLowerCase': (str) => str.toLowerCase(),
  '.equals':    (str, [other]) => str === other,
  '.contains':  (str, [sub]) => str.includes(sub),
  '.trim':      (str) => str.trim(),
  '.indexOf':   (str, [sub]) => str.indexOf(sub),
  '.replace':   (str, [from, to]) => str.split(from).join(to),
};

// Java's string conversion rules:
// null → "null", boolean → "true"/"false", char → single char, etc.
function javaToString(val) {
  if (val === null) return 'null';
  if (val === true) return 'true';
  if (val === false) return 'false';
  if (typeof val === 'number') {
    // Java prints integers without decimal: 5 not 5.0
    // But doubles with decimal: 5.0 not 5
    // We track type through evaluation to handle this correctly
    return String(val);
  }
  return String(val);
}

Math.PI is a field access, not a method call — the evaluator recognizes MemberExpression(Identifier("Math"), "PI") and returns Math.PI.

Integration with the Existing App

This is the most careful part. The interpreter must integrate without breaking anything in Phase 1.

New field in lesson JSON: `executionMode`

A lesson opts into interpreter execution by adding a field to its phase3:

"phase3": {
  "executionMode": true,
  "scaffoldCode": "public class Main {\n    public static void main(String[] args) {\n        // your code here\n    }\n}",
  "expectedOutput": "Hello, World!\n",
  "openingDialogue": "Alright, write it yourself this time~"
}

When executionMode is absent or false, Phase 3 behaves exactly as it does today — ScaffoldEditor with fill-in-the-blank inputs, validated by blankValidator.js. When it's true, Phase 3 renders SandboxEditor instead, and validation goes through src/interpreter/index.js.

No existing lessons change behavior. The executionMode field is opt-in. Every lesson without it continues to work exactly as before. The rollout is additive.

New component: `SandboxEditor.jsx`

SandboxEditor replaces ScaffoldEditor for interpreter-mode lessons. It renders:

A <textarea> (or Monaco Editor if we add it later) pre-filled with phase3.scaffoldCode
A Run button
An Output panel showing stdout from the interpreter
An Error panel showing stderr if execution failed
A validation feedback strip (same CSS classes as the existing .validation-feedback strip in LessonCanvas)

The Run button calls run(sourceCode) from src/interpreter/index.js, gets back an ExecutionResult, and:

If success is false → show stderr in the error panel, set Java-Chan's expression to oops or frustrated depending on attempt count
If success is true but stdout.trim() !== expectedOutput.trim() → show both outputs side-by-side ("Expected: ... / Got: ..."), set expression to thinking
If success is true and output matches → passed, play success sound, award XP, advance to Phase 4 — exactly the same path as a correct blank submission today

Changes to `LessonCanvas.jsx`

One new conditional inside the Phase 3 block:

{currentPhase === 3 && (
  <motion.div ...>
    <h2 className="phase-heading phase-heading--try">✎ Code It With Me</h2>

    {phase3?.executionMode ? (
      <SandboxEditor
        scaffoldCode={phase3.scaffoldCode}
        expectedOutput={phase3.expectedOutput}
        onPass={handleSandboxPass}
      />
    ) : hasBlanks ? (
      <ScaffoldEditor ... />   {/* existing, unchanged */}
    ) : (
      <div className="scaffold-stub-notice">...</div>   {/* existing, unchanged */}
    )}
  </motion.div>
)}

handleSandboxPass is a new handler that mirrors handleSubmitBlanks's success path — records attempts, calculates XP, calls completeLesson, advances to Phase 4.

No changes to:

patternMatcher.js — still used for Phase 4 MCQ
blankValidator.js — still used for fill-in-the-blank Phase 3 lessons
progressStore.js — no changes; completeLesson and recordAttempt are reused as-is
xpCalculator.js — no changes; calculateEarnedXP is reused as-is
lessonStore.js — no changes
javaHighlighter.js — Phase 1 and 2 code display is unaffected
All existing lesson JSON files

Direction Change: The Global Sandbox

After Task 9, the team reviewed the lesson migration plan and made a product decision: lessons will not be migrated to executionMode. The reasons, documented for future contributors:

Why the migration plan was dropped:

Every Unit 1 lesson was designed for fill-in-the-blank. The scaffold code targets token recall — "what keyword goes here?" — not behavioral output. Forcing those lessons into executionMode would require rewriting their scaffold code entirely, which is content surgery, not engineering. It risks breaking what already works, and the pedagogical value is unclear: a student who fills in i++ correctly and a student who writes a working loop body are being tested on different skills. Conflating them serves neither.

The interpreter is also a living piece of code — it will keep growing as more Java features are added. Tying every growth step to lesson migration creates a dependency chain where the interpreter can't improve without triggering a content review cycle. That's a bad coupling.

The new direction:

The interpreter becomes a Global Sandbox — a floating scratchpad available everywhere in the app, not tied to any lesson. Students can open it at any time, write whatever Java they want (within interpreter scope), and run it. No expected output, no validation, no XP. Just a place to experiment.

This solves the original problem better than lesson migration did: students can test code while studying a lesson, without the lesson needing to change. The interpreter keeps improving — every new feature just makes the sandbox more capable. The lessons stay stable.

Global Sandbox — Design & Implementation Options

The sandbox is a floating panel accessible from anywhere in the app via a persistent trigger button. It reuses SandboxEditor.jsx (already built in Task 8) with the lesson-validation wiring removed.

UI placement options

Three reasonable approaches — pick one before starting Task 10:

Option A — Floating action button (FAB) + modal overlay A </> or terminal icon button fixed to the bottom-right corner of the screen, outside all route components. Clicking it opens a full-screen or large modal overlay with the sandbox inside. Closing the modal returns the user exactly where they were. This is the most mobile-friendly option and the least likely to interfere with existing layouts.

┌─────────────────────────────────┐
│         App (any route)         │
│                                 │
│                           [</>] │  ← fixed FAB, always visible
└─────────────────────────────────┘

On click:
┌─────────────────────────────────┐
│  ╔═══════════════════════════╗  │
│  ║   Java Sandbox      [✕]  ║  │
│  ║  ┌─────────────────────┐ ║  │
│  ║  │  code editor        │ ║  │
│  ║  └─────────────────────┘ ║  │
│  ║  [Run]                   ║  │
│  ║  ┌─────────────────────┐ ║  │
│  ║  │  output             │ ║  │
│  ║  └─────────────────────┘ ║  │
│  ╚═══════════════════════════╝  │
└─────────────────────────────────┘

Option B — Slide-in drawer A panel that slides in from the right (or bottom on mobile), covering part of the screen without fully obscuring the lesson beneath. The student can still see their lesson content while the sandbox is open. Better for reference use ("let me just quickly test this").

┌──────────────────┬──────────────┐
│   Lesson content │ Java Sandbox │  ← drawer slides in from right
│   (still visible)│  code editor │
│                  │  [Run]       │
│                  │  output      │
└──────────────────┴──────────────┘

Option C — Dedicated route /sandbox A full-page sandbox accessible via the main nav. No floating button — the student navigates to it like any other page. Simplest to implement, but breaks the "always accessible" requirement — the student has to leave their lesson to use it.

Recommendation: Option A (FAB + modal) for the initial implementation. It's the least invasive to the existing layout, works on both desktop and mobile, and can be upgraded to Option B later if students prefer the side-by-side feel. Option C can exist in parallel as a dedicated route for power users once the FAB version is stable.

Component architecture

The sandbox panel is a new top-level component — not part of any route:

src/
├── components/
│   └── sandbox/
│       ├── GlobalSandbox.jsx     ← the modal/drawer shell + open/close state
│       ├── GlobalSandbox.css
│       └── SandboxTrigger.jsx    ← the FAB button (renders the trigger only)

SandboxEditor.jsx (already in src/components/lesson/) is reused as-is for the editor + output panel. GlobalSandbox.jsx wraps it without passing expectedOutput or onPass — those props become optional in SandboxEditor, and when absent, the validation strip is hidden and "Run" just shows output.

GlobalSandbox is rendered once at the app-shell level (in App.jsx or the root layout), so it persists across route changes. Its open/close state lives in a lightweight Zustand store slice or simple React context — not in progressStore or lessonStore, since it has nothing to do with lesson progress.

State the sandbox needs to preserve

Editor content — the code the student was working on. Should survive route navigation (the store holds it). Optionally persisted to localStorage so it survives page refresh.
Output — last run result. Cleared on editor change or explicitly by a Clear button.
Open/closed state — in the store, so it can be toggled from multiple places if needed.

What `SandboxEditor` needs to change

expectedOutput and onPass are both optional. When neither is provided, SandboxEditor enters sandbox mode:

// Lesson mode (full grading):
<SandboxEditor
  scaffoldCode={phase3.scaffoldCode}
  expectedOutput={phase3.expectedOutput}
  onPass={handleSandboxPass}
/>

// Sandbox mode (free-play — no grading):
<SandboxEditor
  scaffoldCode={defaultCode}
/>

Sandbox mode behaviour (implemented — Task 10a done):

Only the raw output (or error) is shown after Run. No diff panel, no validation strip, no attempt counter.
Java-Chan is not notified. No setExpression, no setDialogue, no play('error'). The student is experimenting freely — reacting to "wrong" output would be hostile to that goal. There is no wrong output in the sandbox.
The Run button is never disabled. There is no terminal "passed" state.
sandboxMode is detected as expectedOutput === undefined && onPass === undefined — both must be absent. Passing expectedOutput="" still activates lesson mode.

The trigger button

A small, tasteful FAB. Java-Chan's design language is warm and educational — the trigger shouldn't feel like a developer tool. Options:

A terminal/code icon (</>) with a subtle hover animation
Java-Chan's chibi face with a tiny code symbol
A simple "Try it" pill button that fits the existing button styles

Position: fixed, bottom-right, above any existing fixed elements (e.g. if there's a bottom nav on mobile, stack above it with a bottom offset).

Lesson JSON Migration Plan

~~Not every lesson needs executionMode.~~ This section is superseded by the Global Sandbox direction. Lessons will not be migrated. The executionMode field remains in the schema and SandboxEditor still works as a lesson component — if a future content decision changes this, the infrastructure is already there. But no lesson migration is planned.

The existing fill-in-the-blank validation (blankValidator.js, patternMatcher.js) remains the sole validation path for all current lessons.

Build Phases & Milestones

The original four-milestone plan was written when the interpreter's goal was lesson migration. That goal has changed — see Direction Change: The Global Sandbox. The milestones below reflect the new direction: build the sandbox first, then keep expanding interpreter capability indefinitely. There is no fixed end state. The interpreter grows as long as the app does.

Milestone 1 — The Scripting Subset ✅ Complete

Lexer, Parser, Evaluator for Unit 1's Java feature set. No classes, no objects. Static methods only. System.out, arithmetic, control flow, arrays, Math, ternary, enhanced for-each, array initializers.

Done: 233 tests passing. All features in the In Scope — Unit 1 table implemented and fixture-verified.

Milestone 2 — The Global Sandbox (Next)

Ship the floating sandbox panel as a globally accessible feature. This is the priority after Task 9.

Definition of done:

A trigger button (FAB or equivalent) is visible on every screen in the app
Clicking it opens the sandbox panel without navigating away or disrupting lesson state; the drawer has a clearly visible close button
Students can write, edit, and run any Java code within the interpreter's current feature scope
Output is shown inline; errors are displayed as raw interpreter output — Java-Chan does not react to sandbox runs (no expressions, no sounds, no judgement — the sandbox is a free-play space)
Editor content survives route navigation within a session
The sandbox panel can be opened and closed without side effects

Files: src/components/sandbox/GlobalSandbox.jsx, SandboxTrigger.jsx, CSS, app-shell wiring in App.jsx. SandboxEditor.jsx gets minor props changes to support lesson-free mode.

Milestone 3 — The Object System

Implement JavaObject.js and the class/instance/inheritance machinery. This is the hardest milestone — it requires the evaluator to model an object system rather than just static execution.

Definition of done:

A class with fields, a constructor, and instance methods can be defined and instantiated
this correctly refers to the current instance
extends creates a prototype chain; super() delegates to the parent constructor
Method overriding: if Dog extends Animal and both define speak(), calling speak() on a Dog runs Dog's version
instanceof returns the correct boolean
Full fixture coverage for all new node types

Sandbox impact: After this milestone, students can write and run OOP programs — classes, objects, inheritance — in the sandbox. A major capability jump.

Milestone 4 — Collections Subset

Implement ArrayList and HashMap as built-in interpreted types, backed by JS arrays and Maps respectively. Special-cased in the evaluator — new ArrayList<Integer>() creates a JS array with a Java-ArrayList-shaped interface.

ArrayList methods: add(val), get(i), set(i, val), size(), remove(i), contains(val), isEmpty(), iterator support (for (T item : list))

HashMap methods: put(k, v), get(k), containsKey(k), keySet(), values(), size()

Beyond Milestone 4 — Open-Ended Expansion

After the object system and collections are in place, the interpreter has covered essentially the full CS22301 curriculum scope. From that point, expansion is driven by what students actually try to run in the sandbox — not by a fixed plan.

Likely additions over time, in rough priority order:

String.format() / printf
Exception handling (try/catch/throw) — modeling Java's exception hierarchy as interpreter-level constructs
Method overloading (multiple methods with the same name, different arity/types)
Varargs
Interfaces (structural — implements is already parsed; evaluation is the gap)
Basic generics (enough to make ArrayList<T> feel real rather than erased)
Multi-dimensional array operations beyond 2D
Additional Math and String methods as students hit them

Each addition follows the same process: fixture first, failing test, implementation, passing test, done. The "Contributing: How to Add a Feature" section covers the mechanics.

No lesson migration is planned at any milestone. The sandbox is the delivery vehicle. Lessons stay as they are.

Error Message Design

Errors are a teaching opportunity. Java-Chan's interpreter errors should read like Java-Chan, not like a C compiler.

Every InterpreterError has a type (LexError, ParseError, RuntimeError), a message, and optionally a line. The SandboxEditor component renders these with Java-Chan's voice:

Actual error	Displayed message
Missing semicolon	`Line 3: Looks like you forgot a semicolon! Every statement needs one~ 😅`
Undeclared variable	`Line 7: I don't see where 'x' was declared — did you forget int x = ...?`
Array index out of bounds	`Runtime error: That index is out of range! Array has 5 elements, you tried index 7 🙈`
Type mismatch	`Line 4: Can't assign a String where an int belongs. Types have to match!`
Infinite loop / timeout	`Execution stopped: looks like this might be an infinite loop... check your condition~ 😓`
Division by zero	`Runtime error: Can't divide by zero! Java throws ArithmeticException here 📖`

These messages are defined in InterpreterError.js as a mapping from error codes to templates. New contributors should add error messages here rather than scattering strings through the evaluator.

Testing Strategy

The interpreter is the highest-stakes code in this project — a bug here produces wrong output that misleads students. Every evaluator feature needs a test.

Tests live in src/interpreter/__tests__/. Use whatever test runner is already in the project (Vitest, since the project uses Vite). Tests call run(sourceString) directly and assert on stdout.

Test fixture structure:

__tests__/fixtures/
  unit1/
    hello_world.java
    variables_basic.java
    for_loop_sum.java
    array_access.java
    ...
  unit2/
    inheritance_basic.java
    override.java
    ...

Each fixture is a complete valid Java program (one that runs in a real JVM). The test asserts that our interpreter produces the same stdout as the real JVM would. This keeps us honest — if our output diverges from real Java, that's a bug, not a design decision.

Minimum coverage targets:

Module	Minimum tests
Lexer	One test per token type; one test for each escape sequence; malformed input cases
Parser	One test per AST node type; operator precedence; nested blocks
Evaluator	All arithmetic operators; all control flow structures; method calls; array operations; standard library methods; timeout trigger; each error type

What Not to Do

A few specific pitfalls to avoid that are common when building interpreters in this situation:

Don't try to reuse javaHighlighter.js as a lexer. The highlighter is a regex-based colorizer, not a proper tokenizer. It doesn't track state, doesn't handle context, and doesn't produce structured tokens the parser can consume. They share some vocabulary but serve different purposes. Lexer.js is a fresh implementation.

Don't eval() the student's code. Converting Java to JavaScript and running it with eval() is not an interpreter — it's a transpiler, and a dangerous one. Students could inject JS that escapes the sandbox. The AST-walking approach is safe because you control every execution step.

Don't implement Java's type system fully. Java's type system is one of the most complex in any mainstream language (generics, wildcards, intersection types, type erasure). We need just enough type tracking to handle int vs double arithmetic and to correctly format output (Java prints 5 not 5.0 for integers). Beyond that, type annotations are decorative in our interpreter.

Don't implement exceptions as exceptions. Java's try/catch semantics are their own thing. When the interpreter hits a runtime error, it surfaces it as an InterpreterError to the UI — it doesn't try to model Java's exception hierarchy. That's Phase 2 scope anyway.

Don't implement Scanner with real stdin. Lessons that use Scanner for user input will be given a stdin array in the lesson JSON — pre-seeded input values that the interpreter delivers one line at a time when Scanner.nextLine() or Scanner.nextInt() is called. This gives deterministic, testable behavior without needing a real interactive terminal.

Contributing: How to Add a Feature

When you need to add a new Java feature to the interpreter:

Write a fixture first. Put a .java file in __tests__/fixtures/ that uses the feature and produces known output. Confirm the output is correct by running it against a real JVM.
Write a failing test. Call run(fixture) and assert on stdout. It should fail because the feature isn't implemented yet.
Add the token(s) to Lexer.js. If the feature introduces new syntax (instanceof, a new keyword), add the token type and the lexer rule.
Add the AST node(s) to Parser.js. Figure out where in the recursive descent grammar the new syntax appears, add the parsing function or extend an existing one, return the new node type.
Add the evaluation case to Evaluator.js. Handle the new node type in evaluate(). Add it to StandardLibrary.js if it's a standard library method.
Run the test. It should pass. If it doesn't, the evaluator logic is wrong.
Update this doc. If the new feature changes the scope tables, AST node list, token set, or sandbox capability in a meaningful way, update the relevant sections. Keep the doc honest.
Run all existing tests. Adding a feature should never break existing tests. If it does, something in the shared evaluation path changed in a way that needs investigation.

Current Task Queue

Tasks are listed in dependency order. The same session rules apply: take the first unchecked task, finish it fully (implementation + tests + passing npm run test + lint clean), check the box, update Status at the top, commit in the same PR.

Rules for picking up a task:

Take the first unchecked [ ] task from the top. If you're not sure it's actually free, check this file's git history/blame first — someone may have claimed it mid-session without pushing yet.
Finish the whole task in one session. These are sized to be doable in a single sitting — implementation + tests + a passing npm run test and npm run lint. Don't leave a task half-done and checked off, and don't check off a task you didn't finish.
When done, check the box, add your name and the PR/commit, and update Status at the top of this doc if a milestone's Definition of Done is now met.
Commit the checkbox update in the same PR as the code — this file is the source of truth for "what's next," so it has to move in lockstep with the code, not after it.

If a task turns out to be bigger than one session, stop and split it into two sub-tasks in this list rather than pushing through — that keeps the "one task, one session" rule honest for whoever picks it up next.

After Task 10: The task queue becomes open-ended. Each new interpreter feature follows the same pattern — fixture, test, implementation, done — and gets its own task entry added here when it's scoped. The milestones in §"Build Phases & Milestones" give the broad direction; the task queue is where the specifics live. Add new tasks at the bottom of this list as they're planned, keeping the dependency chain clear.

Summary

Java-Chan's interpreter is a tree-walking Java subset interpreter written entirely in JavaScript, living in src/interpreter/, integrated additively into the existing app via the Global Sandbox — a floating panel available on every screen where students can write and run Java freely, without any lesson context.

Lessons are not migrated. The fill-in-the-blank validation (blankValidator.js, patternMatcher.js) remains the sole validation path for all current lessons. The executionMode field exists in the schema and SandboxEditor still works as a lesson component, but no lesson migration is planned.

The interpreter's roadmap is open-ended. Milestone 1 (the scripting subset) is complete. Milestone 2 (the Global Sandbox UI) is next. After that, the object system, collections, and whatever the students actually try to run come in rough priority order. Each addition follows the same fixture-first, test-driven process. There is no fixed endpoint.

The public API is a single function: run(sourceCode) → { output, error }. Everything else is internal. The rest of the app stays unchanged.

This document lives on the feature/java-interpreter branch and should be updated as implementation decisions are made. Major deviations from this plan — especially changes to the public API or the lesson JSON schema — should be noted here with a rationale before the code changes.

FilesExpand file tree

INTERPRETER.md

Latest commit

History