pcbjam/features/yjs-bridge/0003-eeschema-bridge.md

eeschema (schematic editor) — bridge specifics

Differences from 0001-general-bridge-design.md. eeschema implements the same unified bridge contract (general §1); its ChangeSource/apply adapter is a thin re-use of native machinery, so most of pl_editor's hard work (0002) disappears here. Two genuinely new things: multi-sheet hierarchy and symbol instances.

Adapter — native (no derived differ, no format change) — and why

eeschema has the full machinery natively:

• Identity free: SCH_ITEM ⊂ EDA_ITEM → const KIID m_Uuid (include/eda_item.h:516), serialized as (uuid …) on every item by SCH_IO_KICAD_SEXPR (eeschema/sch_io/kicad_sexpr/sch_io_kicad_sexpr.cpp:745,1047,1189,1322,…; parsed in …_parser.cpp:2777,3476,…). No format change (contrast 0002).
• Granular change set: SCH_COMMIT (eeschema/sch_commit.h), Push() loop (eeschema/sch_commit.cpp:228–397) tags each entry CHT_ADD / CHT_REMOVE / CHT_MODIFY.
• Native observer — hook without patching core: SCHEMATIC_LISTENER (eeschema/schematic.h:60–71):

  virtual void OnSchItemsAdded   ( SCHEMATIC&, std::vector<SCH_ITEM*>& );
  virtual void OnSchItemsRemoved ( SCHEMATIC&, std::vector<SCH_ITEM*>& );
  virtual void OnSchItemsChanged ( SCHEMATIC&, std::vector<SCH_ITEM*>& );
  virtual void OnSchSheetChanged ( SCHEMATIC& );
  

  Register via schematic->AddListener(bridge) (schematic.h:359). SCH_COMMIT::Push fires these in bulk (sch_commit.cpp:399–417). → emit is a listener subclass; near-zero fork divergence.

So: no derived differ and no format patch here. The ChangeSource is the listener; apply goes through SCH_COMMIT.

Model — multi-sheet (the main structural difference)

• SCHEMATIC (eeschema/schematic.h:87) → virtual m_rootSheet, m_topLevelSheets, current m_currentSheet. Each SCH_SHEET owns one SCH_SCREEN whose items live in an EE_RTREE (eeschema/sch_screen.h:98–117).
• Yjs shape: because m_Uuid is globally unique, a flat uuid-keyed Y.Array still works, but each item's Y.Map must carry a screen/sheetPath field so apply knows which SCH_SCREEN to target. (Alternative: a Y.Map of screens, each a Y.Array of items — more structure, mirrors the model; decide during the eeschema commit. Flat+scope-field is simpler to start.)
• OnSchSheetChanged / hierarchy refresh must propagate as its own doc field/event.

Symbol instances (the other new wrinkle)

A SCH_SYMBOL placed in a shared sheet appears on multiple sheet instances; per-instance data (reference, unit) lives in m_instanceReferences (SCH_SYMBOL_INSTANCE). Editing the shared symbol affects all instances; a remote change to reference/unit must update the right instance record, not just the symbol. Treat instance data as nested fields keyed by sheet-path within the symbol's item.

ChangeSource (emit)

SCHEMATIC_LISTENER subclass → on OnSchItemsAdded/Removed/Changed, emit per-item JSON. Converter strategy: reflection-first (general §3 mechanism 1) — SCH_ITEM : EDA_ITEM, so use PROPERTY_MANAGER to serialize registered fields write-once; hand-map (mechanism 3) the gaps where properties aren't registered. (Blobs are not an option here — see serialization note.) Include the screen/sheetPath scope on every item.

apply — go through SCH_COMMIT

SCH_COMMIT commit( toolMgr );
// add:    create SCH_ITEM, commit.Add(item, screen)
// modify: item = schematic->ResolveItem(uuid); commit.Modify(item, screen); …edit fields…
// remove: commit.Remove(item, screen)
commit.Push( "collab" );   // triggers the recompute below

Push (sch_commit.cpp) runs the required side-effects:

• Connectivity/ERC/netlist: frame->RecalculateConnections(...) when any connectable item changed (HasConnectivityChanges); local vs global cleanup chosen automatically.
• Hierarchy: schematic->RefreshHierarchy() + nav update when a SCH_SHEET changed.

Apply gotchas (enumerated)

• Connectivity is bidirectional — adding/removing a wire re-nets connected pins; never skip RecalculateConnections.
• Symbol instances — update the per-sheet instance record, not only the shared symbol.
• Groups — keep parent/child links in sync (group->AddItem/RemoveItem).
• SCH_FIELD remove is special — it hides, not deletes (sch_commit.cpp:308).
• ERC markers are uuid-tied; deletes orphan them (respect exclusions).
• Selection is transient UI state — never propagate.

Serialization note (differs from pcbnew)

eeschema's I/O plugin is document-level, not per-item — there is no clean public Format(single SCH_ITEM), so the opaque-S-expr-blob path (general §3 mechanism 2) is not available here. This is exactly why the converter is reflection-first + hand-mapped gaps: fields via PROPERTY_MANAGER (or accessors), and on apply build complex items via Clone() + field setters rather than re-parsing a blob.

Scale

~500–5000 items typical (10k+ for large hierarchical designs). Granular deltas (listener) are strongly preferred; whole-document serialization is expensive (hierarchy + uuid resolve + connectivity). A pl_editor-style derived differ would be wrong at this scale — use the listener.