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/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