pcbjam/features/yjs-bridge/0006-eeschema-apply-findings.md

eeschema collab apply — bugfix session findings (2026-06-04)

Investigation + fixes for the four reported eeschema collab apply bugs, plus the SCH_SHAPE / SCH_SYMBOL converters. Ground truth was gathered with a headless probe spec and with the real web app driven in two tabs (?collab=1, demo.kicad_sch, 75 items incl. 26 SCH_SYMBOL) — the only place real GAL painting happens.

Key correction: apply works headless

The e2e harness's kicadOpenFile returns false, but the schematic + screens ARE built, so SCH_COMMIT::Push does take effect headless (move/delete/add all mutate the model). The earlier belief that "Push no-ops headless" predated the dyncall-shim fix. What headless cannot do is paint (the GL window is incomplete → the window.cpp(731) GetScreenPositionOfClientOrigin: no window assert). So apply logic is testable headless; rendering must be checked in the real app. The skipped apply test is now un-skipped and extended (move via the sx/sy/ex/ey line form, delete, text add, shape add).

Bug-by-bug

1. "Adding text freezes" — does NOT reproduce through the collab bridge. Verified in the real app: a text added locally in tab A (via the onDelta emit sink, the exact path the native SCHEMATIC_LISTENER uses) propagates over BroadcastChannel and tab B applies it and stays responsive. Single-tab kicadCollabApply of a constructed SCH_TEXT also stays responsive. Conclusion: the user's freeze is the interactive text placement (createNewText → DIALOG_TEXT_PROPERTIES::ShowQuasiModal, a modal nested event loop — a known Asyncify-wasm hang), not the collab apply/emit path. Defensive change anyway: makeItem now parents the text to the schematic and applies the default text size, mirroring createNewText.

2. "Delete doesn't apply" — does NOT reproduce. C++ apply-delete works headless (kicadCollabGetPos → "" after a removed delta) AND end-to-end in two tabs (tab B drops the item, count decrements). Likely already fixed by the converters + the CallAfter deferral now in place.

3. Circles / SCH_SHAPE don't sync — REAL gap. Emit side added (itemToJson hand-maps SHAPE_T + start/end, arc center, bezier control points, stroke width, fill). But added reconstruction is DEFERRED — same wasm trap class as SCH_SYMBOL (below). Bisected with EM_ASM markers: makeItem + commit.Add succeed; the trap is inside SCH_COMMIT::Push's CHT_ADD path — the GAL view->Add of a new SCH_SHAPE — "memory access out of bounds". The identical view->Add succeeds when the shape is loaded from file and when an existing shape is moved (CHT_MODIFY, verified), so it's the asyncify invoke_viii mis-dispatch of a SCH_SHAPE add-path virtual, only from the programmatic CallAfter/apply context. The dyncall shim catches only the "signature mismatch" variant; this trap fires inside the wrong function → not safely retryable. (SetParent/fill-value/layer-warmup were all ruled out by experiment.)

4. Wire moves only partially converge — basic two-tab move does converge (verified: tab A kicadCollabTestMoveFirst → tab B matches, count stable, no dup). The connected-wire re-split divergence was not deeply reproduced; it remains a known connectivity-CRDT limitation (both peers run RecalculateConnections on apply). Also found: for a SCH_LINE, the changed path's bare item->Move() is a no-op (line endpoints only move when flagged) — but the emit side always sends sx/sy/ex/ey, so real wire moves take the working SetStart/EndPoint branch.

SCH_SYMBOL — deferred (wasm parser trap)

The robust approach is the s-expr clipboard blob (0001 §3 mechanism #2): serialize a single item with SCH_IO_KICAD_SEXPR::Format(SCH_SELECTION*, …, /*clipboard*/ true) and reconstruct with LoadContent. Emit works (itemToSexpr produced a valid (symbol(lib_id …)) blob). Reconstruction traps: LoadContent → the s-expr parser hits RuntimeError: table index is out of bounds via invoke_iii (the exception trampoline) when called from the apply/CallAfter context — even though the same parser works during file load. This is the same Asyncify + indirect-call family as the original SCH_ITEM::Move trap; the dyncall shim only catches "signature mismatch", not "table index out of bounds", and a C++ catch(...) cannot catch a wasm trap (it escapes and leaves s_applyingRemote stuck true). So the blob path was removed. Symbol position/move already syncs via the generic changed path; only live symbol-add is unsupported. Next step for symbols: either (a) extend the dyncall/invoke shim to fall back to getWasmTableEntry on "table index out of bounds" too, or (b) route the parse through a tool coroutine, then re-enable the blob converter for SCH_SYMBOL (+ bus entries, tables, sheets).

Shared blocker — the asyncify invoke_* mis-dispatch from the apply context

Three deferred items (SCH_SHAPE add, SCH_SYMBOL add, and historically SCH_ITEM::Move) all hit the same root cause: a virtual call dispatched through an asyncify-instrumented invoke_* / dynCall_* trampoline mis-dispatches when invoked from the programmatic CallAfter/apply context (it works from the file-load / main-loop-boot context). The dyncall shim (scripts/common/shims/dyncall-binding.js.tmpl) fixed the Move case because that one trapped with "indirect call signature mismatch" at the call boundary (safe to fall back to getWasmTableEntry). The shape (invoke_viii → "memory access out of bounds") and symbol (invoke_iii → "table index is out of bounds") cases trap inside the mis-dispatched function, so a blind retry is unsafe. Next step for both: either extend the shim to catch these at the boundary, or route apply through the TOOL_MANAGER so it runs inside a tool coroutine (the asyncify root real edits use) — then re-enable the SCH_SHAPE hand converter and the SCH_SYMBOL s-expr-blob converter.

Files touched

• wasm/bindings/eeschema_embind.cpp — SCH_SHAPE emit fields (itemToJson), defensive SCH_TEXT construction (SetParent + default size). SCH_SHAPE/SCH_SYMBOL added reconstruction documented + deferred. (No kicad-fork change.)
• tests/kicad/eeschema-collab.spec.ts — un-skipped + extended the single-page apply test (move / delete / text-add).