Phase B: main-thread sleep parks its context; the real D blocker is DOM entries

wasm/shims/context_sleep.cpp: a main-thread nanosleep whose frame stands on a
scheduler context that OWNS the stack arms a mailbox wake and yield_parks that
context instead of suspending the stack in place. It lives in the sleep
primitive rather than in tool_manager.cpp on purpose - KiCad and the wx core
stay untouched (CLAUDE.md's fork rule) and the whole K7 class moves at once,
not just TOOL_MANAGER::RunSynchronousAction's spin loop.

MEASURED AT D-ON, and it is NOT what unblocks Phase D. The four canvas-tool
specs still fail, but the trace now names a different cause: the fatal swap is
old=<libcontext ROOT> new=<tool coroutine> with mouseEventHandlerFunc above it
- a DOM mouse handler entering wasm DIRECTLY on the main stack, bypassing the
tick. So one coroutine is entered two ways: by the tick through the dispatch
context as a STAR TRANSFER, and by DOM handlers as a DIRECT SYMMETRIC SWAP. A
capture written by one path cannot be rewound by the other -> index out of
bounds in doRewind. That is section 7 rule 5 (partial migration is worse than
none) in its purest measured form, and it is why the harness stays green: its
coroutines are only ever entered from one place.

So the next increment is the DOM event entries (mouse/key/wheel/resize must
hand their events to the dispatch context as the tick does), not another park
site. It subsumes the one-root work too: with no dispatch on the main stack,
resolve_root_identity() always answers "the running context".

Landing state: STAR_DISPATCH=0, kicad 139 passed / 1 (pre-existing occ-probe)
= baseline, with the sleep shim in and inert.

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

wasm/shims/context_sleep.cpp

@@ -0,0 +1,109 @@
+/*
+ * Main-thread sleep as a CONTEXT PARK (docs/features/async/22, Phase B).
+ *
+ * THE PROBLEM THIS SOLVES. `nanosleep` on the main thread yields via Asyncify
+ * (see nanosleep_yield.c): it parks THE STACK IT STANDS ON. Doc 21 filed that
+ * as K7, the "anywhere" class, and its worst caller is a loop inside a tool
+ * body — TOOL_MANAGER::RunSynchronousAction spins
+ *
+ *     while( synchronousControl == STS_RUNNING ) { wxYield(); wxMilliSleep(1); }
+ *
+ * (kicad/common/tool/tool_manager.cpp:370-371). Every canvas edit/draw/move
+ * action goes through it. An in-place park there means a tool stack sits
+ * mid-Asyncify-suspension while a nested wxYield() dispatch runs on top of it,
+ * and once the scheduler owns dispatch (Phase D) a star transfer aimed at that
+ * stack rewinds a capture that is still in flight: `index out of bounds` in
+ * doRewind — the blue screen, measured on four canvas-tool specs 2026-08-07.
+ *
+ * THE FIX. When the sleeping frame stands on a scheduler context that OWNS
+ * that stack, the wait becomes what every other migrated wait already is: arm
+ * a timed wake, YIELD THE CONTEXT, and let the scheduler resume it. Nothing
+ * is suspended in place, so there is no in-flight capture for a transfer to
+ * land on, and the caller's `for(;;)`-shaped poll keeps its exact semantics —
+ * it just waits by yielding instead of by suspending.
+ *
+ * WHY HERE AND NOT IN KiCad. The loop is upstream KiCad code, and CLAUDE.md
+ * asks the fork to stay close to upstream. Routing this through the sleep
+ * primitive keeps KiCad and the wx core untouched AND fixes the whole K7 class
+ * at once (every main-thread sleep_for/wxMilliSleep reached on a context), not
+ * just the one caller that happened to be measured.
+ *
+ * WHY THE POLL DOESN'T NEED A SIGNAL. The waited-for state (an atomic set by a
+ * later dispatch) has no wake source of its own, so this keeps polling — the
+ * caller's contract. What changes is only which stack the wait suspends. The
+ * dispatch that eventually flips the atomic runs on a DIFFERENT context: the
+ * tick reuses an idle dispatch context or makes one when all are parked
+ * deeper (the idle-reuse set), which is exactly why that change had to land
+ * before this one.
+ */
+
+#include <wx/wasm/private/sched_context.h>
+
+#include <cstdint>
+
+// The scheduler mailbox (wx/wasm/private/mailbox.h). A timer message is the
+// wake source: it is delivered from a fresh JS task on the main stack, which
+// is where a resume is allowed to happen.
+extern "C" void wxWasmMailboxEnqueueAfter( void ( *aFn )( void* ), void* aArg, int aMillisecs );
+
+// Does some wx pump already own this context's wake (the main loop's rAF, a
+// dispatch context's tick)? Parking such a context here would give it TWO
+// owners, and the second wake resumes a capture the first already consumed —
+// measured 2026-08-07 as a doRewind trap through wxWasmArmFrameWake. Those
+// contexts keep the in-place yield; the tool coroutines this exists for have
+// no other wake source, which is precisely why their wait must park.
+extern "C" int wxWasmContextWakeIsPumpOwned( unsigned aId );
+
+namespace
+{
+
+void wake_sleeper( void* aArg )
+{
+    const pcbjam_sched::ContextId id =
+            static_cast<pcbjam_sched::ContextId>( reinterpret_cast<uintptr_t>( aArg ) );
+
+    // mark_ready never resumes inline (doc 13 §1.4); drain_all performs the
+    // entry from this clean mailbox-tick stack.
+    if( pcbjam_sched::mark_ready( id, 0 ) )
+        pcbjam_sched::drain_all();
+}
+
+}  // namespace
+
+extern "C" {
+
+/**
+ * Park the running context for aMillisecs instead of suspending this stack.
+ *
+ * Returns 1 if the wait was taken as a context park, 0 if the caller must fall
+ * back to the in-place Asyncify yield — which is the right answer whenever no
+ * context owns this stack: the main loop itself, a bridge entered before the
+ * scheduler exists, or a libcontext fiber swapped in above a context (yielding
+ * there would save the WRONG stack — doc 22 §7 rule 4, enforced by
+ * can_yield_here()).
+ */
+int pcbjam_context_sleep_ms( double aMillisecs )
+{
+    const pcbjam_sched::ContextId self = pcbjam_sched::current();
+
+    if( !self || !pcbjam_sched::can_yield_here() )
+        return 0;
+
+    if( wxWasmContextWakeIsPumpOwned( self ) )
+        return 0;
+
+    // Round up: a 0 ms mailbox delay would re-enter this poll in the same
+    // macrotask chain and spin the CPU exactly as the sleep exists to avoid.
+    int delay = static_cast<int>( aMillisecs );
+
+    if( delay < 1 )
+        delay = 1;
+
+    wxWasmMailboxEnqueueAfter( &wake_sleeper,
+                               reinterpret_cast<void*>( static_cast<uintptr_t>( self ) ),
+                               delay );
+    pcbjam_sched::yield_park( "main-thread-sleep" );
+    return 1;
+}
+
+}  // extern "C"

wasm/shims/nanosleep_yield.c

@@ -33,13 +33,28 @@ EM_ASYNC_JS( void, __wasm_main_thread_yield_ms, ( double ms ), {
     await new Promise( function( resolve ) { setTimeout( resolve, ms ); } );
 } );
 
+/*
+ * Scheduler-aware sleep (context_sleep.cpp, docs/features/async/22 Phase B):
+ * when this frame stands on a scheduler context that owns the stack, the wait
+ * PARKS THAT CONTEXT instead of suspending the stack in place. Returns 0 when
+ * no context owns the stack, and then the Asyncify yield below is still right.
+ *
+ * This is what makes TOOL_MANAGER::RunSynchronousAction's spin loop safe under
+ * Phase D: an in-place park inside a tool body leaves a capture in flight for a
+ * star transfer to land on (doRewind -> "index out of bounds").
+ */
+extern int pcbjam_context_sleep_ms( double ms );
+
 int nanosleep( const struct timespec* req, struct timespec* rem )
 {
     if( req )
     {
         double ms = (double) req->tv_sec * 1000.0 + (double) req->tv_nsec / 1.0e6;
         if( emscripten_is_main_runtime_thread() )
-            __wasm_main_thread_yield_ms( ms ); /* yield -> event loop runs -> Worker boots */
+        {
+            if( !pcbjam_context_sleep_ms( ms ) )
+                __wasm_main_thread_yield_ms( ms ); /* yield -> event loop runs -> Worker boots */
+        }
         else
             emscripten_thread_sleep( ms );     /* worker: real blocking sleep */
     }