Add design doc for the browser JS module refactor - #503
Merged
Conversation
browser/io.js is a REPL page script with no exports, so the VM cannot be embedded in another page without copying files by hand. The doc describes turning it into an importable module: the file layout, the proposed Io class API, the three changes that cut the seam, and the hazards found while reading the current code. Notes one real bug: output printed from inside Io callbacks is silently dropped when there is no REPL #output element, because ioSend reaches into the DOM through flushCallbackOutput. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Design doc only — no code changes.
browser/io.jsis 1071 lines: 1-889 are library, 891-1071 are the REPL app. The layering is already sound, and there is exactly one edge from the core into the DOM, at line 774. The doc describes cutting that seam so the VM can be embedded, and eventually published to npm.Covers the five things that block library use (no exports, module-level singletons, parse-time config, the DOM edge, browser-only loading), the proposed file layout and
Ioclass API, the three changes that do the work, and the hazards found while reading the current code.One of those is a real bug rather than a smell:
flushCallbackOutputreturns early when there is no#outputelement, so output printed from inside Io callbacks is silently discarded for any embedder. Inverting the line 774 edge fixes it.Also worth flagging: the core becomes instantiable from bytes with no DOM, so most of
test.htmlcould become a plain Node test andmake check-browserwould stop needing Playwright/Chromium for anything but genuine in-page behavior.All line references in the doc were verified against the current file.
🤖 Generated with Claude Code