Audit hardening: persistence durability, Electron security, perf, deps

.github/PULL_REQUEST_TEMPLATE.md

@@ -35,3 +35,4 @@ Anything risky, or areas to pay attention to:
 - `MODULE_DEVELOPMENT.md`
 - `CONTRIBUTING.md`
 - `RUNTIME_TS_TESTING_GUIDELINES.md`
+- `E2E_TESTING_GUIDELINES.md`

.github/copilot-instructions.md

@@ -8,6 +8,7 @@ You are reviewing changes in `nw_wrld`, an Electron app with a deliberate archit
 - `MODULE_DEVELOPMENT.md`
 - `CONTRIBUTING.md`
 - `RUNTIME_TS_TESTING_GUIDELINES.md`
+- `E2E_TESTING_GUIDELINES.md`
 
 #### Primary goal
 

.github/workflows/release.yml

@@ -165,7 +165,10 @@ jobs:
           pathlib.Path("SHA256SUMS").write_text("\n".join(lines) + ("\n" if lines else ""), encoding="utf-8")
           print(pathlib.Path("SHA256SUMS").read_text(encoding="utf-8"))
           PY
-      - uses: softprops/action-gh-release@v2
+      # Pinned to a commit SHA (supply-chain hardening): a floating @v2 tag can be
+      # repointed by a maintainer or attacker, and this step publishes release
+      # artifacts with the contents:write token. SHA == softprops/action-gh-release v2.
+      - uses: softprops/action-gh-release@3bb12739c298aeb8a4eeaf626c5b8d85266b0e65 # v2
         with:
           tag_name: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.tag != '' && github.event.inputs.tag || github.ref_name }}
           files: |

CONTRIBUTING.md

@@ -78,7 +78,7 @@ Documentation improvements are always welcome:
 
 ### Prerequisites
 
-- Node.js v18 or higher
+- Node.js v20 or higher
 - Git
 - A code editor (VS Code recommended)
 - Basic familiarity with JavaScript
@@ -99,19 +99,9 @@ cd nw_wrld
 git remote add upstream https://github.com/aagentah/nw_wrld.git
 ```
 
-### Install Dependencies
+### Install and Run
 
-```bash
-npm install
-```
-
-### Run the App
-
-```bash
-npm start
-```
-
-Two windows should open: Dashboard and Projector.
+Install dependencies and start the app by following the [Installation (For Developers)](README.md#for-developers) section of the README. Two windows should open: Dashboard and Projector.
 
 ### Development Workflow
 
@@ -142,10 +132,12 @@ git checkout -b feature/my-awesome-feature
 ### Formatting
 
 - 2 spaces for indentation
-- Semicolons are optional but be consistent
-- Use single quotes for strings
+- Semicolons are required
+- Use double quotes for strings
 - No trailing whitespace
 
+These are enforced by Prettier. Run `npm run format` to auto-format, or `npm run format:check` to verify before submitting.
+
 ### Comments
 
 - Add comments for complex logic
@@ -169,13 +161,17 @@ pulse({ intensity = 1.5, duration = 500 }) {
 
 ### Module Structure
 
-All modules must:
+All modules must (these are validated):
 
-1. Extend `ModuleBase` or `BaseThreeJsModule`
-2. Include the required `@nwWrld` docblock metadata (`name`, `category`, `imports`)
+1. Include the `@nwWrld` docblock metadata (`name`, `category`, `imports`), with `imports` non-empty
+2. Use only allow-listed tokens in `imports`
 3. Default-export the module class
-4. Call `super()` first in constructor
-5. Implement `destroy()` and call `super.destroy()` last
+
+You should also (recommended best practice, not validated):
+
+- Extend `ModuleBase` or `BaseThreeJsModule`
+- Call `super()` first in the constructor
+- Implement `destroy()` and call `super.destroy()` last
 
 Example:
 
@@ -251,18 +247,20 @@ Bad:
 
 4. **Be responsive**: Address review feedback promptly
 
-5. **Update your branch** if main has changed:
+5. **Target `develop`**: open your PR against the `develop` branch (this is required)
+
+6. **Update your branch** if `develop` has changed:
 
 ```bash
 git fetch upstream
-git rebase upstream/main
+git rebase upstream/develop
 ```
 
 ### Review Process
 
 - Maintainers will review your PR
 - They may request changes
-- Be patient—reviews take time
+- Be patient, reviews take time
 - Address feedback constructively
 
 ---
@@ -324,16 +322,7 @@ If your module needs assets, there are two cases:
 
 ### Module Categories
 
-Use appropriate categories:
-
-- `Text` - Text-based visuals
-- `GUI` - UI elements and overlays
-- `3D` - Three.js 3D graphics
-- `2D` - Canvas-based 2D graphics
-- `Data` - Data visualization
-- `Effects` - Visual effects and filters
-- `Particle` - Particle systems
-- `Examples` - Tutorial/example modules
+The `category` field in the docblock is a free-form label; it is not validated against a fixed list. The bundled starter modules use `2D`, `3D`, and `Text`. Pick a label that describes your module and stays consistent with related modules. See [MODULE_DEVELOPMENT.md](MODULE_DEVELOPMENT.md) for guidance.
 
 ---
 
@@ -375,7 +364,7 @@ A good bug report includes:
 ```
 - OS: macOS 13.2 / Windows 11
 - Node version: 20.x.x
-- App version: 1.0.0
+- App version: 0.5.0-beta
 ```
 
 ### 2. Steps to Reproduce
@@ -429,6 +418,20 @@ A good feature request includes:
 
 ## Testing Guidelines
 
+### Automated Checks
+
+Run these before submitting and make sure they pass:
+
+```bash
+npm run typecheck:all
+npm run test:unit
+npm run test:e2e
+npm run lint
+npm run build:renderer
+```
+
+For more detail on the test suites, see [RUNTIME_TS_TESTING_GUIDELINES.md](RUNTIME_TS_TESTING_GUIDELINES.md) for runtime/unit tests and [E2E_TESTING_GUIDELINES.md](E2E_TESTING_GUIDELINES.md) for end-to-end tests.
+
 ### Manual Testing
 
 Before submitting:

E2E_TESTING_GUIDELINES.md

@@ -12,6 +12,7 @@ This document is the standard we will follow (and enforce) for any future work i
 - **Boundary coverage**: Prefer tests that cross real boundaries (UI → IPC → disk JSON → projector messaging) when that’s the risk.
 - **No bloat**: Keep tests short, deterministic, and easy to maintain.
 - **Zero regression**: A failing E2E test should point to a real break (not flakiness).
+  - Note: `playwright.config.ts` retries up to 3 times locally, so a green local run can still mask intermittent flakiness (a test that only passed on a retry). Treat retried passes as a signal to fix the underlying instability, not as a clean result.
 
 ---
 
@@ -22,7 +23,7 @@ This document is the standard we will follow (and enforce) for any future work i
 - **No fixed sleeps.**
   - Do not add `setTimeout`/`sleep` waits. Use Playwright auto-waiting, `expect(...).toBeVisible()`, `waitForFunction`, `expect.poll`, etc.
 - **No brittle selectors.**
-  - Prefer stable selectors. If you can’t make it stable, don’t write the test yet—fix the UI contract first.
+  - Prefer stable selectors. If you can’t make it stable, don’t write the test yet. Fix the UI contract first.
 - **No mystery diffs.**
   - If you can’t explain a changed line, revert it.
 
@@ -97,7 +98,7 @@ Use “wait for truth” instead of “wait for time”:
 ### Scope rules: golden paths vs. small workflows
 
 - **Golden path tests**:
-  - 1–2 tests max
+  - 1-2 tests max
   - Prove the most important end-to-end “happy path”
   - Keep assertions minimal but meaningful
 

GETTING_STARTED.md

@@ -22,21 +22,11 @@ This guide covers installation, setup, and basic usage of nw_wrld.
 
 ## Installation
 
-### Developer Setup
-
 **Requirements:** Node.js v20+ and basic terminal knowledge
 
-```bash
-# Clone the repository
-git clone https://github.com/aagentah/nw_wrld.git
-cd nw_wrld
+To clone the repository, install dependencies, start the app, and learn what the two windows are, follow the [Installation (For Developers)](README.md#for-developers) section in the README.
 
-# Install dependencies
-npm install
-
-# Start the app
-npm start
-```
+The rest of this guide picks up from your first launch.
 
 ---
 
@@ -55,7 +45,7 @@ You have two options:
 
 nw_wrld will initialize your project folder with:
 
-- **16 starter modules** - Ready-to-use examples (Text, GridOverlay, SpinningCube, etc.)
+- **22 starter modules** - Ready-to-use examples (Text, GridOverlay, SpinningCube, etc.)
 - **Sample assets** - Images and JSON data files for experimentation
 - **Data storage** - Configuration, tracks, and recordings
 
@@ -65,7 +55,7 @@ Your project folder structure will look like this:
 
 ```
 MyProject/
-├── modules/           # Visual modules (16 starter modules included)
+├── modules/           # Visual modules (22 starter modules included)
 ├── assets/            # Images and JSON data
 │   ├── images/
 │   └── json/
@@ -97,7 +87,7 @@ Tracks are containers for visual modules and sequencer patterns.
 2. Select a module from the dropdown (e.g., **Text**, **GridOverlay**, **Corners**)
 3. Configure the module's initial properties if prompted
 
-**What are modules?** Modules are visual elements displayed in the Projector window. Your project includes 16 starter modules covering 2D graphics, 3D visuals, text, and data visualization.
+**What are modules?** Modules are visual elements displayed in the Projector window. Your project includes 22 starter modules covering 2D graphics, 3D visuals, text, and data visualization.
 
 ---
 
@@ -140,7 +130,7 @@ When the sequencer playhead hits an active cell, it triggers that channel's assi
 1. Click the **[PLAY]** button in the footer
 2. Watch the playhead move across the 16-step grid
 3. See your visuals respond to the pattern in the Projector window
-4. Adjust BPM in Settings (60-130 BPM)
+4. Adjust BPM in Settings (default 120)
 
 The pattern loops continuously until you click **[STOP]**.
 
@@ -156,7 +146,7 @@ One of nw_wrld's most powerful features is that you can edit modules and see cha
 
 1. Navigate to your project folder (the one you selected on first launch)
 2. Open the `modules/` directory
-3. You'll see all 16 starter modules as `.js` files
+3. You'll see all 22 starter modules as `.js` files
 
 ### Editing Modules
 
@@ -167,12 +157,14 @@ One of nw_wrld's most powerful features is that you can edit modules and see cha
 3. Save the file
 4. nw_wrld automatically detects the change and reloads the module
 
-**Option 2: Use the Built-in Editor (Optional)**
+**Option 2: View the Source via the Module Editor**
+
+The Module Editor modal does not edit modules in-app. It shows the module's source read-only and gives you a quick way to jump to the file.
 
-1. In Dashboard, go to Settings → Module Editor
-2. Select a module to edit
-3. Make changes in the Monaco editor
-4. Save → hot reload applies automatically
+1. In Dashboard, open the Module Editor for a module
+2. Read the source in the read-only viewer to find what you want to change
+3. Click the link to open the file in your own code editor
+4. Edit and save there, and nw_wrld hot-reloads the change automatically
 
 ### What You Can Change
 
@@ -197,7 +189,7 @@ Save the file and the module reloads automatically.
 
 ### Learning from Examples
 
-Study the 16 starter modules to learn different patterns:
+Study the 22 starter modules to learn different patterns:
 
 - **HelloWorld.js** - Simplest possible module
 - **Text.js** - DOM-based text rendering
@@ -389,6 +381,12 @@ $: note(r).midi("MIDI_port_name").midichan(1); // send to MIDI_port_name channel
 
 **libasound.so cannot open shared object file (Windows 11 + WSL/Ubuntu):**
 
+Electron needs the ALSA sound libraries, which are not installed by default on minimal WSL/Ubuntu setups. Install them, then start the app again:
+
+```bash
+sudo apt-get install libasound2 libasound2-dev
+```
+
 For more help, see [Troubleshooting](README.md#troubleshooting) in the README or check [GitHub Issues](https://github.com/aagentah/nw_wrld/issues).
 
 ---