Reveal Decks

Repozytoria prezentacji łatwo zamieniają się w zbiór niepowiązanych plików HTML z powieloną konfiguracją i bez użytecznego przeglądu. Zbudowałem Reveal Decks jako jeden lokalny workspace pod kontrolą wersji, w którym każda prezentacja ma własne slajdy, motyw i zasoby, ale pozostaje łatwa do odnalezienia, uruchomienia i eksportowania ze wspólnej biblioteki.

Zaprojektowałem i zbudowałem produkt od początku do końca: konwencję tworzenia prezentacji, typowany kontrakt, wykrywanie przez Vite, przeszukiwalną bibliotekę, generator, walidację, mechanizm druku, dokumentację, testy i proces wydania.

Aplikacja miała pozostać statyczna i lokalna, bez bazy danych oraz backendu. Style prezentacji musiały być odizolowane, lokalne zasoby odporne na fingerprinting produkcyjnego buildu, a routing zgodny z podścieżką repozytorium w GitHub Pages. Autorzy mieli też zachować bezpośredni dostęp do HTML reveal.js zamiast uczyć się własnego formatu slajdów.

Eksport PDF wprowadził inne ograniczenie przeglądarki. Duże diagramy z Eraser były hybrydowymi plikami SVG zawierającymi gęstą grafikę wektorową i osadzone dane rastrowe. Podczas prezentacji działały płynnie, ale przekazanie wielu ich kopii bezpośrednio do mechanizmu PDF w Chromium powodowało powolne i niestabilne dokumenty. Kilka slajdów wykorzystywało też ten sam diagram źródłowy z innym powiększeniem i kadrowaniem w CSS, więc zastąpienie go jedną uniwersalną bitmapą zmieniłoby narrację.

Vite wykrywa definicje prezentacji przez `import.meta.glob`, a typowany kontrakt i walidacja w czasie działania zamieniają je w spójny katalog. Każda prezentacja znajduje się we własnym folderze, a zabezpieczona komenda `pnpm create:deck` generuje metadane, slajdy, motyw i okładkę na podstawie sluga w formacie kebab-case. Biblioteka oferuje wyszukiwanie i filtrowanie po tagach, a sterowanie prezentacją obsługuje klawiaturę, dotyk, pełny ekran i preferencję ograniczenia animacji. Cięższe moduły reveal.js, notatek i podświetlania składni są ładowane dopiero po otwarciu prezentacji.

Trasa drukowania czeka na motyw, obrazy, fonty i zdarzenie `pdf-ready` z reveal.js, zanim przeanalizuje prezentację. Zasoby SVG o rozmiarze co najmniej 200 KB są rasteryzowane osobno dla każdego wystąpienia na slajdzie. Mechanizm przechwytuje końcowy prostokąt obrazu względem kontenera kadrującego, dzięki czemu zachowuje dokładne powiększenie i wycinek zdefiniowany w CSS, a tylko w DOM-ie przeznaczonym do druku podmienia SVG na PNG w skali 2×. Prezentacja na żywo nadal korzysta więc z responsywnych zasobów wektorowych i zachowuje płynną nawigację. Atrybuty danych pozwalają wymusić lub pominąć rasteryzację oraz wskazać własny obszar kadrowania.

Powstała dopracowana biblioteka z dwiema przykładowymi prezentacjami, generowaniem nowej prezentacji jedną komendą, walidacją metadanych i 16 testami automatycznymi, uzupełnionymi o lint, kontrolę typów i build produkcyjny. Leniwe ładowanie utrzymuje początkowy bundle biblioteki na poziomie około 36 KB nawet po dodaniu mechanizmu druku. W rzeczywistej, 30-stronicowej prezentacji etap przygotowania przekonwertował wszystkie 14 widoków dużych diagramów, zachował ich indywidualne kadry, wygenerował oczekiwaną liczbę stron i zakończył się bez ostrzeżeń przeglądarki. Repozytorium jest publiczne na licencji MIT i zawiera dokumentację ułatwiającą samodzielne użycie.

Niewielka konwencja staje się trwała, gdy wspierają ją generator i walidacja, a nie tylko dokumentacja. Projekt potwierdził też wartość odkładania wyspecjalizowanych zależności do momentu, gdy są potrzebne, oraz testowania ścieżek hostingu statycznego jako pełnoprawnej części produkcji.

Wydruk jest osobnym celem renderowania, a nie biernym zrzutem interfejsu prezentacji. Zaczekanie na deterministyczny stan układu i przechwycenie każdego widocznego kadru okazało się pewniejsze niż optymalizacja samych plików źródłowych — szczególnie gdy jeden diagram przekazuje kilka etapów narracji za pomocą różnych przybliżeń.