coschema.

Wszystkie projekty

Publiczne repozytorium

Wspólna edycja diagramów

Edytor diagramów do pracy w kilka osób naraz, z kursorami na żywo, edycją offline, cofaniem tylko własnych zmian i symulatorem sieci, który sprawdza, że każdy klient kończy z tym samym, poprawnym diagramem.

Dwa edytory obok siebie. Ada przechodzi offline, oboje edytują, łącze wraca i kopie się scalają. Potem kursory na żywo i tryb śledzenia.

Demo otwiera stronę /demo. Pokój działa w twojej przeglądarce, więc nic nie trafia na serwer. Nagranie z repozytorium, bez dźwięku.

Po co to zrobiłem.

Diagramy to moja codzienna praca. Pracuję nad oprogramowaniem, które generuje schematy jednokreskowe stacji elektroenergetycznych wysokiego napięcia: Angular i rysowanie diagramów na froncie, Java i Quarkus za nim. W prawdziwych zespołach kilka osób edytuje ten sam diagram w tym samym czasie.

Chciałem zmierzyć się z trudnymi częściami współpracy: utrzymać poprawny graf, gdy dwie osoby zmieniają go naraz, cofać tylko własne edycje i czysto scalać pracę offline. Edytor da się też obsłużyć klawiaturą i ogłasza czytnikom ekranu zmiany innych osób, bo wspólne płótna rzadko to potrafią.

Sprawdź w demo.

Na stronie demo są dwa edytory, Ada i Bruno, każdy za własnym symulowanym łączem z opóźnieniem, jitterem, utratą pakietów i przełącznikiem offline.

Praca offline
Zaznacz „Network offline” u Ady, edytuj po obu stronach i odznacz. Kopie się scalą i skończą identyczne.
Zła sieć
Podnieś suwakami opóźnienie, jitter albo utratę pakietów jednego edytora albo wybierz Slow, Lossy lub Chaotic dla obu. „Make a mess” odcina łącza, edytuje te same węzły po obu stronach i po chwili przywraca łącza, więc konflikt jest prawdziwy.
Cofanie tylko swojego
Przesuń węzeł u Ady, zmień jego etykietę u Bruna i cofnij u Ady. Wraca pozycja, etykieta zostaje.
Kursory i śledzenie
Kliknij odznakę drugiej osoby nad płótnem, żeby śledzić jej widok. Własne przesunięcie widoku kończy śledzenie.
Klawiatura
Kliknij węzeł, a potem: N i P chodzą po węzłach, strzałki je przesuwają, Enter edytuje etykietę, a znak zapytania pokazuje wszystkie skróty.
Eksport
Przyciski SVG i PNG na pasku narzędzi zapisują cały diagram.

coschema.adrianturbinski.pl

Trzy trudne miejsca.

Każda decyzja ma w repozytorium swój ADR, razem z alternatywami, które przegrały.

  • Poprawny graf przy odczycie.

    Jedna osoba łączy krawędź z węzłem, a druga w tym samym czasie ten węzeł usuwa. Wspólny dokument może trzymać taki niepoprawny stan, a widok pochodny, który nigdy nic nie zapisuje, go ukrywa. Żaden klient niczego nie naprawia, więc nie ma burzy poprawek.

    Cena: ukryte krawędzie zostają w dokumencie, dopóki węzeł nie wróci albo ktoś ich nie usunie.

    Przegrały naprawy na każdym kliencie (N klientów usuwa tę samą krawędź, a każda naprawa może walczyć z cofaniem) i naprawy tylko na serwerze (serwer staje się drugim autorem dokumentu, a przywrócony węzeł zastałby swoje krawędzie już usunięte).

    ADR 0007 na GitHubie
  • Cofam tylko swoje.

    Każdy klient ma własny menedżer cofania, który śledzi tylko lokalne zmiany, a przeciągnięcie to jeden krok, niezależnie od liczby ruchów wskaźnika. Pozycja i etykieta to osobne klucze, więc cofnięcie mojego przesunięcia nie cofa późniejszej zmiany etykiety kogoś innego.

    Cena: jeśli ktoś przesunął ten sam węzeł po mnie, moje cofnięcie nic nie robi, bo moja zmiana została już nadpisana. Test przypina to zachowanie.

    Przegrały wspólny stos cofania, który cofa cudzą pracę, i ręcznie pisane operacje odwrotne: więcej kodu i błędy przy współbieżności dokładnie w tych przypadkach, które mają testy.

    ADR 0008 na GitHubie
  • SVG zamiast canvasa.

    5000 węzłów w SVG przy 60 klatkach na sekundę: jedna transformacja świata, indeks siatki, który daje stabilne okno widoczności, trzy poziomy szczegółów i przegląd całej sceny poniżej powiększenia 0,25. Benchmark powstał pierwszy, a pierwszy renderer go nie przeszedł przy powiększeniu pokazującym całą scenę, więc renderer się zmienił.

    Cena: elementów poza oknem nie ma w DOM, więc wyszukiwanie na stronie i tryb przeglądania czytnika ekranu ich nie widzą. Model klawiatury działa na danych, nie na DOM, i przewija do węzła z fokusem.

    Przegrały canvas i WebGL, szybsze w dużej skali, ale SVG jest dostępne z natury, z elementami, które przyjmują fokus i ARIA. Przegrało też samo content-visibility, które pomaga w układzie strony, ale nie zmniejsza liczby widoków Angulara.

    ADR 0014 na GitHubie

Liczby.

Tylko to, co zmierzyły skrypty z repozytorium.

5000
Przebiegów symulatora zbieżności z różnymi ziarnami, 0 nieudanych, w 90,9 s. Symulowana sieć przeniosła 1 756 564 wiadomości, zgubiła 12 715 i zdublowała 6418. Po uzdrowieniu sieci każdy dokument jest porównywany bajt po bajcie.
18 ms
p95 od puszczenia przycisku u piszącego do zmienionych pikseli u czytającego. Dwa konteksty przeglądarki w jednym pokoju, 200 edycji, magazyn w pamięci. Z PostgreSQL 15 ms. Cel: poniżej 200 ms.
60 fps
Przesuwanie sceny z 5000 węzłów: mediana i najgorszy z trzech przebiegów na każdym z ośmiu poziomów powiększenia, od 1 do 0,05.
3987
Operacji na sekundę, które utrzymał jeden proces Node z PostgreSQL, przy p95 dostarczenia 15,77 ms. Przy 8000 oferowanych p95 przekroczyło 200 ms. To liczby dla jednego procesu.
1012
Testów jednostkowych: 661 w pakietach, serwerze i skryptach i 351 w edytorze. Do tego 40 testów integracyjnych z PostgreSQL i 41 testów Playwright. Pokrycie linii: 98,75% w pakietach i serwerze, 96,85% w edytorze.
100
Dostępność w Lighthouse na /, /r/test i /demo, w ustawieniach desktop i mobile, bez żadnego nieudanego audytu.

Zmierzone na laptopie: Intel Core i7-12700H, 20 rdzeni logicznych, 15,5 GiB RAM, Linux pod WSL2, Node 24.21, headless Chromium 153, PostgreSQL 18.6. Przeglądarka działała na localhoście, więc to liczby dla tej maszyny.

Pliki z wynikami w bench/results

Czego nie ma.

Z listy dodatków zbudowałem tylko eksport SVG i PNG. Testy nigdy nie wypadały.

Wersje z przywracaniem
Dokument Yjs nie ma powrotu do stanu dla wszystkich, więc przywrócenie byłoby różnicą zastosowaną jako nowe edycje. To najtrudniejsza część.
Komentarze do węzłów
Druga wspólna struktura, z własnymi regułami poprawności po usunięciu węzła i własnym modelem dostępności.
Serwis autoryzacji w Quarkusie
Serwer synchronizacji sprawdza JWT kluczem deweloperskim. Osobny serwis w Javie to praca na całe repozytorium i nie mówi nic nowego o współpracy.
Uchwyty rozmiaru i punktów krawędzi
Model danych i symulator już je obsługują. Edytor nie ma uchwytów, którymi można by je przesunąć.
Kilka serwerów na pokój
Pokój należy do jednego procesu serwera. Kilka instancji potrzebowałoby kierowania ruchu po pokoju albo warstwy pub/sub.
Firefox, WebKit i czytnik ekranu
Testy end to end i liczby z przeglądarki pochodzą z Chromium. Nikt jeszcze nie słuchał edytora z NVDA ani VoiceOver.

Co dalej.

Najpierw warstwa pub/sub, żeby kilka serwerów dzieliło pokoje, potem wersje, potem brakujące uchwyty edycji, a potem testy z NVDA i VoiceOver. W samym edytorze najpierw dodałbym przeciąganie widoczne na żywo: dziś inni widzą skok węzła dopiero, gdy puścisz przycisk.

ADR 0025: czego nie zbudowałem

Technologie

  • Angular
  • TypeScript
  • Signals
  • Node.js
  • WebSockets
  • Docker
  • GitHub Actions
  • Obsługa klawiaturą
  • Zarządzanie fokusem

Artykuł na blogu, po angielsku: How I test that collaborative edits converge

Porozmawiajmy o roli.

contact@adrianturbinski.pl

Napisz, jaki to zespół, jaki produkt i jaki stack.

Masz projekt do zrobienia? Jest też edycja dla klienta.