diff --git a/.eslintignore b/.eslintignore
index ea488711f..551293df2 100644
--- a/.eslintignore
+++ b/.eslintignore
@@ -1,3 +1,2 @@
src/ui
-src/protocol-validation
network-canvas
diff --git a/.github/workflows/dist.yml b/.github/workflows/dist.yml
index 88d232af5..40915198b 100644
--- a/.github/workflows/dist.yml
+++ b/.github/workflows/dist.yml
@@ -9,9 +9,9 @@ on:
jobs:
dist:
- runs-on: ubuntu-20.04
+ runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@v3
+ - uses: actions/checkout@v4
with:
submodules: recursive
- uses: actions/setup-python@v4
@@ -21,13 +21,13 @@ jobs:
- name: Update apt cache
run: sudo apt-get update -y
# Set node version
- - uses: actions/setup-node@v2
+ - uses: actions/setup-node@v4
with:
node-version: "14.21.3"
- name: Set NPM 7
run: npm install -g npm@8.19.4
# Cache node_modules
- - uses: actions/cache@v2
+ - uses: actions/cache@v4
env:
cache-name: cache-node-modules
with:
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
index ee54f70e7..3322c7c59 100644
--- a/.github/workflows/main.yml
+++ b/.github/workflows/main.yml
@@ -9,9 +9,9 @@ on:
jobs:
test:
- runs-on: ubuntu-20.04
+ runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@v3
+ - uses: actions/checkout@v4
with:
submodules: recursive
- uses: actions/setup-python@v4
@@ -21,13 +21,13 @@ jobs:
- name: Update apt cache
run: sudo apt-get update -y
# Set node version
- - uses: actions/setup-node@v2
+ - uses: actions/setup-node@v4
with:
node-version: "14.21.3"
- name: Set NPM 7
run: npm install -g npm@8.19.4
# Cache node_modules
- - uses: actions/cache@v2
+ - uses: actions/cache@v4
env:
cache-name: cache-node-modules
with:
@@ -48,9 +48,9 @@ jobs:
build:
needs: test
- runs-on: ubuntu-20.04
+ runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@v3
+ - uses: actions/checkout@v4
with:
submodules: recursive
- uses: actions/setup-python@v4
@@ -60,13 +60,13 @@ jobs:
- name: Update apt cache
run: sudo apt-get update -y
# Set node version
- - uses: actions/setup-node@v2
+ - uses: actions/setup-node@v4
with:
node-version: "14.21.3"
- name: Set NPM 7
run: npm install -g npm@8.19.4
# Cache node_modules
- - uses: actions/cache@v2
+ - uses: actions/cache@v4
env:
cache-name: cache-node-modules
with:
diff --git a/.gitignore b/.gitignore
index f45501a7f..fdd34a823 100644
--- a/.gitignore
+++ b/.gitignore
@@ -13,6 +13,9 @@
# local dev build output
electron-dev/
+# electron-vite build output
+dist/
+
npm-debug.log*
yarn-debug.log*
yarn-error.log*
@@ -22,3 +25,4 @@ yarn.lock
*.pbxproj
.vscode
Icon^M^M
+*.tgz
diff --git a/.gitmodules b/.gitmodules
index 0d91b8345..ca53c5953 100644
--- a/.gitmodules
+++ b/.gitmodules
@@ -1,9 +1,7 @@
[submodule "network-canvas"]
path = network-canvas
url = https://github.com/complexdatacollective/network-canvas.git
-[submodule "src/protocol-validation"]
- path = src/protocol-validation
- url = https://github.com/complexdatacollective/protocol-validation.git
+
[submodule "development-protocol"]
path = development-protocol
url = https://github.com/complexdatacollective/development-protocol.git
diff --git a/.node-version b/.node-version
new file mode 100644
index 000000000..2bd5a0a98
--- /dev/null
+++ b/.node-version
@@ -0,0 +1 @@
+22
diff --git a/.npmrc b/.npmrc
new file mode 100644
index 000000000..f8f436a14
--- /dev/null
+++ b/.npmrc
@@ -0,0 +1,7 @@
+# Electron 34.x has native ARM64 support on Apple Silicon
+
+# Ignore scripts from optional dependencies that may fail
+ignore-scripts=false
+
+# Enable strict peer dependencies checking
+strict-peer-dependencies=false
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 000000000..766f0dd91
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,135 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Network Canvas Architect is an Electron + React application for designing Network Canvas interview protocols. It includes a git submodule (`network-canvas/`) which was previously used for interview preview functionality (currently disabled pending modernization).
+
+## Development Commands
+
+```bash
+# Install dependencies
+pnpm install
+
+# Development
+pnpm run dev # Start electron-vite dev server with HMR
+
+# Build
+pnpm run build # Build production bundle
+pnpm run preview # Preview production build
+
+# Testing (Vitest)
+pnpm test # Run tests once
+pnpm test:watch # Watch mode
+pnpm test:coverage # Run with coverage
+pnpm test:update-snapshots # Update snapshots
+
+# Linting
+pnpm run lint # Run both JS and SCSS linting
+pnpm run lint:js # ESLint only
+pnpm run sass-lint # Stylelint only
+
+# Distribution
+pnpm run dist:mac # macOS build (x64 + arm64)
+pnpm run dist:linux # Linux build
+pnpm run dist:win # Windows build
+```
+
+## Architecture
+
+### Build System
+
+electron-vite with custom configuration:
+- **electron.vite.config.js** - Main, preload, and renderer configuration
+- Main process files are copied (not bundled) due to CommonJS usage
+- Renderer uses Vite with React plugin
+
+### State Management
+
+Redux with ducks pattern (`src/ducks/`):
+- **store.js** - Redux store with redux-persist, thunk middleware
+- **modules/root.js** - Root reducer combining all slices
+- **modules/protocol/** - Protocol state (stages, codebook, assets) with timeline middleware for undo/redo
+- **modules/session.js** - Current editing session state
+- **modules/ui/** - UI state (screens, dialogs)
+
+Protocol actions are prefixed with `PROTOCOL/` and tracked by the timeline middleware for undo/redo support.
+
+### Selectors
+
+Reselect-based selectors in `src/selectors/`:
+- **protocol.js** - Current protocol data
+- **codebook/** - Node/edge types, variables
+- **indexes.js** - Derived indexes for fast lookups
+- **usage.js** - Track where variables/types are used
+
+### Import Aliases
+
+Configured in `electron.vite.config.js` and `vitest.config.js`:
+- `@app` → `src/`
+- `@components` → `src/components/`
+- `@modules` → `src/ducks/modules/`
+- `@selectors` → `src/selectors/`
+- `@hooks` → `src/hooks/`
+- `@utils` → `src/utils/`
+
+### Key Directories
+
+- **src/components/sections/** - Stage editor section components (prompts, forms, panels per interview stage type)
+- **src/components/StageEditor/** - Stage editing UI
+- **src/components/Form/** - Redux-form field components
+- **src/components/Codebook/** - Codebook (types/variables) management UI
+- **src/utils/netcanvasFile/** - `.netcanvas` file format handling (read/write protocols)
+- **src/utils/electronBridge.js** - Secure IPC bridge abstraction for renderer process
+- **src/behaviours/** - Higher-order components for zoom, validation, windowing
+
+### Protocol Structure
+
+A protocol contains:
+- `stages[]` - Interview stages configuration
+- `codebook` - Node types, edge types, ego, and their variables
+- `assetManifest` - Media assets (images, audio, video, external data)
+
+### Electron Integration
+
+Security hardened with context isolation:
+- **public/electron-starter.js** - Electron main process entry
+- **public/preload/appPreload.js** - Secure IPC bridge (contextBridge)
+- **public/components/ipcHandlers.js** - Main process IPC handlers
+- **src/utils/electronBridge.js** - Renderer-side abstraction for IPC
+
+All Node.js operations happen in the main process via IPC. The renderer has no direct Node.js access.
+
+## Testing
+
+Vitest with Enzyme. Test files use `.test.js` suffix and are co-located with source files in `__tests__/` directories.
+
+Test setup: `config/vitest/setup.js`
+Mock files: `src/__mocks__/`
+
+Snapshot testing is used for component rendering. Update snapshots with:
+```bash
+pnpm test:update-snapshots
+```
+
+## Code Style
+
+- ESLint with Airbnb config
+- Stylelint for SCSS
+- Prettier for formatting (via VSCode)
+- React 16 with class components and hooks
+- Redux-form for form state
+
+## Prerequisites
+
+- Node.js 22.x (LTS)
+- pnpm 9.x
+
+## Security
+
+This application uses Electron's recommended security model:
+- `nodeIntegration: false`
+- `contextIsolation: true`
+- Preload scripts with contextBridge for IPC
+- All file system operations via main process
diff --git a/README.md b/README.md
index 40066966a..464075a62 100644
--- a/README.md
+++ b/README.md
@@ -12,10 +12,10 @@ For questions and support, please visit the [Network Canvas User Community](http
### Prerequisites
-- [Node.js](https://nodejs.org/en/) (v14.21.3)
-- [npm](https://www.npmjs.com/) (v8.19.4)
+- [Node.js](https://nodejs.org/en/) (v22.x LTS) - Use [fnm](https://github.com/Schniz/fnm) or [nvm](https://github.com/nvm-sh/nvm) for version management
+- [pnpm](https://pnpm.io/) (v9.x) - Install via `corepack enable` or `npm install -g pnpm`
- [Git](https://git-scm.com/)
-- [Python](https://www.python.org/) (v3.10.12)
+- [Python](https://www.python.org/) (v3.10+) - For native module compilation
### Installation
@@ -31,36 +31,33 @@ git clone https://github.com/complexdatacollective/Architect.git
git submodule update --init --recursive -f
```
-3. Install NPM packages
+3. Install packages with pnpm
```sh
-npm install
+pnpm install
```
-Note: for Apple Silicon users, you need to install the `electron` package manually:
-
-```sh
- npm install electron --arch=x86
-```
+Note: The `.npmrc` file configures x64 architecture for Electron (required until Electron upgrade is complete).
# Operation
-| `npm run
+
+