0707. / AetherWall

Tworzenie tapet AetherWall 0.5

Minimalna paczka

ZIP ma w katalogu głównym wallpaper.json, index.html oraz CSS/JS. Opcjonalna miniatura to preview.png (maks. 3 MB, do 16 mln pikseli). HTML jest otwierany w WebView2. Nie wymaga serwera ani node_modules. Limit paczki: 100 MB po rozpakowaniu, 1500 plików. Nie są obsługiwane ZIP64, szyfrowanie, dowiązania ani ścieżki wychodzące poza paczkę. Używaj nazw plików UTF-8.

{
 "id":"moja-tapeta",
 "title":"Moja tapeta",
 "author":"Twoja nazwa",
 "description":"Opis tapety",
 "entry":"index.html",
 "version":1,
 "supportsWidgets":true,
 "display":{"width":1920,"height":1080,"minWidth":1280,"minHeight":720,"responsive":true,"aspectRatios":["16:9","16:10","21:9"]},
 "properties":[
  {"key":"accent","label":"Kolor akcentu","type":"color","default":"#8FCCF0"},
  {"key":"speed","label":"Szybkość","type":"slider","min":0,"max":100,"step":1,"default":40},
  {"key":"effects","label":"Efekty","type":"bool","default":true},
  {"key":"caption","label":"Podpis","type":"text","default":"Witaj"},
  {"key":"mode","label":"Motyw","type":"choice","options":["Ciemny","Jasny"],"default":"Ciemny"}
 ]
}

id: małe litery, cyfry i myślniki, do 64 znaków. entry musi wskazywać istniejący HTML. Maks. 64 właściwości. Klucz właściwości zaczyna się literą, potem litery, cyfry lub _, maks. 64 znaki. Wartości domyślne muszą zgadzać się z typem i zakresem. Nie umieszczaj danych użytkownika w paczce.

Właściwości i SDK

Host wywołuje listener po wczytaniu dokumentu i po zatwierdzeniu zmian:

window.wallpaperPropertyListener = {
 applyUserProperties(properties) {
  if (properties.accent) document.documentElement.style.setProperty('--accent', properties.accent.value);
 }
};

Alternatywnie słuchaj zdarzenia aetherwall-properties. event.detail zawiera obiekty {value: ...}. Ostatnie ustawienia są w window.aetherWallProperties. Parametry zapisywane są osobno dla tapety i monitora. Dołączona biblioteka aetherwall-sdk.js daje onProperties, onPerformance, onEditMode oraz save/load. Działa też w zwykłej przeglądarce z ograniczonym zakresem funkcji.

Rozdzielczość i wiele ekranów

Używaj CSS procentowego, grid/flex i resize/ResizeObserver. Obliczaj rozmiar canvas z jego kontenera. W trybie automatycznym viewport odpowiada rozmiarowi monitora. contain zachowuje proporcje z pasami, cover skaluje i przycina projekt; zoom wpływa na CSS viewport.

Każdy monitor ma osobną instancję przeglądarki i wybór tapety. Ten sam id tapety współdzieli profil przeglądarki i localStorage między ekranami: dokumenty mogą być wspólne. Parametry wyglądu są niezależne dla monitorów. Słuchaj zdarzenia storage, jeśli chcesz synchronizować otwarte widoki tych samych notatek.

supportsWidgets:false wyłącza nakładkę widżetów dla tej tapety. Przełącznik edycji pozostaje dostępny. Widżety programu nie są częścią paczki autora i prywatna treść nie trafia do workshopu.

Pisanie na pulpicie

Używaj zwykłych input, textarea lub contenteditable. Włączona ikona ołówka wynosi tę samą tapetę nad ikony i nadaje jej normalny fokus klawiatury. Esc kończy edycję bez przeładowania. window.aetherWallEditMode oraz zdarzenie aetherwall-edit-mode sygnalizują stan. Nie przechwytuj Escape w fazie capture przed listenerem hosta. Przełącznik można przesuwać w trybie edycji.

Animacja, limit FPS i wydajność

AetherWall ogranicza wywołania requestAnimationFrame do skonfigurowanego FPS. Limit nie obejmuje CSS/WAAPI, WebGL animowanego innymi timerami, wideo ani kompozytora WebView2. Nie ma globalnego twardego limitu FPS WebView2. Płynna, oszczędna tapeta powinna używać jednej pętli RAF, czasu przekazanego do callbacku, DPR ograniczonego do potrzeb i unikać stałych timerów oraz filtrów na całym ekranie.

let previous=0;
function frame(time) {
 const dt=Math.min(.1,(time-previous)/1000);previous=time;
 // Aktualizuj scenę na podstawie dt, nie liczby klatek.
 requestAnimationFrame(frame);
}
requestAnimationFrame(frame);
window.addEventListener('aetherwall-performance', e => {
 const {fps,reducedMotion}=e.detail;
 // Dostosuj liczbę cząstek lub efekty.
});

window.aetherWallPerformance ma fps i reducedMotion. Obsługuj także prefers-reduced-motion. Pauza hosta wstrzymuje WebView2 i odbiór audio; po powrocie dt może być duże, dlatego ograniczaj skok czasu. Profil oszczędny ogranicza RAF i częstotliwość FFT. Ustawienie renderer CPU/GPU zaczyna działać po restarcie. Tryb CPU nie gwarantuje mniejszego zużycia zasobów.

Audio i multimedia

Opcjonalnie wywołaj wallpaperRegisterAudioListener(samples => ...). samples ma 128 wartości [0,1]; pierwsze 64 to widmo, drugie 64 zdublowane. Obecny silnik analizuje pierwszy kanał domyślnego wyjścia audio. Nie używa mikrofonu. Częstotliwość zdarzeń zależy od ustawienia audio; funkcja może nie wysyłać próbek, gdy analiza jest wyłączona lub tapeta wstrzymana.

Opcjonalne funkcje wallpaperRegisterMediaPropertiesListener, wallpaperRegisterMediaThumbnailListener, wallpaperRegisterMediaTimelineListener, wallpaperRegisterMediaPlaybackListener i wallpaperRegisterMediaStatusListener przekazują informacje z sesji multimediów Windows. Rejestracja uruchamia potrzebny most. W standardowej przeglądarce sprawdzaj istnienie funkcji przed wywołaniem.

Zapis, sieć i uprawnienia

localStorage/IndexedDB są trwałe w profilu id tapety. Nie zapisuj plików w katalogu paczki. Przeglądarka może korzystać z sieci, lecz uprawnienia urządzeń i pobieranie plików są blokowane. Nowe okna i nawigacja poza lokalny origin są blokowane. Tapety zawierają kod wykonywalny autora; suma SHA-256 zapewnia integralność paczki, a nie zaufanie do jej treści. Nie umieszczaj sekretów w JS.

Publikacja

Workshop: https://0707.pl/soft/aetherwall/api/catalog.json

Opublikuj ZIP z programu albo formularza witryny z kluczem nadanym przez administratora. Serwer kontroluje format ZIP, ścieżki, manifest, miniaturę i SHA-256. Po publikacji paczka jest publicznie dostępna; administrator może ją usunąć. Serwer nie obsługuje publicznych kont, ocen ani automatycznych aktualizacji instalacji. Aby opublikować nową instalowalną wersję, nadaj jej nowy id, np. moja-tapeta-v2 (obecny importer chroni przed nadpisaniem danych istniejącego id).

API: GET api/catalog.json?q=...&sort=newest|popular; GET api/packages/{id}.zip; POST api/publish (surowy ZIP) z X-Workshop-Token, X-Title, X-Author, X-Description (trzy teksty URL-encoded); DELETE api/packages/{id} z X-Workshop-Token. Lista zwraca url, sha256, preview, created, size i downloads. Licznik pobrań obejmuje żądania pliku, nie unikalnych użytkowników.

Weryfikacja przed publikacją

Sprawdź minimum 1280×720, 1920×1080, ultrawide i pionowy viewport, wszystkie właściwości i ich reset, wpisywanie tekstu z polskimi znakami, brak sieci, pauzę i wznowienie oraz limit RAF. Upewnij się, że ZIP nie zawiera Data, kluczy, prywatnych notatek ani testów. Przykład działającej tapety jest w Wallpapers/aurora.

Projekty MP4 (od wersji 0.6)

Importuj bezpośrednio MP4 w Bibliotece. Program kopiuje film i tworzy projekt wideo; nie potrzebujesz index.html ani własnego kodu strony. Film pozostaje niezmieniony, bez konwersji. Odtwarzacz programu obsługuje pętlę, wyciszenie, głośność, prędkość, dopasowanie, jasność, kontrast, nasycenie, rozmycie, kolor, cząsteczki, poświatę reagującą na systemowe audio oraz ruch za kursorem. Widżety i edycja pulpitu działają także z MP4. Efekty nie tworzą prawdziwej głębi 3D filmu ani animacji obiektów z nieruchomego obrazu.

Minimalny manifest paczki wideo:

{"id":"moj-film","title":"Mój film","author":"Autor","description":"Tapeta wideo","entry":"video.mp4","version":1,"type":"video","supportsWidgets":true}

Paczka zawiera wallpaper.json i video.mp4, opcjonalnie preview.png. Brak properties automatycznie udostępnia parametry odtwarzacza. Jeśli podajesz properties, użyj kluczy loop, muted, volume, speed, videoFit, brightness, contrast, saturation, blur, tint, tintStrength, particles, particleCount, audioReactive, parallax zgodnie z Modern/VideoProject.cs. Stare paczki HTML nadal działają, type domyślnie wynosi web.

Dla największej zgodności użyj MP4 z H.264 (AVC) i opcjonalnym AAC. Samo rozszerzenie MP4 nie gwarantuje zgodnego kodeka. Film pauzuje wraz z tapetą. Limit animacji JS ogranicza dodatkowe cząsteczki, nie liczbę klatek zdekodowanego filmu. Tryb ograniczonego ruchu wyłącza animowane efekty i parallax, lecz film nadal jest odtwarzany. Reakcja na audio wymaga włączonej analizy audio w ustawieniach programu. Ruch kursora na pulpicie działa w miejscach niezasłoniętych ikonami.

Bezpośredni import lokalnego MP4 nie ma limitu 100 MB. Workshop zachowuje limit 100 MB paczki i rozpakowanych danych; przed publikacją dłuższy film trzeba zoptymalizować. Import kopiuje film do biblioteki, więc wymaga wolnego miejsca na dysku.