AI_Assistant/pcbjam
Watch
1
0
Fork
You've already forked pcbjam
 0
Code Issues Pull requests Projects Releases 7 Packages Wiki Activity Actions
pcbjam/docs
History
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Gergő Törcsvári ae33a100c2
 fix(asyncify): consume-once root suspensions — replaces the wake-window deferral 
The deferral (9ca2ac1) modeled the wrong condition and taxed every parked
fiber completion with a macrotask hop: under CI load that stretched
three-client apply chains and flaked drift-trio S4 twice consecutively
(26/26 green locally under stress) — retracted.

The actual fatal state, readable in all four prod stacks once seen: a SECOND
rewind of the same root suspension. Root suspends once per fiber_swap out of
it; two parked fibers completing against one root suspension epoch (a tool
fiber + a collab fiber both waking around open:settled) each drive
finishContextSwitch(root) — the second rewinds already-consumed data →
"unreachable executed" → poisoned runtime, with the wake-side "index out of
bounds" as the sibling symptom.

Cure: stop exempting root from the validity check the shim already keeps.
First consumption proceeds synchronously — zero added latency anywhere; the
second is refused ([wx-asyncify] "root suspension already consumed") — the
yielded fiber stays properly suspended and resumable, root continues via its
real pending resume, libcontext's ghost-epoch contract enforced one layer
lower. Root remains exempt only from the internally-parked quarantine (its
yield park is routine).

.ci-cache-epoch 4→5 (the epoch-4 cache holds the retracted deferral shim).

Local: fiber 2/2 + timer 1/1, firefox sweep 20 passed, drift-trio-scenarios
kicad-chromium 26/26 under 3-worker stress, web fatal+follow 2/2.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019SE4o46Lnq3hF574FFq8x4
2026-08-01 15:53:18 +02:00
..
debugging docs: ✏️ cleanup and organize docs 2026-06-05 12:16:13 +02:00
features fix(asyncify): consume-once root suspensions — replaces the wake-window deferral 2026-08-01 15:53:18 +02:00
research docs: ✏️ cleanup and organize docs 2026-06-05 12:16:13 +02:00
build.md refactor: collapse dual-mode plumbing — the DOM port is the only WASM build 2026-06-12 20:19:48 +02:00
ci-build-slowness-findings.md docs: CI build perf findings + parked wasm-exceptions experiment 2026-06-11 07:50:57 +02:00
README.md docs: ✏️ cleanup and organize docs 2026-06-05 12:16:13 +02:00
wasm-exceptions-experiment.md feat(wasm-eh): migrate the WASM build to native wasm exceptions (+ 3D viewer default-on) 2026-06-30 09:40:26 +02:00

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

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

Feature design docs

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

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)