# bard/mozrepl architecture

> Architecture diagram of the GitHub repository bard/mozrepl, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bard/mozrepl
- Repository: https://github.com/bard/mozrepl

## Overview

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: [`chrome/content/repl.js`](https://github.com/bard/mozrepl/blob/HEAD/chrome/content/repl.js) (REPL Engine), [`chrome/content/overlay_impl.js`](https://github.com/bard/mozrepl/blob/HEAD/chrome/content/overlay_impl.js) (Lifecycle), [`test/test-repl.js`](https://github.com/bard/mozrepl/blob/HEAD/test/test-repl.js) (REPL Test), [`chrome/content/server.js`](https://github.com/bard/mozrepl/blob/HEAD/chrome/content/server.js) (TCP Server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph "Firefox Runtime"
  node_overlay["Browser Overlay<br/>chrome overlay"]
  node_overlay_impl["Lifecycle<br/>extension bootstrap<br/>[overlay_impl.js]"]
  node_server["TCP Server<br/>socket listener<br/>[server.js]"]
  node_repl["REPL Engine<br/>eval layer<br/>[repl.js]"]
  node_ui["Browser UI<br/>chrome ui<br/>[ui.js]"]
  node_util["Shared Helpers<br/>utility module<br/>[util.js]"]
  node_mozel["Emacs Glue<br/>editor integration<br/>[moz.el]"]
end

subgraph "XPCOM Layer"
  node_xpcom["MozRepl Component<br/>xpcom service<br/>[MozRepl.js]"]
  node_idl["IDL Contract<br/>xpcom interface<br/>[MozRepl.idl]"]
  node_xpt["Binary Interface<br/>xpcom typelib<br/>[MozRepl.xpt]"]
  node_cmdline["Cmdline Hook<br/>startup hook<br/>[CommandLine.js]"]
end

subgraph "Configuration"
  node_prefs["Defaults<br/>preferences<br/>[mozrepl.js]"]
end

subgraph "Tests"
  node_test["REPL Test<br/>integration test<br/>[test-repl.js]"]
  node_fixture_html["Page Fixture<br/>test fixture<br/>[index.html]"]
  node_fixture_prefs["Test Prefs<br/>test fixture<br/>[test-prefs.json]"]
end

node_package["Addon Package<br/>manifest/package<br/>[install.rdf]"]
node_chrome_manifest["Chrome Reg<br/>manifest/chrome<br/>[chrome.manifest]"]
node_bootstrap["Entry Point<br/>node/npm<br/>[index.js]"]

node_package -->|"registers"| node_chrome_manifest
node_chrome_manifest -->|"loads"| node_overlay
node_bootstrap -->|"packages"| node_package
node_xpcom -->|"implements"| node_idl
node_xpcom -->|"exposes"| node_xpt
node_cmdline -->|"starts"| node_xpcom
node_prefs -->|"configures"| node_overlay_impl
node_overlay -->|"delegates"| node_overlay_impl
node_overlay_impl -->|"starts"| node_server
node_overlay_impl -->|"hosts"| node_ui
node_overlay_impl -->|"uses"| node_util
node_server -->|"forwards"| node_repl
node_repl -->|"reports"| node_ui
node_repl -->|"uses"| node_util
node_repl -->|"integrates"| node_mozel
node_test -->|"connects"| node_server
node_test -->|"verifies"| node_repl
node_test -->|"loads"| node_fixture_html
node_test -->|"applies"| node_fixture_prefs
node_server -->|"reads"| node_prefs
node_repl -->|"executes in"| node_xpcom

click node_package "https://github.com/bard/mozrepl/blob/master/install.rdf"
click node_chrome_manifest "https://github.com/bard/mozrepl/blob/master/chrome.manifest"
click node_bootstrap "https://github.com/bard/mozrepl/blob/master/index.js"
click node_overlay "https://github.com/bard/mozrepl/blob/master/chrome/content/overlay_browser.xul"
click node_overlay_impl "https://github.com/bard/mozrepl/blob/master/chrome/content/overlay_impl.js"
click node_server "https://github.com/bard/mozrepl/blob/master/chrome/content/server.js"
click node_repl "https://github.com/bard/mozrepl/blob/master/chrome/content/repl.js"
click node_ui "https://github.com/bard/mozrepl/blob/master/chrome/content/ui.js"
click node_util "https://github.com/bard/mozrepl/blob/master/chrome/content/util.js"
click node_mozel "https://github.com/bard/mozrepl/blob/master/chrome/content/moz.el"
click node_xpcom "https://github.com/bard/mozrepl/blob/master/components/MozRepl.js"
click node_idl "https://github.com/bard/mozrepl/blob/master/components/MozRepl.idl"
click node_xpt "https://github.com/bard/mozrepl/blob/master/components/MozRepl.xpt"
click node_cmdline "https://github.com/bard/mozrepl/blob/master/components/CommandLine.js"
click node_prefs "https://github.com/bard/mozrepl/blob/master/defaults/preferences/mozrepl.js"
click node_test "https://github.com/bard/mozrepl/blob/master/test/test-repl.js"
click node_fixture_html "https://github.com/bard/mozrepl/blob/master/test/fixtures/index.html"
click node_fixture_prefs "https://github.com/bard/mozrepl/blob/master/test/fixtures/test-prefs.json"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_overlay,node_overlay_impl,node_server,node_repl,node_ui,node_util,node_mozel toneBlue
class node_xpcom,node_idl,node_xpt,node_cmdline toneAmber
class node_prefs toneMint
class node_test,node_fixture_html,node_fixture_prefs toneRose
class node_package,node_chrome_manifest,node_bootstrap toneNeutral
```

## Components

### Firefox Runtime

Privileged browser-side extension code and REPL execution paths.

- [Browser Overlay](https://github.com/bard/mozrepl/blob/HEAD/chrome/content/overlay_browser.xul): chrome overlay · Hooks the extension into Firefox browser windows. · `chrome/content/overlay_browser.xul`
- [Lifecycle](https://github.com/bard/mozrepl/blob/HEAD/chrome/content/overlay_impl.js): extension bootstrap · Coordinates startup, shutdown, and browser event wiring. · `chrome/content/overlay_impl.js`
- [TCP Server](https://github.com/bard/mozrepl/blob/HEAD/chrome/content/server.js): socket listener · Accepts external local client connections over TCP. · `chrome/content/server.js`
- [REPL Engine](https://github.com/bard/mozrepl/blob/HEAD/chrome/content/repl.js): eval layer · Parses commands and evaluates JavaScript in Mozilla contexts. · `chrome/content/repl.js`
- [Browser UI](https://github.com/bard/mozrepl/blob/HEAD/chrome/content/ui.js): chrome ui · In-browser status or interaction surface for the add-on. · `chrome/content/ui.js`
- [Shared Helpers](https://github.com/bard/mozrepl/blob/HEAD/chrome/content/util.js): utility module · Common chrome-side helpers reused across runtime modules. · `chrome/content/util.js`
- [Emacs Glue](https://github.com/bard/mozrepl/blob/HEAD/chrome/content/moz.el): editor integration · Editor-side helper artifact for external control workflows. · `chrome/content/moz.el`

### XPCOM Layer

Legacy Mozilla component registration and command-line integration.

- [MozRepl Component](https://github.com/bard/mozrepl/blob/HEAD/components/MozRepl.js): xpcom service · Primary legacy component interface and implementation. · `components/MozRepl.js`
- [IDL Contract](https://github.com/bard/mozrepl/blob/HEAD/components/MozRepl.idl): xpcom interface · Interface definition for the MozRepl component. · `components/MozRepl.idl`
- [Binary Interface](https://github.com/bard/mozrepl/blob/HEAD/components/MozRepl.xpt): xpcom typelib · Compiled typelib exposing the component contract. · `components/MozRepl.xpt`
- [Cmdline Hook](https://github.com/bard/mozrepl/blob/HEAD/components/CommandLine.js): startup hook · Command-line integration for startup-time behavior. · `components/CommandLine.js`

### Configuration

Default preferences that shape server binding and startup behavior.

- [Defaults](https://github.com/bard/mozrepl/blob/HEAD/defaults/preferences/mozrepl.js): preferences · Default Mozilla preferences for port and binding behavior. · `defaults/preferences/mozrepl.js`

### Tests

End-to-end REPL coverage with browser fixtures.

- [REPL Test](https://github.com/bard/mozrepl/blob/HEAD/test/test-repl.js): integration test · Main automated test entry exercising socket-to-browser evaluation. · `test/test-repl.js`
- [Page Fixture](https://github.com/bard/mozrepl/blob/HEAD/test/fixtures/index.html): test fixture · Controlled browser document used by REPL tests. · `test/fixtures/index.html`
- [Test Prefs](https://github.com/bard/mozrepl/blob/HEAD/test/fixtures/test-prefs.json): test fixture · Preference fixture used to shape browser/test behavior. · `test/fixtures/test-prefs.json`

### Other components

- [Addon Package](https://github.com/bard/mozrepl/blob/HEAD/install.rdf): manifest/package · Legacy Mozilla add-on packaging and registration entry points. · `install.rdf`
- [Chrome Reg](https://github.com/bard/mozrepl/blob/HEAD/chrome.manifest): manifest/chrome · Maps chrome content and overlays into the browser. · `chrome.manifest`
- [Entry Point](https://github.com/bard/mozrepl/blob/HEAD/index.js): node/npm · Repository-level package entry used by the current toolchain. · `index.js`

## Connections

- 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.
