Wyślij mailem.
Pojawi się u Babci.

Słownik

Co dokładnie kryje się za pojęciami, których pozwoliliśmy sobie nie używać wyżej.

Allowlista

Lista zaufanych nadawców mailowych. Nieznany adres → poczekalnia (status=pending), zdjęcia widoczne tylko po manualnej akceptacji w panelu.

IMAP IDLE

Push-mode po stronie skrzynki — serwer mailowy sam mówi „nowy mail”, zamiast cyklicznego pollingu. Worker trzyma 3 połączenia jednocześnie (foto@madrzak.pl, fotomadrzak@gmail.com, melafoto@madrzak.pl), kto pierwszy ten lepszy. Każde konto może mieć opcjonalny IMAP_N_DEFAULT_FRAME_SLUG bindujący wszystkie maile do konkretnej ramki (np. melafoto → mela), z kolejnością rozpoznawania: tag #slug w temacie > bind konta > default ramki nadawcy.

Day-window

Para godzin (wake_hour, sleep_hour) per ramka. W oknie ramka chodzi non-stop z filmami. Poza oknem — 5 min po dotyku, potem MainActivity zdejmuje FLAG_KEEP_SCREEN_ON i AlarmManager usypia ekran przez DPM.lockNow().

Capacitor

Framework od Ionica do pakowania webowej aplikacji (nasz React 19 + Vite) w natywną appkę Android/iOS. WebView jako runtime + JS bridge do natywnych API przez pluginy w Kotlinie/Swift. Konkretnie u nas: na ramce frontend wywołuje window.Capacitor.Plugins.ScreenSchedule.setSchedule({sleepHour: 23, wakeHour: 7}), a po stronie Kotlina MainActivity programuje AlarmManager.setAlarmClock(...) — TV gaśnie o 23:00, budzi się o 7:00. Bez Capacitora to samo trzeba by pisać dwa razy (Kotlin + Swift) albo zostać przy zwykłym PWA bez prawdziwego budzika sprzętowego.

X-Accel-Redirect

Nginx-owy mechanizm: Express weryfikuje token PIN i odpowiada nagłówkiem X-Accel-Redirect na internal location, nginx serwuje plik APK z lokalnego dysku jak zwykły static. Range, streaming, zero bufora w Node.

Device token

Per-ramka Bearer token (32 hex). Wkleja się w URL fragment #t=... przy pierwszym otwarciu, potem żyje w localStorage. requireDeviceToken middleware wywołuje trackFrameAccess i UPSERT-uje (frame_id, ip) do frame_seen_ips — pierwsze nowe IP wyzwala mail przez nodemailer + Gmail SMTP.

PIN flow

Sześciocyfrowy kod (TTL 10 min) lub 32-hex link (TTL 24 h) do pobrania APK z /dl/:token. Token bindowany do IP po pierwszym hicie — kolejne requesty z tego samego IP w oknie OK, inne IP → 410. Rozwiązuje wzorzec Sony BRAVIA Downloader, który robi 2 requesty na ten sam URL (WebView preflight + DownloadManager Range).

Dedup po Message-ID + SHA-256

Pierwsza warstwa: Message-ID maila (idempotencja przy retry IMAP). Druga: SHA-256 oryginału pliku — ten sam plik wysłany dwukrotnie z różnych klientów dostaje jeden wpis.

Oryginały vs miniaturki

storage/originals/ — jedyna kopia oryginału (gitignored, do regeneracji). storage/display/ — wersja max 2048 px sRGB JPEG do slideshow. storage/thumbs/ — 320 px do listingu w panelu. Tylko display i thumbs są serwowane przez nginx; oryginały nigdy publicznie.

Weighted shuffle

Display.jsx ekspanduje pulę zdjęć przez wagi (każde id powielane N razy), potem Fisher-Yates, potem de-clustering sąsiadujących duplikatów. Trzy wagi się składają: base = ceil(senders.priority/2) (priority 1-2→1, 3-4→2, 10→5; obniżone od 2026-05-01, bo dla 1026 zdjęć przy bazie=priority pula rosła do ~2400 wpisów i cykl 13 h nie mieścił się w dziennym oknie 7-22:30), boost ulubionych (★ → ×2), freshness decay 7-dniowy z photo.takenAt (boosted = base + freshness×(10-base), max=10 dla świeżego, liniowo do base po 7 dniach). Cap 30 entries per zdjęcie. Reshuffle reaguje na: zmianę zestawu zdjęć, toggle z panelu, zmianę priority/★ (przez photosKey = id:priority:fav), upływ czasu (freshnessTick co godzinę), zawijanie cyklu (shuffleEpoch++). Efekt: świeży mail od mamy z dziś dominuje rotację (waga 10), za tydzień wraca do bazowej 2, archiwum 2014 zawsze rzadko (1).

lastIndexRef + reset po reshuffle

Pułapka weighted shuffle: lista photos ma duplikaty po wagach, więc list.findIndex(id) zawsze zwraca PIERWSZE wystąpienie. Stary setIndex iterował przez findIndex(currentId)+1 — pivot zawsze wracał do najwcześniejszej pozycji, co dawało mikro-pętlę 5 zdjęć z początku listy zamiast pełnego cyklu. Fix: useRef(0) zapamiętujący faktyczną expanded position; setIndex używa go jako pivot dopóki photos[lastIdx].id wciąż się zgadza z prevId, fallback do findIndex tylko gdy ref jest stale. Drugi fix (od 2026-05-01 wieczór): po bumpie shuffleEpoch useEffect wymusza currentId = photos[0].id i lastIndexRef = 0, bo bez tego fallback findIndex(prevId) w nowej kolejce skakał na pierwsze wystąpienie ostatnio widzianego ID (~1/N długości listy), więc drugi cykl startował w środku i pomijał pierwszą partię expanded queue — dla babci 30-50% zdjęć drugiego cyklu nie pojawiało się na ekranie. Sync też przy 'foto:new-photo' żeby kolejne next() startowało z aktualnej pozycji.

Status bar — dwa liczniki

Po tapnięciu pasek pokazuje dwa różne liczniki, oba z tym samym mianownikiem (= liczba unikalnych zdjęć ramki). Górny „135 / 1027” to pozycja PIERWSZEGO wystąpienia aktualnego ID w shuffled queue — skacze niemonotonicznie, bo expanded queue ma duplikaty po wadze i lecąc po slajdzie #340 (drugi pokaz tego samego zdjęcia) cofamy się do np. 135. Dolny „143 / 1027 (14%)” to liczba unikalnych zdjęć obejrzanych od początku bieżącego cyklu — rośnie monotonicznie, powtórki nie liczą. Dolny może być WIĘKSZY od górnego, gdy aktualny slajd to duplikat zdjęcia widzianego wcześniej (jego pierwsze wystąpienie ma niski numer, ale w międzyczasie minęły inne unikalne ID). Oba resetują się przy reshuffle (shuffleEpoch++). viewedInCycleRef = useRef(new Set()) trzyma ID, viewedCount jako useState do triggera rerenderu paska.

Bulk import + parser dat

scripts/bulk-import.js — import zdjęć z katalogu poza emailem (SCP archiwum, panel admin do dyspozycji jako alternatywa). Dedup po SHA-256: zdjęcie istniejące w innej ramce dolinkowane przez photo_frames.added_via='admin_bulk' bez duplikacji pliku. Fallback daty: EXIF DateTimeOriginal (ImageMagick %[EXIF:...]) → parser nazwy pliku (lib-filename-date.js obsługuje 2015.04.06-11.43_*, IMG_YYYYMMDD_HHMMSS, IMG-YYYYMMDD-WAxxxx, Screenshot_YYYYMMDD-HHMMSS). Dla zdjęć bez EXIF i bez parsowalnej nazwy: sentinel taken_at='2014-01-01T00:00:00' rozpoznany w StatusBar.jsx (jan 1, 00:00:00) renderuje 'Rok 2014' zamiast 'Styczeń 2014'.

MediaSession trap

Filmy (mediaType==='video') w slideshow trzymają MediaSession active, co blokuje wygaszanie ekranu nawet po naszym clearFlag(KEEP_SCREEN_ON). Display.jsx odfiltrowuje filmy poza day-window, żeby nocne wygaszenie faktycznie zadziałało.

Rotacja rezydenta

Gdy frames.resident_rotate=1, Resident.jsx ignoruje resident_kind i co 10 min (na granicy :00, :10, :20, :30, :40, :50 UTC) liczy effectiveKind = ['cat','dog','owl','bunny','panda','puppy','kitty','jumbo','crocodile_on_scooter','yacht','bunnies_in_boat'][Math.floor(Date.now() / 600_000) % 11]. setInterval(60_000) trzyma React aktualny, useEffect na zmianie kind reset'uje state i fetchuje nowy plik Lottie — bez restartu aplikacji. Wszystkie ramki z rotate=1 zsynchronizowane po zegarze UTC.

photo_frames M:N

Zdjęcia żyją w tabeli M:N (photo_id, frame_id, status, added_via, added_at) — to samo zdjęcie może być w kilku ramkach z niezależnym statusem (approved u Babci, hidden u Cioci). Worker IMAP robi dual-write w transakcji, a gdy hash już istnieje w innej ramce — auto-link 'imap_dedup' zamiast wyrzucenia jako duplikat. added_via to audit trail (imap / imap_dedup / admin_add / admin_bulk / migration). photos.frame_id zostaje jako legacy mirror do migracji 019.

forceReloadAt

Sygnał zdalnego reloadu frontendu na ramce. Admin klika w panelu → backend pisze do frames.force_reload_at = now(). Heartbeat (5 min) zwraca tę wartość; App.jsx trzyma ref seenForceReloadAt — pierwsza odpowiedź ustanawia baseline, każda kolejna zmiana → window.location.reload(). W trybie Capacitor APK reload pobiera świeże pliki z server.url bez App.exitApp() i bez podchodzenia do TV. Diagnostyka: vite.config.js wstrzykuje __APP_BUILD_HASH__ = sha1(BUILD_AT).slice(0,7), QuickMenu pokazuje (BUILD: 2b94c2c) — wzrokowo widać czy reload zaszedł.

configUpdatedAt

Drugi sygnał obok forceReloadAt — bumpowany przez admin/frames PATCH i device PATCH /:slug/config (force-reload nie bumpuje, czysta separacja). Heartbeat zwraca; App.jsx ma drugi ref seenConfigUpdatedAt → silent fetchFrameConfig + setConfig (bez reloadu). Po setConfig useEffect w Display.jsx wywołuje Capacitor.Plugins.ScreenSchedule.setSchedule(...) i AlarmManager przeprogramowuje alarmy. Czyli zmiana harmonogramu w panelu propaguje się sama w max 5 min, bez fizycznej interakcji z ramką.

banner_*

Trzy kolumny w frames (banner_text, banner_kind, banner_expires_at) — jeden aktywny komunikat per ramka, kind ∈ {info, news, alert} mapowane na kolory (zielony / niebieski / czerwony pulsujący). Backend zwraca banner w GET /api/frame/:slug/photos (piggyback na 30 s polling — dla rodzinnej ramki wystarczy). Frontend Banner.jsx renderuje overlay top z setInterval(1s) do auto-hide po expiresAt — TTL liczony klient-side, bez backendowego cron-cleanup. Endpointy: POST /:id/banner, DELETE /:id/banner, POST /banner-broadcast (UPDATE wszystkich).

ticker_*

Pięć kolumn w frames (ticker_text, ticker_mode, ticker_kind, ticker_speed, ticker_expires_at) — niezależny od banner news ticker na dole ekranu. Mode ∈ {scroll, static}, kind ∈ {neutral, info, news, alert} (default neutral — czarne tło, klasyczny news ticker look), speed ∈ {slow, medium, fast} presety mapowane na SPEED_PX_PER_S = {60, 120, 200} px/s. Tekst do 300 zn., TTL 5–86400 s. CSS animation tv-ticker-scroll (translateX 100vw → -100%), animationDuration liczony inline z (text.length × 16px + 1200px) / SPEED. Display.jsx gating przez interactiveActive — poza day-window ticker nie istnieje. Z-index 70 (StatusBar nad ticker'em, decyzja: user-triggered i krótki). Endpointy bliźniacze do banner: POST /:id/ticker, DELETE /:id/ticker, POST /ticker-broadcast. Migracja 021, piggyback na photos-poll.

Pauza slideshow

In-memory toggle (Display.jsx state, NIE persisted) zatrzymujący advance() — current photo wisi do czasu kolejnego next()/prev()/wyjścia z day-window. Trigger: klawisz P na klawiaturze, media-key || (KeyMediaPlayPause), przycisk w QuickMenu, gesture na touch — Spacja zostaje na OK (bo OK na pilocie TV = Enter = Space na keyboard, kolizja z otwarciem menu). Reset: prev/next, nowy photo w refresh, wyjście z interactiveActive (ramka usypia → wakeup zaczyna od czystego stanu). Brak persistence intencjonalna: pauza to mikro-akcja użytkownika, nie ustawienie.

Pilot Android TV (D-pad)

lib/remote-keys.js: isOkKey() łapie Enter/Select/Space/keyCode 13/32/23, isBackKey() Escape/BrowserBack/keyCode 4/8/27 — różne TV WebViews (Sony BRAVIA, Lenovo, Chromecast, Sharp AQUOS) emitują różne kombinacje pod KEYCODE_DPAD_CENTER / BACK. Mapping w slideshow: ←/→ prev/next, OK/↑ otwiera Szybkie menu, ↓ status bar, Back zamyka. QuickMenu: autofocus + ↑/↓ cykl pozycji. ThumbnailGrid: strzałki po grid (kolumny z getComputedStyle.gridTemplateColumns.split(/\s+/).length), OK otwiera chooser modal (Anuluj / Ukryj-Pokaż / Pokaż na ramce primary) — bo pilot TV emituje OK jako natychmiastowy click (keyup zaraz po keydown), long-press niewykrywalny. Touch (tablet) ma własny pointer-event pipeline z 600 ms timerem, niezmieniony. Debug: localStorage.foto:debug-keys='1' lub ?debug-keys=1. Pułapka focus(): zawsze { preventScroll: true } + ręczne scrollIntoView({ block: 'nearest' }) wewnątrz scrollowalnego rodzica — bez tego BRAVIA/AQUOS wykonują scrollIntoView na D-pad fokusie i przesuwają cały slideshow.

Slideshow watchdog

Dwa antyzawisowe timery w Display.jsx. (1) Slideshow.jsx — w gałęzi isVideo=true setTimeout(advance, max(60s, durationSec × 3)) capped 5 min — bez tego ramka zawisała na wideo, które po cichu nie odpaliło onEnded (autoplay-block, codec stuck, MediaSession). (2) Display.jsx — setInterval(15s) sprawdza Date.now() - lastAdvanceAt > max(90s, slideDur × 5) capped 5 min; jeśli currentId nie zmienił się tak długo, wymuszamy next(). Plus image preload: onerror + 30 s timeout, żeby zawiśnięty fetch (oddzielne 503 z nginx, połączenie reset) też wyzwalał advance. Wszystkie ścieżki logują console.warn('[slideshow*-watchdog] forcing advance', ...) do diagnostyki post-mortem.