nw wrld

Abstract

nw_wrld is an event-driven sequencer for triggering visuals using web technologies. It enables users to scale up audiovisual compositions for prototyping, demos, exhibitions, and live performances. Users code their own visual modules, then orchestrate them using the project's native UI composer.

The Problem

Live audiovisual performances typically need bespoke software that ties visuals to audio triggers, MIDI hardware, or sequencers. Most tools either force you into a fixed visual framework or require you to build the entire control surface yourself. nw_wrld solves this by giving performers a ready-made orchestration layer — a 16-step sequencer, MIDI/OSC/audio input mapping, and a UI for arranging tracks — while letting them write the actual visual modules in plain JavaScript or TypeScript.

What This Does

nw_wrld is an Electron app with two windows: a Dashboard (src/dashboard/) for composing tracks, programming patterns, and configuring inputs, and a Projector (src/projector/) that renders the visuals. Users write visual modules as JavaScript files (using p5.js, Three.js, D3.js, or vanilla JS) and drop them into a project folder. The dashboard maps those modules to tracks, which are triggered by sequencer patterns or external signals.

The repo is a fork of aagentah/nw_wrld (2048 stars) and is in active beta. It includes 16 starter modules (src/main/starter_modules/), hot module reloading, and a project-folder workflow where each project is self-contained with its modules, assets, and data.

How It Is Wired

Execution starts in src/index.js, which boots the Electron main process (src/main/mainProcess/entry.ts). That process creates the two windows and sets up an IPC bridge (src/main/mainProcess/ipcBridge/) that exposes workspace, project, input, and JSON operations to the renderer. The Dashboard is a React app (src/dashboard/Dashboard.js) that manages state through a set of custom hooks in src/dashboard/core/hooks/.

The most heavily used function is isPlainObject (called from 87 places), defined in src/shared/validation/jsonBridgeValidation.ts. That file is the repository's hub — 37 other files depend on it, and it defines the core validation utilities (isArray, asString, normalizeRecordingDataJson) that nearly every data path routes through. The Dashboard component has 25 imports and an instability score of 0.96, meaning it's a leaf node — change it and little else breaks, but it's the largest single point of UI composition.

The projector side (src/projector/Projector.ts) loads module source, instantiates classes, and manages the Three.js scene via src/projector/helpers/threeBase.ts (33 functions). The main process reads and writes files directly — for example, main in scripts/checkRuntimeLaneNoDuplicateSources.ts calls findOffenders → readJson using fs.readFileSync. The src/dashboard/core/utils.ts file owns user data persistence (readUserData, updateUserData, getUserDataPath).

The import graph shows 274 internal modules with zero circular dependencies — a clean structure. The main risk is hub modules: Button.tsx and core/utils.ts each have 20 dependents, so changes there ripple widely.

How To Use It

Setup:

git clone https://github.com/moses-y/nw_wrld.git
cd nw_wrld
npm install
npm start

Requires Node.js v20+. The app opens both the Dashboard and Projector windows. For E2E testing: npm run test:e2e (uses Playwright). Projects are self-contained folders with modules/, assets/, and data/ subdirectories.

Real-World Use

A VJ preparing a live set creates a project folder, drops in their Three.js modules, and uses the Dashboard to assign each module to a track. They configure a 16-step pattern for the beat-synced visuals and map a MIDI controller to trigger specific methods on other tracks. During the show, the Projector window outputs to a display while the Dashboard stays on a laptop for live tweaks.

Code Health & Issues

Static analysis found 84 issues (7 high, 77 medium). The high-severity findings:

High - Duplicated code blocks - 860 repeated 6-line blocks across 112 files, including src/dashboard/Dashboard.js and src/dashboard/core/hooks/useDashboardUiState.ts. Extract shared helpers.
High - Deep nesting - Max indentation depth of 9 in src/dashboard/components/track/ModuleComponents.tsx and src/dashboard/modals/AddModuleModal.tsx. Flatten with early returns.

Medium findings include high branching density (useIPC.ts, pathSafety.ts), hub modules with high blast radius (20 dependents on Button.tsx and core/utils.ts), and oversized files (threeBase.ts at 740 lines).

CI/CD has one high-severity issue: GitHub Actions are pinned to version tags (e.g., softprops/action-gh-release@v2) rather than commit SHAs, which is a supply-chain risk. The workflow also lacks least-privilege permissions declarations and has no dependency vulnerability scan.

The Bottom Line

nw_wrld is a well-architected Electron app for a niche but real need: live audiovisual performance. The two-window model and module system are sound, and the zero-circular-dependency graph is a good sign. The main technical debt is code duplication and some deep nesting in the UI layer, plus CI hygiene issues worth fixing before relying on it for production shows. It's beta software with frequent breaking changes, so treat it as a tool for performers who can tolerate some instability, not a drop-in product.