ILP — Interactive Learning Runtime
Experimental browser runtime for declarative interactive lessons, with schema validation, parsed expressions, reactive state, and DOM, SVG, and 3D rendering. Runtime implemented; authoring reliability and learning outcomes remain unevaluated.
The problem
Interactive lessons usually require topic-specific application code. A reusable runtime needs to interpret lesson definitions, validate their references and actions, and keep several renderers synchronized without executing arbitrary lesson code.
Context and constraints
An experimental local-first runtime separates the lesson document from the application that interprets it. A new topic should reuse the same state model, expression rules and rendering capabilities.
- Lesson definitions must use a bounded expression and action vocabulary rather than arbitrary JavaScript.
- References, dependencies and renderer capabilities must be checked before a lesson session starts.
- A working example demonstrates runtime behaviour; it does not establish authoring reliability or learning benefit.
What I built
A TypeScript runtime with strict Zod schemas, staged lesson validation, a lexer and Pratt expression parser, dependency-ordered derived state, facts and allowlisted actions. DOM, SVG and React Three Fiber renderers share the lesson session. A paste/file importer and four example lessons exercise the MVP.
Architecture
A lesson document is validated before a session resolves state and expressions for the reusable renderers.
- Lesson JSON
- Declarative content and actions
- Validator
- Schemas, references, limits
- Expression parser
- Bounded syntax tree
- Reactive session
- State, facts, derived values
- Shared renderers
- DOM, SVG, 3D
My contribution
Author and maintainer. Lesson schema and validator, expression parser, reactive runtime, shared rendering model, importer, examples and regression tests.
Runtime built, evaluation pending
The implemented MVP and its unperformed evaluation are recorded separately.
Implemented means code exists in the reviewed source. It does not mean the runtime is fully hardened or that learning benefits have been demonstrated.
Technical decisions
What was chosen, why, and what it cost.
Keep lessons separate from runtime code
- Decision
- Represent lessons as JSON using a shared schema and capability vocabulary.
- Why
- Topic-specific content can reuse the runtime while validation catches unsupported references before rendering.
- Trade-off
- The format cannot express arbitrary application behaviour; authors must work within the implemented capabilities.
Parse expressions instead of evaluating JavaScript
- Decision
- Use a lexer and Pratt parser with bounded syntax-tree evaluation.
- Why
- Expressions can reference runtime state without gaining general JavaScript execution.
- Trade-off
- A restricted language needs explicit semantics, validation and edge-case tests; current hardening gaps still need attention.
Verification
How the implementation was checked, and how much of that can be shown publicly.
Validator and runtime test sourcesevidenced
Reviewed schema/reference validation and app interaction tests. The UI suite stubs the 3D canvas, so it does not verify real WebGL rendering.
Authoring and learner evaluationnot publicly evidenced
Neither external authoring reliability nor learning effectiveness has been measured.
Results
- The MVP runs declarative example lessons through one shared runtime.
- No authoring-reliability or learning-effectiveness results are claimed.
Limitations and disclosure
What this project does not do, and what cannot be shown publicly.
- External lesson-authoring reliability and learning effectiveness have not been evaluated.
- Known hardening gaps include fact-namespace lookup, non-finite numeric bindings, flow visibility/highlighting, and plot discontinuity handling.
- No accounts, course backend or durable progress storage. The MVP supports four example lessons rather than a validated curriculum.
Repository private. This case study publishes a sanitized implementation summary and known limitations; it contains no private source links or lesson-material excerpts.