ci: run lint, tests, and production build on PRs and main

.github/workflows/ci.yml

@@ -0,0 +1,48 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  check:
+    name: Lint, test, build
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: avatar
+    env:
+      # Nothing here launches Electron: the unit-tested modules deliberately
+      # avoid require('electron'), so the ~100 MB binary is dead weight.
+      ELECTRON_SKIP_BINARY_DOWNLOAD: 1
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Set up Node
+        uses: actions/setup-node@v5
+        with:
+          # Vite 7 needs ^20.19.0 || >=22.12.0.
+          node-version: 22
+          cache: npm
+          cache-dependency-path: avatar/package-lock.json
+
+      - name: Install
+        run: npm ci
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Test
+        run: npm test
+
+      - name: Build
+        run: npm run build

CHANGELOG.md

@@ -6,10 +6,22 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+### Added
+
+- GitHub Actions CI on pull requests and `main`: `npm ci` → `lint` → `test` → `build` in `avatar/` (Node 22; Electron binary download skipped). See [Contributing](CONTRIBUTING.md#continuous-integration) and [Project layout](docs/development/project-layout.md). (#4, #35)
+- README CI status badge.
+
 ### Changed
 
 - Rename the app package directory from `avatar-demo/` to `avatar/`. Contributor paths (`cd avatar`, docs, `.gitignore`) updated; the Windows installer is unchanged.
 - Docs and README: add desktop companion GIFs (`AVATAR_M5_*`) for overlay, Settings scroll, animations, custom environments, and Camera & Lighting.
+- ESLint covers `src/`, `electron/**/*.cjs`, and build scripts (`scripts/`, config files); `npm run lint` enforces `--max-warnings=0`. (#34)
+- Expand [Contributing](CONTRIBUTING.md) for ripple effects, changelog style with issue/PR numbers, CI expectations, and guidance for human and AI contributors.
+
+### Fixed
+
+- Capture the Three.js group once in `VrmAvatar` so effect cleanup detaches from the same container the model was attached to (avoids orphan scenes on avatar swap). (#34)
+- Drop unused `audioFile` prop from `VoicePanel` (file input is uncontrolled). (#34)
 
 ## [0.5.0] — 2026-08-06
 

CONTRIBUTING.md

@@ -31,10 +31,13 @@ npm install
 | Production-like Electron on `dist/` | `npm run desktop` |
 | Browser only | `npm run dev` → http://localhost:5173 |
 | Lint | `npm run lint` |
+| Unit tests (Electron modules) | `npm test` |
 | Vite production build | `npm run build` |
 | Windows installer (local output under `desktop-setup/`) | `npm run dist:win` |
 | Regenerate bundled avatar thumbnails | `npm run thumbs` |
 
+Pull requests and pushes to `main` run the same **lint → test → build** sequence in GitHub Actions (see [Continuous integration](#continuous-integration)). Run those three locally before opening a PR.
+
 End users can use [AVATAR-Setup-0.5.0.exe](https://github.com/ARPAHLS/avatar/releases/download/v0.5.0/AVATAR-Setup-0.5.0.exe) without Node.
 
 ### Bundled avatar thumbnails
@@ -78,20 +81,33 @@ AVATAR is small but cross-cutting. When you change behavior, ask what else must
 | Installer / packaging | [Installation](docs/getting-started/installation.md), [releases](docs/releases/README.md) if user-facing, `avatar/build/` assets, `package.json` `build` field |
 | Public API of preload / IPC | Every `window.voxDesktop` (or equivalent) caller; keep `preload.cjs` and `main.cjs` in sync |
 | Labels or issue forms | [`.github/labels.yml`](.github/labels.yml) (CI syncs labels) — do not invent one-off label names in templates |
+| Lint / ESLint scope | `avatar/eslint.config.js` (renderer `src/`, Electron `electron/**/*.cjs`, scripts) — keep Node vs browser globals correct |
+| CI workflow | [`.github/workflows/ci.yml`](.github/workflows/ci.yml), [Project layout](docs/development/project-layout.md#continuous-integration), README CI badge if the workflow name/path changes |
+| Package scripts / Node engines | `avatar/package.json`, install docs if contributors must change Node version |
+| Roadmap item shipped | [Roadmap](docs/development/roadmap.md) checkboxes |
 
 ### Docs, changelog, and README
 
-For **user-visible** changes:
+For **user-visible** or **contributor-visible** changes (behavior, install, CI, lint gates):
 
-1. **`CHANGELOG.md`** — add a bullet under `[Unreleased]` (`Added` / `Changed` / `Fixed` / `Removed`). Keep it short; say *why it matters*, not every file touched.
+1. **`CHANGELOG.md`** — add a bullet under `[Unreleased]` (`Added` / `Changed` / `Fixed` / `Removed`). Keep it short; say *why it matters*, not every file touched. Prefer **issue and PR numbers** when known, matching the style under published releases (e.g. `(#4, #35)`). Do not use `Closes`/`Fixes` keywords inside changelog text.
 2. **Feature docs** — update the guide that describes the behavior (see table above). Do not leave docs describing the old path.
 3. **`docs/using-the-app.md`** — update if menus, defaults, or the main walkthrough change.
 4. **`README.md`** — only if Quick start, install order, badges/links, or high-level “what this is” change. Keep README lite; deep detail stays in `docs/`.
 5. **Screenshots** — replace or add under `docs/screenshots/` when the UI in docs would mislead; keep filenames stable when replacing in place.
 6. **`CITATION.cff` / release notes** — only when versioning or release messaging changes (maintainers).
+7. **`docs/development/roadmap.md`** — mark shipped items when a tracked milestone lands.
 
 Docs-only PRs still need a clear description; changelog entry optional unless the doc fix is user-facing correction of wrong instructions.
 
+### Continuous integration
+
+- Workflow: [`.github/workflows/ci.yml`](.github/workflows/ci.yml) on every pull request and on pushes to `main`.
+- Steps (in `avatar/`): `npm ci` → `npm run lint` → `npm test` → `npm run build`.
+- Node **22** (Vite 7 compatible). Electron’s binary is **not** downloaded in CI (`ELECTRON_SKIP_BINARY_DOWNLOAD`); unit tests must not `require('electron')` at load time.
+- Windows installer (`dist:win`) is **not** run in CI — too heavy and Windows-specific; verify locally when you touch packaging.
+- A failing CI check blocks confidence for merge; fix lint/tests/build in the same PR when you introduce the breakage.
+
 ### Desktop vs browser parity
 
 - If a feature is **Electron-only**, say so in UI copy and docs; do not silently no-op in a confusing way when possible.
@@ -105,6 +121,18 @@ Docs-only PRs still need a clear description; changelog entry optional unless th
 - Desktop: `electron/settingsStore.cjs` → `config.yaml` in userData.
 - Changing keys or defaults can break existing user configs — prefer migrations or tolerant reads; document resets in [User settings](docs/user-settings.md).
 
+### For AI coding agents (and humans using them)
+
+Treat the repo as a **product + docs** unit, not a single-folder code patch:
+
+1. **Read before editing** — [Using the app](docs/using-the-app.md), the feature doc for the area, and this ripple table.
+2. **Electron vs browser** — do not claim desktop-only behavior works in `npm run dev` without checking.
+3. **Complementary files in the same PR** — code + catalogs + preload/main + docs + `CHANGELOG.md` `[Unreleased]` + screenshots when the UI story changes. Avoid “follow-up later” for obvious ripples (changelog, user guide line, roadmap checkbox).
+4. **Changelog** — Keep a Changelog sections; short *why*; include `#issue` / `#PR` when known (see [0.5.0](CHANGELOG.md) entries).
+5. **Do not commit** secrets, `desktop-setup/*.exe`, or gitignored `custom/` media.
+6. **Verify** — `npm run lint`, `npm test`, and `npm run build` in `avatar/` (same as CI). Use `dev:desktop` for overlay/audio smoke tests.
+7. **PR description** — what / why / how tested / leftover follow-ups that are genuinely optional.
+
 ---
 
 ## Assets and licensing
@@ -120,14 +148,14 @@ Docs-only PRs still need a clear description; changelog entry optional unless th
 
 Before you open a PR:
 
-- [ ] `npm run lint` and `npm run build` pass in `avatar/`
+- [ ] `npm run lint`, `npm test`, and `npm run build` pass in `avatar/`
 - [ ] Smoke-tested the path you changed (`dev:desktop` and/or `dev` as appropriate)
 - [ ] Catalogs / config updated if you added assets or options
 - [ ] Electron preload ↔ main IPC still aligned (if you touched desktop APIs)
-- [ ] `CHANGELOG.md` `[Unreleased]` updated for user-visible changes
-- [ ] Relevant docs (and screenshots if needed) updated
+- [ ] `CHANGELOG.md` `[Unreleased]` updated for user- or contributor-visible changes (with issue/PR numbers when known)
+- [ ] Relevant docs (and screenshots if needed) updated; roadmap touched if a listed item shipped
 - [ ] No secrets, local `custom/` media, or `desktop-setup/` installer binaries committed
-- [ ] PR description states **what** changed, **why**, and any **follow-ups**
+- [ ] PR description states **what** changed, **why**, how you **tested**, and any **follow-ups**
 
 ---
 

README.md

@@ -10,6 +10,7 @@
 
 <div align="center">
   <a href="https://github.com/ARPAHLS/avatar/releases/download/v0.5.0/AVATAR-Setup-0.5.0.exe"><img src="https://img.shields.io/badge/Version-0.5.0-b8d4f0?style=flat-square" alt="Version 0.5.0" /></a>
+  <a href="https://github.com/ARPAHLS/avatar/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/ARPAHLS/avatar/ci.yml?branch=main&style=flat-square&label=CI" alt="CI" /></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-ffb38a?style=flat-square" alt="License MIT" /></a>
   <a href="https://vrm.dev/ja/"><img src="https://img.shields.io/badge/BOOTH-VRM-f87171?style=flat-square" alt="BOOTH VRM" /></a>
   <a href="https://hub.vroid.com/en/"><img src="https://img.shields.io/badge/VRoid-Hub-f0d78c?style=flat-square" alt="VRoid Hub" /></a>

docs/development/project-layout.md

@@ -42,8 +42,12 @@ End users personalize via **Settings → Directories** and **VRoid Hub** (see [U
 | `npm run dev:desktop` | Contributors | Vite + Electron (hot reload) |
 | `npm run dist:win` | Contributors | Build Windows NSIS installer (local `desktop-setup/` output) |
 | `npm run build` | CI / web | Production Vite bundle |
-| `npm run lint` | Contributors | ESLint |
-| `npm test` | Contributors | Electron unit tests |
+| `npm run lint` | Contributors / CI | ESLint (`src/`, `electron/**/*.cjs`, scripts; `--max-warnings=0`) |
+| `npm test` | Contributors / CI | Electron unit tests (`electron/*.test.cjs`) |
 | `npm run thumbs` | Contributors | Re-render committed avatar portraits into `src/assets/avatars/thumbs/` |
 
+### Continuous integration
+
+Pull requests and pushes to `main` run [`.github/workflows/ci.yml`](../../.github/workflows/ci.yml): install → lint → test → production build in `avatar/` on Ubuntu (Node 22). The workflow does **not** build the Windows installer (`dist:win`) and skips downloading the Electron binary (`ELECTRON_SKIP_BINARY_DOWNLOAD`) because unit tests do not launch Electron. Label sync remains a separate workflow (`.github/workflows/sync-labels.yml`).
+
 Run `npm run thumbs` whenever a bundled `.vrm` or the `config/avatars.js` catalog changes, and commit the PNGs — the Appearance picker reads those files rather than rendering a live preview. Custom-folder avatars are cached at runtime under Electron `userData/thumbnails/` instead. See [Contributing](../../CONTRIBUTING.md#bundled-avatar-thumbnails).

docs/development/roadmap.md

@@ -41,7 +41,8 @@
 - [ ] Avatar thumbnail follow-ups (pre-warm, sidecars, cache prune) (#21)
 - [ ] Environments picker flicker / GIF size (#22)
 - [ ] Code-signed Windows installer
-- [ ] Broader CI (lint / build)
+- [x] Broader CI (lint / test / build) (#4, #34, #35)
 - [ ] Asset license audit and manifest
 - [ ] Security review for capture permissions copy
 - [ ] Harden VRoid Hub VRM download for restrictive networks / CDN paths
+- [ ] Docs visual overhaul (reshoot screenshots / GIFs, layout rules)