README.md

Documentation Map

A central index of the documentation in this repo. The goal of the project is to build KiCad with WASM and run it in a browser.

Note: per-area README.md files stay next to the code they describe (they're linked below). Cross-cutting guides live under docs/. Per-feature design notes live under features/.

Start here

• Project README — overview, prerequisites, quick start, project structure
• CLAUDE.md — project/agent context and contribution conventions

Build

• docs/build.md — Docker-based KiCad WASM build system (two-phase build, outputs, memory)
• docker/README.md — Docker build environment, branch-specific containers, troubleshooting
• wasm/README.md — WASM compatibility layer (overrides/shims without patching KiCad)

Debugging & Asyncify

• docs/debugging/DEBUG.md — debugging guide: Asyncify stalls vs crashes, shim/codegen coupling, stub-bisection
• docs/debugging/learning.md — Asyncify + consecutive modal dialogs: the lock pattern
• docs/research/threading_1.md — deep dive: the Asyncify single-slot currData collision bug and the fix
• docs/research/threading_2.md — external research: JSPI/WasmFX/state-machine alternatives, QEMU analysis

Architecture

• wasm/README.md — WASM compatibility layer structure
• web/README.md — web app (create/open KiCad projects), tech stack, URL routing, WASM artifact serving

Testing

• tests/README.md — Playwright test infrastructure, element registry, logs, screenshots
• tests/WHATWORKS.md — wxWidgets-in-WASM feature coverage matrix and KiCad readiness
• tests/GL_README.md — Emscripten legacy GL immediate-mode quirks (color-per-vertex)
• tests/gal-regression/README.md — GAL visual regression suite (native OpenGL vs WebGL WASM)

Feature design docs

Per-feature design notes and porting records live under features/:

• web-init — web app spec
• schematic — eeschema WASM bring-up
• symbol-editor — symbol editor (eeschema kiface launcher)
• gerbview — Gerber viewer port
• pl-editor — page-layout editor port (incl. file-dialog usability fixes)
• browser-tools — tool-activation / coroutine deep dives
• fix-asyncify-O2-and-modal-promise-rejection — RTree wasm overflow bug investigation

Archived / historical

features/archive/ holds docs whose work is done or superseded (each carries a status banner):

• webgl — WebGL-GAL strategy/plan (since implemented in kicad/common/gal/webgl/)
• ipc-api — IPC-API guard cleanup TODO (revert not yet actioned)