test(kicad): timer-park repro lever — deterministic concurrent-Asyncify window

kicadTestArmTimerPark(delayMs, parkMs): a one-shot wxTimer whose Notify()
emscripten_sleep()s, entering through the exact GAL-refresh-timer path
(emscripten_async_call → TimerCallbackFunc::Run → dispatch guard → Notify) —
the fresh-entry-that-parks the prod board-load trap family needs. Pollable
kicadTestTimerParkState(); inert unless armed. Registered beside
kicadTestSetOpenPark in pcbnew + the merged kicad_editor image.

tests/kicad/timer-park-repro.spec.ts drives four escalating cycles (park
only, 2× + fiber hammering, + 256MB heap growth mid-park) and asserts the
runtime survives every rewind AND that the [wx-asyncify] diagnostics observed
the window — engagement is asserted, so a run where the lever never created
the overlap cannot pass vacuously.

Result so far (docs/features/async/15-timer-park-repro.md): GREEN through
both rounds — genuine double-parks, live currData cross-restores, fiber
swaps, and mid-park heap growth are all handled by the shim + runtime. The
prod trap needs an ingredient this window still lacks (ranked in the doc);
the spec stays as the regression gate for whatever the eventual fix is.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019SE4o46Lnq3hF574FFq8x4

wasm/bindings/kicad_editor_embind.cpp

@@ -41,6 +41,7 @@
 
 #include "pcbjam_libs_reload.h"
 #include "open_gate.h"
+#include "timer_park.h"
 
 using namespace emscripten;
 
@@ -175,6 +176,18 @@ static void kicadTestSetOpenPark( int aMs )
     pcbjam_open::testParkMs() = aMs;
 }
 
+// Test-only (timer-park repro, timer_park.h): a one-shot wx timer whose
+// Notify() Asyncify-parks — the deterministic concurrent-park window.
+static bool kicadTestArmTimerPark( int aDelayMs, int aParkMs )
+{
+    return pcbjam_timer_park::arm( aDelayMs, aParkMs );
+}
+
+static std::string kicadTestTimerParkState()
+{
+    return pcbjam_timer_park::stateJson();
+}
+
 
 // Canvas-only chrome toggle (features/mobile): hide/show every AUI pane
 // except the central draw canvas, plus the menubar and status bar, so the GAL
@@ -529,6 +542,8 @@ EMSCRIPTEN_BINDINGS(kicad_editor) {
     function("kicadOpenFile", &kicadOpenFile);
     function("kicadOpenFileBusy", &kicadOpenFileBusy);
     function("kicadTestSetOpenPark", &kicadTestSetOpenPark);
+    function("kicadTestArmTimerPark", &kicadTestArmTimerPark);
+    function("kicadTestTimerParkState", &kicadTestTimerParkState);
 
     // Canvas-only mobile mode (features/mobile).
     function("kicadSetChrome", &kicadSetChrome);

wasm/bindings/pcbnew_embind.cpp

@@ -53,6 +53,7 @@
 #include "collab_common.h"
 #include "collab_presence_core.h"
 #include "open_gate.h"
+#include "timer_park.h"
 #include "collab_presence_style.h"
 #include "pcbjam_theme.h"
 #include "pcbjam_libs_reload.h"
@@ -124,6 +125,18 @@ void kicadTestSetOpenPark( int aMs )
     pcbjam_open::testParkMs() = aMs;
 }
 
+// Test-only (timer-park repro, timer_park.h): a one-shot wx timer whose
+// Notify() Asyncify-parks — the deterministic concurrent-park window.
+bool kicadTestArmTimerPark( int aDelayMs, int aParkMs )
+{
+    return pcbjam_timer_park::arm( aDelayMs, aParkMs );
+}
+
+std::string kicadTestTimerParkState()
+{
+    return pcbjam_timer_park::stateJson();
+}
+
 // Read-only viewer lock (read-only-viewer): flips the process-global
 // PCBJAM_READ_ONLY flag consumed by TOOL_MANAGER (view-only action allowlist)
 // and the selection tools (nothing selectable), and mirrors it onto the
@@ -2386,6 +2399,8 @@ EMSCRIPTEN_BINDINGS(pcbnew) {
     function("kicadOpenFile", &kicadOpenFile);
     function("kicadOpenFileBusy", &kicadOpenFileBusy);
     function("kicadTestSetOpenPark", &kicadTestSetOpenPark);
+    function("kicadTestArmTimerPark", &kicadTestArmTimerPark);
+    function("kicadTestTimerParkState", &kicadTestTimerParkState);
     function("kicadCollabFiberBusy", &kicadCollabFiberBusyProbe);
     // Read-only viewer lock (read-only-viewer).
     function("kicadSetReadOnly", &kicadSetReadOnly);

wasm/bindings/timer_park.h

@@ -0,0 +1,106 @@
+/*
+ * Test-only deterministic repro lever for the production board-load trap
+ * family ("index out of bounds" / "unreachable executed" in doRewind —
+ * gal-refresh-timer investigation, docs/features/async/14-open-settle-gate.md
+ * lineage).
+ *
+ * The surviving hypothesis after the v0.1.19 crash log (2026-07-31): a wx
+ * timer callback is a FRESH JS→wasm entry (emscripten_async_call →
+ * TimerCallbackFunc::Run → Notify). The main loop is Asyncify-parked in
+ * wxWasmYieldToBrowser for most of wall-clock time, so a timer handler that
+ * itself parks creates TWO live Asyncify contexts over the single-slot
+ * Asyncify.currData — the emscripten #9153 family the handlesleep.js shim
+ * silently repairs. Add a fiber swap (the collab entries run on
+ * TOOL_MANAGER coroutines — emscripten_fiber_swap, which bypasses the shim's
+ * allocateData accounting entirely) and the prod trap's exact second stack
+ * (doRewind → finishContextSwitch under __asyncjs__wxWasmYieldToBrowser)
+ * becomes constructible on demand.
+ *
+ * Natural occurrences need a timer handler that parks mid-paint (GAL init /
+ * lib bridge) — scheduler-dependent, never reproduced locally in 10+
+ * attempts. This lever makes the window deterministic: arm a one-shot wx
+ * timer whose Notify() emscripten_sleep()s for a fixed time; the e2e then
+ * hammers fiber-based collab entries through the window and asserts the
+ * runtime SURVIVES (red on a build where the hypothesis holds).
+ *
+ * Production is unaffected: nothing fires unless kicadTestArmTimerPark is
+ * called.
+ */
+#pragma once
+
+#include <cstdio>
+#include <string>
+
+#include <emscripten.h>
+#include <wx/app.h>
+#include <wx/timer.h>
+
+namespace pcbjam_timer_park
+{
+
+struct State
+{
+    int  parkMs = 0;
+    int  fired  = 0;   // Notify() entries
+    int  done   = 0;   // Notify() completions (park survived + rewound)
+    bool parked = false;
+};
+
+inline State& state()
+{
+    static State s_state;
+    return s_state;
+}
+
+/**
+ * The timer under test. Notify() runs as a fresh JS→wasm entry under
+ * TimerCallbackFunc::Run's wxWasmDispatchGuard (src/wasm/timer.cpp), exactly
+ * like the GAL refresh timer — then parks, which is what the GAL handler is
+ * suspected of doing (paint → lib bridge / GAL init) on the crashing loads.
+ * While it is parked, wxWasmDispatchParked() reads true, so every OTHER due
+ * timer spins the 17 ms retry loop — the [wx-timer] storm diagnostic should
+ * report the window, validating that channel too.
+ */
+class ParkingTimer : public wxTimer
+{
+public:
+    void Notify() override
+    {
+        ++state().fired;
+        state().parked = true;
+
+        if( state().parkMs > 0 )
+            emscripten_sleep( state().parkMs );
+
+        state().parked = false;
+        ++state().done;
+    }
+};
+
+/** Arm one shot: fire in aDelayMs, park Notify() for aParkMs. */
+inline bool arm( int aDelayMs, int aParkMs )
+{
+    // Lazy: a wxTimer needs the app/traits up, and by the time a test can
+    // call embind the app long is.
+    static ParkingTimer* s_timer = nullptr;
+
+    if( !wxTheApp )
+        return false;
+
+    if( !s_timer )
+        s_timer = new ParkingTimer();
+
+    state().parkMs = aParkMs;
+    return s_timer->StartOnce( aDelayMs );
+}
+
+/** JS-pollable progress of the armed shot. */
+inline std::string stateJson()
+{
+    char buf[96];
+    snprintf( buf, sizeof( buf ), "{\"fired\":%d,\"done\":%d,\"parked\":%s,\"parkMs\":%d}",
+              state().fired, state().done, state().parked ? "true" : "false", state().parkMs );
+    return buf;
+}
+
+} // namespace pcbjam_timer_park