The Problem
nwwrld addresses the need for a lightweight, event‑driven sequencer that lets artists and developers trigger visual compositions with web technologies without leaving the Electron desktop. The project fills a gap for prototyping, demo, exhibition, and live‑performance workflows where modular visual code must be orchestrated quickly and reliably.
What This Does
nwwrld combines a 16‑step pattern sequencer with external input pipelines (MIDI, OSC, microphone/audio capture, file upload) and a visual‑module system that accepts p5.js, Three.js, D3.js, or plain JavaScript. The Dashboard UI (src/dashboard/) provides track creation, pattern programming, and per‑track signal settings such as thresholds and cooldowns (src/dashboard/core/hooks/useDashboardAudioDevices.ts, src/dashboard/core/hooks/useDashboardPlayback.ts). Visual modules live in src/main/startermodules/ and are hot‑reloaded through the renderer; the projector process (src/projector/) sandbox‑executes each module (src/projector/internal/sandbox/TrackSandboxHost.ts) and bridges results back to the dashboard via IPC (src/main/mainProcess/ipcBridge/). Starter modules include HelloWorld.js, SpinningCube.js, Text.js, and 13 others that demonstrate geometry, particle systems, and orbital visuals.
How To Use It
Setup git clone https://github.com/aagentah/nwwrld.git cd nwwrld npm install # pulls dependencies listed in package.json npm start # launches two Electron windows: Dashboard and Projector
The Dashboard (src/dashboard/entry.ts) is the control center; the Projector (src/projector/entry.ts) renders the visual output.
Project folder workflow – place a self‑contained project folder with a modules/ subdirectory containing JavaScript files. The workspace starter scripts (src/main/workspaceStarterModules.ts, src/main/workspaceStarterAssets.ts) seed 16 example modules. Only open folders you trust, as modules are executed untrusted code.
E2E testing – run npm run test:e2e to launch the real Electron app under Playwright; tests can target an isolated project directory via NWWRLDTESTPROJECTDIR. Artifacts land in test-results/ (git‑ignored).
Configuration – no external API keys are required. Per‑track audio thresholds are set through the UI hooks mentioned above; MIDI/OSC ports are configured in the Dashboard’s input‑mapping modals (src/dashboard/modals/InputMappingsModal.tsx).
Real‑World Use
During a live‑performance setup, a MIDI controller sends note‑on messages on channel 1. The Dashboard’s useInputEvents.ts listens for those messages and routes them through src/projector/internal/track/methodExecutor.ts, which invokes the registered visual method (e.g., SpinningCube.rotate) on the appropriate track. Adjusting the per‑track threshold in useDashboardAudioDevices.ts prevents accidental triggers from ambient noise, while the 16‑step sequencer (SequencerGrid.tsx) can fire the same method on a rhythmic grid without hardware. The portable project folder can be copied to a laptop, re‑loaded, and the same visual patch runs unchanged.
Code Health & Issues
Tests & CI – 10 Jest/Playwright test files exist; GitHub Actions workflows (ci.yml, release.yml) run on push and tag. License (LICENSE) and lockfile (package-lock.json) are present. Beta‑level breaking changes – the README notes frequent breaking changes between releases; pinning Node ≥ 20 and Electron v39.2.7 is advised for stability. IPC surface area – many bridge files under src/main/mainProcess/ipcBridge/ expose renderer‑to‑main communication; missing input validation on payloads could allow unexpected data injection. Module sandbox – TrackSandboxHost.ts isolates module execution, but the sandbox configuration is not audited for Node API exposure; a compromised module could potentially escape if the sandbox permits require. TypeScript migration – 75 .ts files and 41 .tsx files are mixed with 27 plain .js starter modules; some legacy modules lack type declarations, which may cause runtime errors when imported from typed code. No secrets or config in repo – .env files are absent; all configuration is UI‑driven or project‑folder based, reducing credential leakage risk.
The Bottom Line
nwwrld is a functional Electron‑based sequencer that lowers the barrier to entry for audiovisual prototyping; its modular architecture, hot‑reloading, and external‑input pipelines make it suitable for rapid iteration and live performance. The beta status and occasional breaking changes mean it is best used by teams comfortable with pinning specific runtime versions and reviewing sandbox boundaries. Solo developers or small crews looking for a portable, UI‑driven visual sequencer will find immediate value, while large organizations requiring strict security audits may need to audit the IPC and sandbox implementations before deployment.