## 🎯 Cel
Dodanie pełnego wsparcia dla Chrome Manifest V3 przy zachowaniu kompatybilności z Firefox. Główne wyzwanie: Chrome MV3 używa service workerów zamiast persistent background pages, co wymaga nowej architektury zarządzania pamięcią.
---
## 🏗️ Architektura
### Nowa warstwa abstrakcji: lib/browser-api/
**lib/browser-api/index.ts**
- Główny punkt wejścia do zunifikowanego API
- Wybiera właściwą implementację na podstawie zmiennej TARGET (build-time)
- Eksportuje jeden interfejs dla całej aplikacji
**lib/browser-api/types.ts**
- Wspólne definicje typów dla obu przeglądarek
- Interfejs BrowserAPI definiujący wszystkie potrzebne metody
- Typy dla tabs, badge, webRequest, cookies, extension, windows
**lib/browser-api/firefox.ts**
- Adapter dla Firefox browser.* API
- Lazy access do globalnego obiektu browser (bezpieczne dla środowisk bez Firefox API)
- Wszystkie metody zwracają Promise lub są no-op jeśli API niedostępne
**lib/browser-api/chrome.ts**
- Adapter dla Chrome chrome.* API
- Mapowanie chrome.action → badge (różnica nazewnictwa)
- Ochrona przed błędami gdy karta zostaje zamknięta (try-catch w operacjach badge)
---
## 🔧 Build System
### esbuild.config.js
- **Dodano**: Rozpoznawanie zmiennej środowiskowej TARGET (firefox/chrome)
- **Dodano**: Różne katalogi wyjściowe (dist-firefox, dist-chrome)
- **Dodano**: Kopiowanie odpowiedniego manifestu na podstawie TARGET
- **Dodano**: Plugin do konwersji ikon SVG → PNG dla Chrome (wymaga PNG w MV3)
- **Zmieniono**: define zawiera teraz process.env.TARGET dostępny w runtime
### package.json
- **Dodano**: Skrypty build:firefox, build:chrome, watch:firefox, watch:chrome
- **Dodano**: Skrypty build-addon:firefox, build-addon:chrome do tworzenia paczek
- **Dodano**: Skrypt convert-icons do generowania PNG z SVG
- **Dodano**: Zależność sharp do konwersji obrazów
### scripts/convert-icons.js (NOWY PLIK)
- Konwertuje assets/icon-addon.svg → PNG w rozmiarach 16, 32, 48, 128px
- Wymagane dla Chrome (MV3 nie akceptuje SVG w manifestach)
### manifest-chrome.json (NOWY PLIK)
- Manifest V3 dla Chrome
- background.service_worker zamiast background.scripts
- action zamiast browser_action
- Ikony PNG zamiast SVG
- host_permissions zamiast embedowanych w permissions
---
## 🧠 Pamięć i Stan (NAJWIĘKSZA ZMIANA)
### memory.ts - Kompletna refaktoryzacja
**Problem Chrome MV3:**
- Service worker może być wyładowany w dowolnym momencie
- Brak dostępu do window.memory z popup/sidebar
- chrome.extension.getBackgroundPage() zwraca null w MV3
**Rozwiązanie:**
1. **Service Worker**: Trzyma pełne dane, synchronizuje do chrome.storage.session
2. **Popup/Sidebar**: Tworzy własną instancję Memory czytając z storage
3. **Throttled sync**: Maksymalnie co 500ms zapisy do storage (wydajność)
**Nowa klasa: CachedRequestCluster**
- Dziedziczy po RequestCluster ale NIE ma rzeczywistych requestów
- Przechowuje tylko metadane: hasCookies, exposesOrigin, hasMarks
- Implementuje wszystkie wymagane metody zwracając cached state
- Używana TYLKO w popup/report window w Chrome
**Zmiany w Memory klasie:**
- **Dodano**: isReady flag i readyPromise dla async inicjalizacji (Chrome)
- **Dodano**: waitUntilReady() - popup musi poczekać na załadowanie danych
- **Dodano**: tabUrls: Map<number, string> - tracking pełnych URL dla Chrome (service worker nie dostaje documentUrl)
- **Dodano**: scheduleSyncToStorage() - throttled sync do storage
- **Dodano**: syncToStorage() - serializacja clustrów do JSON
- **Dodano**: loadFromStorage() - deserializacja przy starcie popup
- **Zmieniono**: register() śledzi main_frame URL i synuje po każdej zmianie
- **Zmieniono**: Badge operacje w try-catch (karta może być zamknięta)
**Funkcja getMemory():**
- **Firefox**: browserAPI.extension.getBackgroundPage().memory (tradycyjnie)
- **Chrome Service Worker**: self.memory (jesteśmy W service workerze)
- **Chrome Popup**: Tworzy NOWĄ instancję czytając z storage (cachowana jako popupMemoryInstance)
---
## 🔒 Bezpieczeństwo i Obsługa Błędów
### util.ts - getshorthost()
- **Dodano**: Walidacja wejścia (null, undefined, pusty string)
- **Dodano**: Czyszczenie URL (protokół, ścieżka, port)
- **Dodano**: Obsługa edge cases (localhost, single word domains)
- **Dodano**: Bezpieczne fallbacki zamiast crashowania
- **Dodano**: Console.warn zamiast milczących błędów
### extended-request.ts
- **MASYWNE POPRAWKI** parsowania URL w konstruktorze
- **Dodano**: isValidHttpUrl() helper - sprawdza czy URL zaczyna się od http(s)
- **Dodano**: safeParseUrl() helper - try-catch wokół new URL()
- **Dodano**: Próba parsowania wielu URL w kolejności priorytetów
- **Dodano**: Obsługa Chrome MV3 initiator property
- **Dodano**: Bezpieczne defaulty gdy parsowanie się nie uda (unknown://unknown)
- **Zmieniono**: isThirdParty() pomija requesty z unparseable URLs
- **Dodano**: uint8ArrayToString() - chunked konwersja dużych arrayów (zapobiega stack overflow)
- **Zmieniono**: Request body processing używa chunked konwersji
---
## 🎨 UI Components
### toolbar.tsx (popup)
- **Dodano**: getCurrentTab() z retry mechanism (Chrome czasem nie zwraca karty od razu)
- **Dodano**: Sprawdzanie memoryReady przed renderowaniem danych
- **Dodano**: Wywołanie waitUntilReady() w useEffect
- **Dodano**: Opóźnienie 200ms dla Chrome przy inicjalizacji (service worker + storage delay)
- **Dodano**: Graceful handling gdy popup otwarty bez active tab
### sidebar.tsx
- **Dodano**: Stan memoryReady i loading screen dla Chrome
- **Dodano**: Wywołanie waitUntilReady() przed dostępem do danych
- **Dodano**: Conditional rendering - pokazuje Ładowanie... gdy pamięć nie gotowa
### report-window.tsx
- **Dodano**: Stan memoryReady i loading message
- **Dodano**: Wywołanie waitUntilReady() przed generowaniem raportu
- **Dodano**: Fallback konstruowania URL z origin gdy brak visited_url
- **Zmieniono**: Filtr clustrów używa hasMarks() zamiast getMarkedRequests().length
### stolen-data-cluster.tsx
- **Bez znaczących zmian** - działa z abstrakcją RequestCluster
---
## 🐛 Poprawki Bugów
### background.ts
- **Dodano**: Diagnostic logging do debugowania inicjalizacji
- **Dodano**: Try-catch wokół init() z error logging
- **Dodano**: Różne logi dla Firefox vs Chrome
### memory.ts - badge operations
- **Dodano**: Try-catch wokół wszystkich operacji badge
- Zapobiega crashowaniu gdy użytkownik zamknie kartę podczas operacji
### chrome.ts - badge adapter
- **Dodano**: Try-catch w setBadgeText, setTitle, setBadgeBackgroundColor
- Chrome rzuca błędy gdy operujemy na zamkniętych kartach
---
## 📝 Workflow Użytkownika (Chrome)
1. **Użytkownik odwiedza stronę** → Service worker rejestruje requesty → Auto-mark podejrzanych → Sync do storage
2. **Użytkownik otwiera popup** → Tworzy Memory → Czyta ze storage → Pokazuje dane z flagami
3. **Użytkownik (od)zaznacza domeny** → Zmienia flagi → Sync do storage
4. **Użytkownik generuje raport** → Otwiera report-window → Czyta ze storage → Filtruje według hasMarks()
---
## ✅ Rezultat
- ✅ **Firefox**: Działa jak wcześniej (background page + window.memory)
- ✅ **Chrome**: Pełne wsparcie MV3 (service worker + storage.session)
- ✅ **Wspólny kod**: 95% kodu jest shared, tylko warstwa dostępu do API różni się
- ✅ **Bezpieczeństwo**: Obsługa wszystkich edge cases w parsowaniu URL
- ✅ **Wydajność**: Throttled sync do storage (max co 500ms)
- ✅ **UX**: Loading states w popup/sidebar dla Chrome
- ✅ **Build**: npm run build-addon:firefox lub npm build-addon dla firefox / npm run build:chrome dla chrome
Wprowadza infrastrukturę umożliwiającą budowanie rozszerzenia dla Chrome i Firefox z jednej bazy kodu. Mapuje różnice w API między przeglądarkami na ujednolicone interfejsy.
ZMIANY:
* lib/browser-api/types.ts - typy oparte na analizie rzeczywistego użycia API w kodzie
* lib/browser-api/firefox.ts - adapter mapujący browser.* na BrowserAPI
* lib/browser-api/chrome.ts - adapter mapujący chrome.* na BrowserAPI
* lib/browser-api/index.ts - build-time selection adaptera na podstawie TARGET
KLUCZOWE RÓŻNICE OBSŁUŻONE:
- Firefox: browser.browserAction.* vs Chrome: chrome.action.*
- Firefox: browser.tabs.* vs Chrome: chrome.tabs.*
- Firefox: browser.cookies.* vs Chrome: chrome.cookies.*
- Firefox: browser.webRequest.* vs Chrome: chrome.webRequest.*
TYPY OPARTE NA FAKTYCZNYM UŻYCIU:
Przeanalizowano 4 pliki używające browser API:
- memory.ts: badge, webRequest, cookies, extension API
- toolbar.tsx: tabs.query, tabs.onUpdated, windows.WINDOW_ID_CURRENT
- tab-dropdown.tsx: tabs.query
- util.ts: tabs.query
STATUS: Preparatory change - istniejący kod pozostaje niezmieniony.
Kolejne commity będą refaktorować pliki do używania nowej abstrakcji.
TARGET: Umożliwienie
> rentgen@0.1.10 build:firefox
> TARGET=firefox node esbuild.config.js
Add-on was built i
> rentgen@0.1.10 build:chrome
> TARGET=chrome node esbuild.config.js
Add-on was built
Wygenerowanie wersji PNG (16px, 20px i 24px) wszystkich ikon SVG przy użyciu komendy Inkscape z wiersza poleceń
Główna ikona wtyczki (dla manifest.json) Chrome oczekuje konkretnych rozmiarów, stadndardowych dla Chrome (16, 32, 48, 128), ale ikony interfejsu (używane wewnątrz stron rozszerzenia) Chrome mogą mieć dowolny rozmiar, ponieważ to zwykłe obrazy w HTML. Ustawiłem je zgodnie z naszymi obecnymi rozmiarami (16, 20, 24px)
użyta komenda for svg in assets/icons/*.svg; do basename=$(basename "$svg" .svg); for size in 16 20 24; do inkscape --export-type=png --export-width=$size --export-height=$size --export-background-opacity=0 "$svg" --export-filename="assets/icons/${basename}-${size}.png"; done; done
