pcbjam/features/yjs-bridge/0002-pl-editor-bridge.md

pl_editor (drawing-sheet editor) — bridge specifics

Differences from 0001-general-bridge-design.md. pl_editor implements the same unified bridge contract as the other two (per-item ChangeSource + per-item apply); it is the first PoC. It has none of the native machinery, so its ChangeSource is the one adapter we write from scratch — an in-bridge snapshot-differ — while its edit/undo core stays untouched (low upstream divergence; Route 1, decided 2026-06-03).

What pl_editor lacks natively (why its adapter is custom)

• DS_DATA_ITEM does not derive from EDA_ITEM (include/drawing_sheet/ds_data_item.h:95) → no KIID, and the COMMIT base operates on EDA_ITEM* so it can't take data items.
• No COMMIT anywhere in pagelayout_editor/ (0 uses); undo is a whole-model S-expr snapshot (SaveCopyInUndoList → DS_PROXY_UNDO_ITEM) wired at 13 sites across 8 files.
• No listener/observer of any kind.
• Single change chokepoint: PL_EDITOR_FRAME::OnModify() (pl_editor_frame.cpp:379).

We do not rewrite that core. Instead the adapter derives per-item events by diffing, and applies per-item by uuid — producing the exact same observable behavior as SCH_COMMIT/ BOARD_COMMIT, encapsulated entirely in the bridge.

Model

• Singleton DS_DATA_MODEL::GetTheInstance(); std::vector<DS_DATA_ITEM*> m_list (include/drawing_sheet/ds_data_model.h). Flat, single-document — no sheets/screens, no connectivity/ERC (a big simplification vs eeschema/pcbnew).
• Item types: DS_TEXT, DS_SEGMENT, DS_RECT, DS_POLYPOLYGON, DS_BITMAP.
• DS_DRAW_ITEM_* render proxies are rebuilt by DS_DATA_ITEM::SyncDrawItems(view); ephemeral.

Identity — add the SAME KIID/(uuid …) as eeschema/pcbnew

Use the identical type + token + writer (general §2), not a bespoke id:

• Add KIID m_Uuid; to DS_DATA_ITEM (include/kiid.h). Default-constructed → random, so a new or uuid-less item is auto-backfilled in memory for free.
• Serialize with the shared helper KICAD_FORMAT::FormatUuid( m_out, item->m_Uuid ) (include/io/kicad/kicad_io_utils.h:55) in ds_data_model_io.cpp, exactly as sch/pcb do.

Save + load + backfill

• Format: add uuid to common/drawing_sheet/drawing_sheet.keywords (absent today). The wks lexer is strict (unknown token → default: → Expecting()/throws), so the token must be declared + handled — no silent passthrough.
• Load: case T_uuid: item->m_Uuid = KIID( FromUTF8() ); NeedRIGHT(); break; in each item parser (drawing_sheet_parser.cpp). If the token is absent, the parser leaves the default random m_Uuid in place → automatic backfill.
• Save: always write (uuid …) per item → the first save of a legacy/upstream uuid-less .kicad_wks upgrades the file in place.
• Cross-client consistency: files with uuids (our output, and any file after one save) → all clients agree. A never-saved uuid-less legacy file gets random backfill (KIID(invalid) → random, confirmed in common/kiid.cpp — not a deterministic hash), so two cold opens disagree; handled by the seed-once rule (general §2). Optional deterministic content-seed backfill (boost name_generator over type+name+pos+index) is deferred hardening.
• Tradeoff: files now carry (uuid …); stock desktop KiCad's strict parser rejects the unknown token → fork-only files. Backfill makes the upgrade graceful.

ChangeSource adapter — in-bridge snapshot-differ (emits per-item deltas)

The bridge holds the last emitted snapshot (a uuid → fields map). On OnModify():

1. Serialize current m_list to a uuid → fields map — all 5 types, none invisible (rationale below): text/segment/rect as scalars; poly/bitmap as an opaque S-expr blob.
2. Diff vs the cached map by uuid: present-only-in-new → added; only-in-old → removed; in-both-with-changed-fields → changed.
3. Emit the per-item delta JSON via EM_ASM window.kicadCollab.onDelta(json); update the cache.

This yields the same added/removed/changed per-item events the native listeners produce. The diff is O(items) — negligible for drawing sheets. (We could instead call the differ directly from OnModify; optionally wrap it as a one-method DS_DATA_MODEL listener purely for registration symmetry with sch/pcb — nice-to-have, not required.)

apply(delta) — per-item mutation by uuid

For each op in the incoming delta (inside the s_applyingRemote guard, general §5):

• changed: find DS_DATA_ITEM by m_Uuid in m_list; set the changed fields.
• added: create the item (with the given uuid), DS_DATA_MODEL::Append.
• removed: find by uuid, Remove + delete. Then SyncDrawItems on touched items + canvas refresh, and re-select by uuid so a remote apply doesn't drop local selection (a bonus the uuid unlocks). Optionally SaveCopyInUndoList() once after a remote batch so local undo has a coherent checkpoint. No connectivity/ERC — none exists for drawing sheets.

Text-insert path (working UI flow targeted first)

PL_DRAWING_TOOLS::PlaceItem (tools/pl_drawing_tools.cpp:72) → AddDrawingSheetItem(DS_TEXT) (pl_editor_frame.cpp:823) → new DS_DATA_ITEM_TEXT("Text") (fresh KIID) → Append → SyncDrawItems → SaveCopyInUndoList() → OnModify() ← differ runs here → emits an added.

Field mapping — all 5 types in one pass, at two fidelities

Cover every type so none is invisible to collaboration (see rationale). pl_editor has no reflection (DS_* is not EDA_ITEM), so scalars are hand-mapped (general §3 mechanism 3) and the awkward two reuse the existing per-item serializer (mechanism 2):

Shared: id(m_Uuid) · type · name(m_Name) · x,y(m_Pos.m_Pos, mm) · anchor(m_Pos.m_Anchor)

• text (scalars): text(m_TextBase) · orient(°) · hjustify/vjustify · italic · bold · sizeX,sizeY(m_TextSize, mm) — field-level merge.
• segment/rect (scalars): ex,ey(m_End.m_Pos) · eanchor · linewidth(m_LineWidth).
• poly/bitmap (opaque blob): sexpr field from DS_DATA_MODEL_IO::Format(model, item) / SaveInString({item}, &str) — no nested corner-list / base64 field mapper to write; item-level merge. Refine to scalars later only if field-level merge is ever wanted.

Why all 5, not just text/line/rect: the adapter is a whole-model differ, so a type absent from the snapshot is invisible — a user adding a polygon or logo bitmap simply wouldn't sync. Including poly/bitmap as blobs closes that correctness gap at near-zero cost (the serializer already exists). Bitmap is safe despite its large base64 payload: the differ emits a field only when its value changes (string compare), so a static image is cached once and never re-emitted — just keep it out of any per-keystroke re-encode path.

On apply, a blob item is reconstructed by parsing its sexpr back into a DS_DATA_ITEM (wrap as a minimal model string → reuse SetPageLayout/the parser; a tiny parse-one helper).

Build steps (maps to phasing commits 1–2 in general §8)

Commit 1 — interface/identity: KIID m_Uuid on DS_DATA_ITEM + (uuid) keyword/parse(backfill)/save via FormatUuid. Build once; verify a .kicad_wks round-trips uuids and a legacy file is backfilled on save. Commit 2 — bridge + converters (all 5 types) + tests: (done 2026-06-03)

Placement update (as built): the bridge does not live in common/drawing_sheet/ds_collab_bridge.{h,cpp} (kicad fork). To honor CLAUDE.md ("fix in the wasm layer / keep the fork close to upstream") the entire differ/apply/emit was implemented in the wasm layer, wasm/bindings/pl_editor_embind.cpp (root repo), using only public DS_DATA_MODEL/DS_DATA_ITEM API. Fork footprint = one file, +15 lines: an extern "C" void kicadCollabOnModify() call wired into PL_EDITOR_FRAME::OnModify(). Same architecture as below; only the file location differs.

1. Bridge (wasm/bindings/pl_editor_embind.cpp): the snapshot-differ ChangeSource (cache + diff, emit on OnModify via EM_ASM), kicadCollabApply per-item-by-uuid (scalars by field; poly/bitmap via SetPageLayout-append blob), s_applyingRemote guard, plus kicadCollabSnapshot() (seed/baseline) and a kicadCollabTestAddText() PoC local-edit hook.
2. Web: yjs + BroadcastChannel provider; the generic reconciler (general §4) under web/apps/frontend/src/wasm/collab/. CRDT = uuid-keyed Y.Map of per-item Y.Map (refinement of "Y.Array<Y.Map>" — better for id-stable items). WasmTool wiring + Zod guard deferred.
3. Verified by tests/kicad/pl_editor-collab.spec.ts: single-page C++ contract (snapshot / apply changed+removed+added / echo-suppression) + two-tab BroadcastChannel A↔B text propagation through the real reconciler. Selection re-acquire-by-uuid and screenshots deferred.

Risks specific to pl_editor

• Carries the format-change divergence (general §9) — the only tool that does.
• Its ChangeSource is a derived differ (not native tracking). Correct and cheap here, but the differ pattern is pl_editor's alone — eeschema/pcbnew use native events.
• Never-saved legacy-file cold-open identity race — mitigated by seed-once; deterministic backfill deferred.