CLAUDE.md

1# CLAUDE.md
2 
3This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4 
5## Build Commands
6 
7```bash
8npm run build:css        # Compile SCSS → expanded cyberpunk.css
9npm run build:css:min    # Compile SCSS → minified cyberpunk.min.css
10npm run scss:watch       # Watch SCSS and auto-compile to minified
11npm run lint:css         # Stylelint all SCSS files
12npm test                 # Jest unit tests (--runInBand)
13npm run test:watch       # Jest in watch mode
14npm run test:coverage    # Jest with coverage report
15npm run test:e2e         # Playwright end-to-end tests
16npm run pug:watch        # Watch/compile Pug templates to HTML
17```
18 
19Coverage thresholds are enforced at 70–80% globally (branches/functions/lines/statements).
20 
21## Architecture
22 
23### SCSS Entry Point
24`scss/cyberpunk.scss` composes all partials via Sass `@use` in this load order:
25 
261. **Core** — `_fonts.scss`, `_variables.scss`, `_mixins.scss`
272. **Base** — `_reset.scss`, `_base.scss`, `_colors.scss`, `_typography.scss`
283. **Components** — `_buttons.scss`, `_components.scss`, `_modal.scss`, `_toast.scss`, `_navbar.scss`, `_windows.scss`, `_netgraph.scss`
294. **Effects/layout** — `_crt.scss`, `_layout.scss`, `_code.scss`, `_terminal.scss`, `_hex.scss`
30 
31### Design Token Layer (`scss/_variables.scss`)
32All variables are declared with `!default` so consumers can override before importing. Covers color palette, breakpoints (XS 360px → XL 1300px), spacing scale (xxs 0.25rem → xxl 4rem), typography, z-index levels, transitions, and per-component variables.
33 
34### Theme System (`scss/_colors.scss`)
35Two built-in palettes: `cyberpunk` (default) and `matrix`. Access colors via the `cp-color($key)` function. The `theme-variables()` mixin switches CSS custom properties at `:root`. Utility classes `.bg-*` and `.txt-*` are auto-generated from the active palette.
36 
37### Key Mixins (`scss/_mixins.scss`)
38- `retro-border()` — CRT-style glowing border
39- `retro-glow-text()` — neon text glow
40- `crt-scanlines` — scanline overlay
41- `grid-bg()` — retro grid background
42 
43### JavaScript Modules (`scripts/`)
44Each file is a standalone ES module with a matching Jest test suite in `tests/`. `init.js` is the entry point and is excluded from coverage. Modules: `buttons`, `modals`, `toasts`, `navbar`, `hexviewer`, `netgraph`, `netgraph-markup` (HTML / `text/cp-netgraph` → topology), `sfx`. The `netgraph` module renders a large default viewBox (`1200×560`), optional directed arrow markers (`arrows`), and packet animation along `source` → `target` edges. Optional **`netgraph-vis.js`** wraps **vis-network** (npm dependency) for interactive layouts; it is not imported from `init.js`—load via `import('./scripts/netgraph-vis.js')`. See `docs/modules/netgraph.html`.
45 
46### Output Files
47Compiled CSS is committed to the repo root (`cyberpunk.css`, `cyberpunk.min.css`, and their source maps). Always rebuild after editing SCSS.
48