How bard/mozrepl works
MozRepl is a legacy Firefox/Mozilla extension that bridges an external TCP client to JavaScript execution inside the browser. Architecturally, it sits between three worlds:
1. the Firefox chrome/extension runtime,
2. the browser/page JavaScript execution contexts,
3. external tools connecting over a local TCP socket.
Main packaging and platform layer
• install.rdf, chrome.manifest, and defaults/preferences/mozrepl.js define the classic Mozilla add-on packaging, chrome registration, and default preferences.
• chrome/content/overlay_browser.xul and chrome/content/overlay.js implement the browser-window overlay mechanism used by old-style Firefox extensions.
• components/ contains XPCOM integration code:
- MozRepl.js, MozRepl.idl, and MozRepl.xpt define the add-on’s component interface and binary component registration.
- CommandLine.js suggests command-line integration so the extension can react to startup arguments or browser launch behavior.
Core runtime architecture
• The main service is a REPL server that listens on a TCP port, by default on localhost only, as described in the README.
• chrome/content/server.js is the network-facing side: it accepts socket connections from external clients.
• chrome/content/repl.js is the evaluation layer that processes incoming REPL input and evaluates JavaScript in the relevant Mozilla context.
• chrome/content/overlay_impl.js likely coordinates startup/shutdown and wires browser lifecycle events to the REPL server.
• chrome/content/ui.js is the browser-side user interface layer, likely for status or interaction within the browser chrome.
• chrome/content/util.js holds shared helpers used across the chrome-side modules.
• chrome/content/moz.el is an Emacs integration artifact, indicating the extension was designed to be controlled from external editors or tooling.
Primary data flow
1. Firefox starts and loads the extension through the legacy overlay/component system.
2. Default preferences from defaults/preferences/mozrepl.js configure the service, including network binding and port behavior.
3. The XPCOM/component layer initializes the MozRepl service and command-line hooks.
4. The server opens a local TCP listener.
5. An external client connects and sends REPL commands.
6. The server passes those commands into the REPL evaluation layer.
7. JavaScript is evaluated in the browser chrome context and, when needed, in web page contexts.
8. Results, errors, or prompt output are sent back across the same TCP connection.
Important boundaries
• Network boundary: only external TCP clients cross into the extension through server.js.
• Browser chrome boundary: extension code runs inside Firefox’s privileged chrome context, separate from page scripts.
• XPCOM/legacy Mozilla boundary: much of the add-on depends on deprecated Mozilla extension APIs, which is why the README notes the Firefox 54 compatibility limit.
• Configuration boundary: runtime behavior is driven by Mozilla preferences rather than by a standalone configuration service.
Testing and fixtures
• test/test-repl.js is the main automated test entry point.
• test/fixtures/ contains the HTML and preference fixtures used to exercise REPL behavior in a controlled browser context.
• The test suite appears to validate the interactive socket-to-browser evaluation path rather than pure library logic.
In short, the repository is organized around a browser-embedded REPL service: Mozilla extension/bootstrap code initializes a privileged server, the server accepts local socket clients, and the REPL layer evaluates commands against Firefox and web-page JavaScript contexts.
Main entry points: repl.js REPL Engine · overlay_impl.js Lifecycle · test-repl.js REPL Test · server.js TCP Server
Components 18
Firefox Runtime
Privileged browser-side extension code and REPL execution paths.
- Browser Overlay · Hooks the extension into Firefox browser windows.
chrome/content/overlay_browser.xul - Lifecycle · Coordinates startup, shutdown, and browser event wiring.
chrome/content/overlay_impl.js - TCP Server · Accepts external local client connections over TCP.
chrome/content/server.js - REPL Engine · Parses commands and evaluates JavaScript in Mozilla contexts.
chrome/content/repl.js - Browser UI · In-browser status or interaction surface for the add-on.
chrome/content/ui.js - Shared Helpers · Common chrome-side helpers reused across runtime modules.
chrome/content/util.js - Emacs Glue · Editor-side helper artifact for external control workflows.
chrome/content/moz.el
XPCOM Layer
Legacy Mozilla component registration and command-line integration.
- MozRepl Component · Primary legacy component interface and implementation.
components/MozRepl.js - IDL Contract · Interface definition for the MozRepl component.
components/MozRepl.idl - Binary Interface · Compiled typelib exposing the component contract.
components/MozRepl.xpt - Cmdline Hook · Command-line integration for startup-time behavior.
components/CommandLine.js
Configuration
Default preferences that shape server binding and startup behavior.
- Defaults · Default Mozilla preferences for port and binding behavior.
defaults/preferences/mozrepl.js
Tests
End-to-end REPL coverage with browser fixtures.
- REPL Test · Main automated test entry exercising socket-to-browser evaluation.
test/test-repl.js - Page Fixture · Controlled browser document used by REPL tests.
test/fixtures/index.html - Test Prefs · Preference fixture used to shape browser/test behavior.
test/fixtures/test-prefs.json
Other components
- Addon Package · Legacy Mozilla add-on packaging and registration entry points.
install.rdf - Chrome Reg · Maps chrome content and overlays into the browser.
chrome.manifest - Entry Point · Repository-level package entry used by the current toolchain.
index.js
Connections 21
- Addon Package → Chrome Reg: registers · Declares chrome resources and overlay wiring.
- Chrome Reg → Browser Overlay: loads · Attaches browser-window overlay into Firefox.
- Entry Point → Addon Package: packages · Repository package entry sits alongside legacy add-on metadata.
- MozRepl Component → IDL Contract: implements · Component implementation follows the declared interface.
- MozRepl Component → Binary Interface: exposes · Typelib publishes the component contract to Mozilla tooling.
- Cmdline Hook → MozRepl Component: starts · Command-line integration can trigger component startup behavior.
- Defaults → Lifecycle: configures · Default preferences shape server and startup behavior.
- Browser Overlay → Lifecycle: delegates · UI overlay hands lifecycle work to implementation logic.
- Lifecycle → TCP Server: starts · Initialization wires up the network listener.
- Lifecycle → Browser UI: hosts · Browser lifecycle coordinates the chrome UI layer.
- Lifecycle → Shared Helpers: uses · Lifecycle code shares helpers with other chrome modules.
- TCP Server → REPL Engine: forwards · Socket input is passed to the evaluation layer.
- REPL Engine → Browser UI: reports · Results and status can surface in browser chrome.
- REPL Engine → Shared Helpers: uses · Evaluation logic relies on shared helpers.
- REPL Engine → Emacs Glue: integrates · Supports editor-driven external control workflows.
- REPL Test → TCP Server: connects · Integration test exercises the socket server path.
- REPL Test → REPL Engine: verifies · Tests validate REPL evaluation behavior.
- REPL Test → Page Fixture: loads · Browser fixture provides a controlled page context.
- REPL Test → Test Prefs: applies · Preference fixture shapes the test environment.
- TCP Server → Defaults: reads · Network binding and port behavior come from preferences.
- REPL Engine → MozRepl Component: executes in · Evaluation ultimately runs through the privileged component/browser runtime boundary.