@konce-pt/backdrop 0.8.5

package/dist/renderer.js

@@ -0,0 +1,348 @@
+/**
+ * Renderery efektów tła.
+ *
+ * Rysowanie nie potrzebuje frameworka — potrzebuje `CanvasRenderingContext2D`. Dzięki temu
+ * komponent w Angularze i w Reakcie zostaje samym cyklem życia (rAF, obserwatory rozmiaru,
+ * widoczności i motywu) wokół tego samego renderera, zamiast dwa razy powtarzać pętlę rysowania.
+ *
+ * Kolory wchodzą tu już rozwiązane: canvas nie rozwija `var()`, więc token na konkretny kolor
+ * zamienia wywołujący, który jedyny wie, na jakim elemencie go odczytać.
+ */
+import { adaptToSurface, mixOklch, parseHexColor, prefersDarkContent, readCssColor, shiftHue, toHexColor, } from "./color.js";
+import { buildSignalGrid, signalGridAlpha } from "./signal-grid.js";
+import { resolveWave, waveBuffer, waveIntensity, waveRamp } from "./wave.js";
+/** Poniżej tego krycia kwadrat i tak nie byłby widoczny — nie ma po co go rysować. */
+const ALPHA_CUTOFF = 0.02;
+/** Ile przystanków ma podręczna tablica barw rampy. */
+const LUT_STOPS = 256;
+/** Gęstość pikseli powyżej dwóch nic nie wnosi przy tych efektach, a kosztuje kwadratowo. */
+export const KPT_BACKDROP_MAX_DPR = 2;
+/** Górna granica kroku czasu (ms) — karta wróciwszy z tła nie ma przewijać animacji do przodu. */
+export const KPT_BACKDROP_MAX_STEP = 100;
+/** O tyle stopni rozchodzą się domyślne barwy wstęgi względem koloru wiodącego. */
+export const KPT_BACKDROP_RAMP_SPREAD = 28;
+/** Własność-sonda; żyje tylko na czas jednego odczytu. */
+const PROBE_PROPERTY = '--_kpt-probe';
+/**
+ * Wyrażenie CSS rozwiązane względem drzewa: `var()` podstawione wartościami obowiązującymi w tym
+ * miejscu dokumentu. Dzięki temu wejście koloru może sięgnąć po token i samo iść za motywem,
+ * zamiast zamarzać na wartości z chwili napisania szablonu.
+ *
+ * `scope` musi być **potomkiem** hosta. `observeBackdropTheme` ogląda `style` na hoście i każdym
+ * jego przodku, więc sonda zapisana na hoście obudziłaby nasłuch, ten sięgnąłby po kolor na nowo,
+ * znów zapisał sondę — i pętla nie miałaby końca. Potomek jest poza zasięgiem nasłuchu.
+ *
+ * Bramka na `var(` nie jest kosmetyczna: bez niej każdy literał kosztowałby zapis stylu
+ * i wymuszone przeliczenie kaskady, a nie ma w nim czego rozwiązywać.
+ *
+ * Odwołanie do nieistniejącej zmiennej daje pusty napis — to sygnał „nie dało się", który
+ * wywołujący czyta jako brak wartości.
+ */
+export function resolveCssValue(scope, value) {
+    if (!value.includes('var('))
+        return value;
+    scope.style.setProperty(PROBE_PROPERTY, value);
+    const resolved = getComputedStyle(scope).getPropertyValue(PROBE_PROPERTY).trim();
+    scope.style.removeProperty(PROBE_PROPERTY);
+    return resolved;
+}
+/**
+ * Sam kolor wiodący: wejście komponentu, a bez niego token odczytany z wyliczonego stylu.
+ *
+ * Wydzielone z `resolveBackdropColors`, bo służy też za tani strażnik przy zmianie motywu —
+ * `getComputedStyle` bez sondy 1×1 i bez arytmetyki barw.
+ *
+ * Wejście przechodzi przez `resolveCssValue`, więc `var(--kpt-color-primary)` działa i zmienia się
+ * razem z motywem, a literał zostaje literałem. Zapis odwołujący się do zmiennej, której nie ma,
+ * schodzi do tokenu — tego chciałby autor literówki w nazwie.
+ */
+export function readBackdropLead(scope, color) {
+    const explicit = resolveCssValue(scope, color.trim());
+    if (explicit)
+        return explicit;
+    const style = getComputedStyle(scope);
+    return style.getPropertyValue('--_dot').trim() || style.color;
+}
+/**
+ * Czy adaptacja ma tę wartość ruszać.
+ *
+ * Pusta bierze token, a zapis z `var()` sam sięga po token — jedno i drugie już idzie za motywem
+ * i przeliczenie odwróciłoby je drugi raz, czyli z powrotem. Adaptacja dotyczy wyłącznie tego,
+ * co autor wpisał na sztywno, bo tylko to nie umie się samo ruszyć.
+ */
+const adaptable = (value) => value.trim() !== '' && !value.includes('var(');
+/** Powierzchnia bieżącego motywu — punkt odniesienia adaptacji. */
+export function readBackdropSurface(scope) {
+    return readCssColor(resolveCssValue(scope, 'var(--kpt-color-surface)'));
+}
+/**
+ * Barwa przeniesiona na powierzchnię bieżącego motywu. Wartość, która nie podlega adaptacji albo
+ * której nie da się odczytać, wraca bez zmian — adaptacja nigdy nie gubi tego, co podano.
+ */
+export function adaptBackdropValue(value, surface) {
+    if (!surface || !adaptable(value))
+        return value;
+    const rgb = readCssColor(value);
+    return rgb ? toHexColor(adaptToSurface(rgb, surface)) : value;
+}
+/** Treść na jasnym tle sekcji. Prymitywy nie zmieniają się z motywem, więc wybór jest absolutny. */
+const DARK_CONTENT = 'var(--kpt-color-neutral-900)';
+/** Treść na ciemnym tle sekcji. */
+const LIGHT_CONTENT = 'var(--kpt-color-neutral-50)';
+/**
+ * Ton i kolor treści dobrane do tła, które sekcja naprawdę maluje.
+ *
+ * Host ustawia `color` tokenem powierzchni strony, ale sekcja z własnym `background` przestaje być
+ * tą powierzchnią — i wtedy token opisuje sąsiada, nie to, na czym treść leży. Bez tego rachunku
+ * ciemne tło w motywie jasnym daje czarny napis na czarnym.
+ *
+ * Ton wychodzi też na zewnątrz atrybutem, bo o kolor treści dopomina się nie tylko sam napis:
+ * przyciski i inne komponenty w sekcji potrzebują kompletu tokenów pod to tło, a tego nie da się
+ * odziedziczyć po `color`.
+ */
+export function readBackdropInk(scope, background) {
+    if (!background.trim())
+        return { tone: '', color: '' };
+    const rgb = readCssColor(resolveCssValue(scope, background));
+    if (!rgb)
+        return { tone: '', color: '' };
+    return prefersDarkContent(rgb)
+        ? { tone: 'light', color: DARK_CONTENT }
+        : { tone: 'dark', color: LIGHT_CONTENT };
+}
+/** Atrybuty, którymi przestawia się tokeny: motyw atrybutowy, klasowy i nadpisanie inline. */
+const THEME_ATTRIBUTES = ['data-theme', 'class', 'style'];
+/**
+ * Nasłuch na wszystkim, co może przestawić tokeny pod hostem. Zwraca funkcję odpinającą.
+ *
+ * Motyw bywa zakresowy — `[data-theme="dark"]` nie jest przywiązany do `:root`, więc tokeny
+ * przestawia dowolny przodek. Łańcuch od hosta w górę jest krótki i znany, więc obserwujemy go
+ * w całości, zamiast puszczać `subtree` na dokumencie, gdzie trafieniem byłaby każda zmiana klasy
+ * w aplikacji. Pętla kończy się na `<html>`, bo rodzicem `<html>` jest dokument, nie element.
+ *
+ * Do tego zapytanie o preferencję systemu: aplikacja może trzymać ciemne tokeny w media query
+ * zamiast w atrybucie i wtedy nie zmienia się nic, co da się zaobserwować w DOM.
+ *
+ * Łańcuch przodków jest brany w chwili zapisu — przeniesienie hosta w inne miejsce drzewa wymaga
+ * ponownego zapisu. Komponent takiego przypadku nie obsługuje.
+ *
+ * Nasłuch trafia też w zmiany niezwiązane z barwą (klasa nakładki na `<html>`, dowolne nadpisanie
+ * inline), więc wywołujący ma porównać `readBackdropLead` z poprzednim odczytem, zanim cokolwiek
+ * przebuduje.
+ */
+export function observeBackdropTheme(host, onChange) {
+    if (typeof MutationObserver === 'undefined')
+        return () => undefined;
+    const observer = new MutationObserver(onChange);
+    for (let node = host; node; node = node.parentElement) {
+        observer.observe(node, { attributes: true, attributeFilter: THEME_ATTRIBUTES });
+    }
+    const scheme = matchMedia('(prefers-color-scheme: dark)');
+    scheme.addEventListener('change', onChange);
+    return () => {
+        observer.disconnect();
+        scheme.removeEventListener('change', onChange);
+    };
+}
+/**
+ * Zamienia wejścia koloru na wartości, które rozumie renderer.
+ *
+ * Canvas nie rozwija `var()`, więc token trzeba odczytać z wyliczonego stylu elementu — komponent
+ * jest jedynym miejscem, które wie, z którego. Pusta rampa bierze kolor wiodący i dwie barwy
+ * wyprowadzone z niego obrotem odcienia: paleta biblioteki jest neutralna, więc sięganie po tokeny
+ * statusowe (`info`, `success`) byłoby użyciem semantyki do dekoracji.
+ *
+ * `adaptive` przenosi barwy wpisane na sztywno na powierzchnię bieżącego motywu — czerń wpisana
+ * na białe tło staje się bielą, gdy tło jest ciemne. Dotyczy wyłącznie literałów: puste wejście
+ * bierze token, a zapis z `var()` sam sięga po token i jedno i drugie już idzie za motywem.
+ *
+ * Rampa podana wprost przechodzi tą samą drogą co domyślna: każdy wpis najpierw rozwiązujemy
+ * względem drzewa (`resolveCssValue`), a potem pytamy przeglądarkę o jego znaczenie. Działa więc
+ * i `oklch()`, i `color-mix()`, i nazwa własna, i odwołanie do tokenu — a `color-mix()` z tokenem
+ * w środku daje rampę, która sama idzie za motywem. Dalej, do renderera, trafia już sam hex.
+ * Wpisy, których przeglądarka nie przyjęła, wracają w `invalid` — rdzeń nie ma własnego trybu dev,
+ * więc ostrzega dopiero port. Gdy nie przeszedł żaden, schodzimy do rampy domyślnej: pusty kadr
+ * nie powiedziałby nikomu nic.
+ *
+ * `scope` musi być potomkiem hosta — powód przy `resolveCssValue`.
+ *
+ * Mieszka w rdzeniu, bo oba porty muszą rozstrzygać to samo tak samo — rozjazd znaczyłby, że ta
+ * sama sekcja ma inne barwy w Angularze niż w Reakcie.
+ */
+export function resolveBackdropColors(scope, color, colors, adaptive = false) {
+    // Powierzchnię czytamy raz na przebudowę: każdy odczyt to zapis sondy i przeliczenie kaskady.
+    const surface = adaptive ? readBackdropSurface(scope) : null;
+    const adapt = (value) => (adaptive ? adaptBackdropValue(value, surface) : value);
+    const lead = readBackdropLead(scope, adapt(color));
+    const explicit = colors.filter((entry) => entry.trim().length > 0);
+    const parsed = [];
+    const invalid = [];
+    for (const entry of explicit) {
+        const rgb = readCssColor(resolveCssValue(scope, adapt(entry)));
+        if (rgb)
+            parsed.push(toHexColor(rgb));
+        else
+            invalid.push(entry);
+    }
+    if (parsed.length > 0)
+        return { color: lead, colors: parsed, invalid };
+    const rgb = readCssColor(lead);
+    if (!rgb)
+        return { color: lead, colors: [], invalid };
+    return {
+        color: lead,
+        colors: [
+            toHexColor(shiftHue(rgb, -KPT_BACKDROP_RAMP_SPREAD)),
+            toHexColor(rgb),
+            toHexColor(shiftHue(rgb, KPT_BACKDROP_RAMP_SPREAD)),
+        ],
+        invalid,
+    };
+}
+/** Renderer, który nic nie rysuje — dla środowisk bez DOM i dla pustej rampy barw. */
+const IDLE = {
+    resize: () => undefined,
+    draw: () => undefined,
+    dispose: () => undefined,
+};
+/**
+ * Drobna siatka migoczących kwadratów. Cała matematyka siedzi w `signal-grid.ts`;
+ * tutaj zostaje pętla po komórkach.
+ */
+export function createSignalGridRenderer(options) {
+    let width = 0;
+    let height = 0;
+    let grid = null;
+    const color = options.color ?? '#ffffff';
+    return {
+        resize(nextWidth, nextHeight) {
+            width = nextWidth;
+            height = nextHeight;
+            grid = buildSignalGrid({
+                width,
+                height,
+                cell: options.cell,
+                gap: options.gap,
+                anchor: options.anchor,
+                density: options.density,
+                falloff: options.falloff,
+                seed: options.seed,
+            });
+        },
+        draw(context, time) {
+            if (!grid)
+                return;
+            context.clearRect(0, 0, width, height);
+            context.fillStyle = color;
+            for (const cell of grid.cells) {
+                const alpha = signalGridAlpha(cell, time);
+                if (alpha < ALPHA_CUTOFF)
+                    continue;
+                context.globalAlpha = alpha;
+                context.fillRect(cell.x, cell.y, cell.size, cell.size);
+            }
+            context.globalAlpha = 1;
+        },
+        dispose() {
+            grid = null;
+        },
+    };
+}
+/**
+ * Jedna miękka wstęga światła z barwami przesuwającymi się wzdłuż niej.
+ *
+ * Liczymy ją w buforze o dłuższym boku `KPT_WAVE_RESOLUTION` i skalujemy w górę — miękkość
+ * bierze się z interpolacji przeglądarki, więc kilkanaście tysięcy pikseli na klatkę wystarcza
+ * na dowolnie duży kadr. Rampa barw idzie przez podręczną tablicę: mieszanie po kole OKLCH raz
+ * na piksel byłoby kilkoma pierwiastkami i arkusem tangensa na każdy z nich.
+ */
+export function createWaveRenderer(options) {
+    const ramp = (options.colors ?? []).map(parseHexColor).filter((color) => color !== null);
+    if (ramp.length === 0 || typeof document === 'undefined')
+        return IDLE;
+    const lut = new Uint8ClampedArray(LUT_STOPS * 3);
+    for (let stop = 0; stop < LUT_STOPS; stop += 1) {
+        const { r, g, b } = mixOklch(ramp, stop / LUT_STOPS);
+        lut[stop * 3] = r;
+        lut[stop * 3 + 1] = g;
+        lut[stop * 3 + 2] = b;
+    }
+    const buffer = document.createElement('canvas');
+    const bufferContext = buffer.getContext('2d');
+    let width = 0;
+    let height = 0;
+    let cols = 0;
+    let rows = 0;
+    let image = null;
+    let settings = null;
+    return {
+        resize(nextWidth, nextHeight) {
+            width = nextWidth;
+            height = nextHeight;
+            const size = waveBuffer(width, height);
+            cols = size.cols;
+            rows = size.rows;
+            if (!bufferContext || cols === 0 || rows === 0) {
+                image = null;
+                return;
+            }
+            buffer.width = cols;
+            buffer.height = rows;
+            image = bufferContext.createImageData(cols, rows);
+            settings = resolveWave({
+                width,
+                height,
+                rotation: options.rotation,
+                band: options.band,
+                amplitude: options.amplitude,
+                seed: options.seed,
+            });
+        },
+        draw(context, time) {
+            if (!image || !bufferContext || !settings)
+                return;
+            const data = image.data;
+            let offset = 0;
+            for (let row = 0; row < rows; row += 1) {
+                // Próbkujemy środek komórki bufora, nie jej róg — inaczej obraz przesuwałby się
+                // o pół piksela przy każdej zmianie rozdzielczości.
+                const v = (row + 0.5) / rows;
+                for (let col = 0; col < cols; col += 1) {
+                    const u = (col + 0.5) / cols;
+                    const stop = Math.min(LUT_STOPS - 1, (waveRamp(u, v, time, settings) * LUT_STOPS) | 0) * 3;
+                    data[offset] = lut[stop];
+                    data[offset + 1] = lut[stop + 1];
+                    data[offset + 2] = lut[stop + 2];
+                    // Barwę piszemy także tam, gdzie krycie jest zerowe: przy skalowaniu w górę
+                    // przeglądarka interpoluje wszystkie cztery składowe i zostawiony śmieć
+                    // wypłynąłby na krawędziach wstęgi.
+                    data[offset + 3] = waveIntensity(u, v, time, settings) * 255;
+                    offset += 4;
+                }
+            }
+            bufferContext.putImageData(image, 0, 0);
+            context.clearRect(0, 0, width, height);
+            context.imageSmoothingEnabled = true;
+            context.imageSmoothingQuality = 'high';
+            context.drawImage(buffer, 0, 0, width, height);
+        },
+        dispose() {
+            image = null;
+            settings = null;
+            // Zerowy rozmiar zwalnia pamięć bufora od razu, bez czekania na zbieracza.
+            buffer.width = 0;
+            buffer.height = 0;
+        },
+    };
+}
+/** Renderer wskazanego efektu. Nieznany efekt nie rysuje niczego, zamiast wywracać klatkę. */
+export function createBackdropRenderer(options) {
+    switch (options.effect ?? 'signal-grid') {
+        case 'signal-grid':
+            return createSignalGridRenderer(options);
+        case 'wave':
+            return createWaveRenderer(options);
+        default:
+            return IDLE;
+    }
+}

package/dist/signal-grid.d.ts

@@ -0,0 +1,35 @@
+import type { KptSignalGridAlphaOptions, KptSignalGridCell, KptSignalGridFrame, KptSignalGridOptions } from './types.ts';
+/** Bok kwadratu (px). */
+export declare const KPT_SIGNAL_GRID_CELL = 5;
+/** Odstęp między kwadratami (px). */
+export declare const KPT_SIGNAL_GRID_GAP = 11;
+/** Udział zapalonych komórek przy kotwicy. */
+export declare const KPT_SIGNAL_GRID_DENSITY = 0.8;
+/** Wykładnik wygaszania ku przeciwnej krawędzi. */
+export declare const KPT_SIGNAL_GRID_FALLOFF = 1.4;
+/** Krycie komórki w dołku migotania. */
+export declare const KPT_SIGNAL_GRID_FLOOR = 0.18;
+/** Radiany na sekundę przy `speed = 1` — pełny cykl komórki to wtedy około siedmiu sekund. */
+export declare const KPT_SIGNAL_GRID_RATE = 0.9;
+/**
+ * Rampa gęstości: udział zapalonych komórek w odległości `distance` od kotwicy (0 przy kotwicy,
+ * 1 przy przeciwnej krawędzi). To ona robi cały efekt — gradient bierze się z tego, ile kwadratów
+ * się pali, nie z przezroczystości nałożonej na równomierną siatkę.
+ */
+export declare function signalGridDensity(distance: number, density: number, falloff: number): number;
+/**
+ * Buduje siatkę pod zadany obszar. Liczy się raz — przy starcie i przy zmianie rozmiaru — bo
+ * geometria i losowania komórek są w czasie stałe; w klatce zmienia się wyłącznie krycie.
+ *
+ * Siatka celowo wychodzi poza obszar: liczba kolumn zaokrągla się w górę, a nadmiar rozkłada się
+ * po równo na obie strony. Siatka kończąca się przed krawędzią wygląda na uciętą.
+ */
+export declare function buildSignalGrid(options: KptSignalGridOptions): KptSignalGridFrame;
+/**
+ * Krycie komórki w chwili `time` (sekundy). Sinus przepuszczony przez wygładzenie — surowy
+ * zostawiałby komórki najdłużej w połowie jasności, a migotanie ma przystawać na końcach.
+ *
+ * `speed` równe zeru zatrzymuje obraz, nie gasi go: każda komórka zostaje na swojej fazie,
+ * więc statyczna klatka (ruch ograniczony w systemie) wciąż ma zróżnicowaną jasność.
+ */
+export declare function signalGridAlpha(cell: KptSignalGridCell, time: number, options?: KptSignalGridAlphaOptions): number;

package/dist/signal-grid.js

@@ -0,0 +1,88 @@
+import { kptHash01 } from "./hash.js";
+/** Bok kwadratu (px). */
+export const KPT_SIGNAL_GRID_CELL = 5;
+/** Odstęp między kwadratami (px). */
+export const KPT_SIGNAL_GRID_GAP = 11;
+/** Udział zapalonych komórek przy kotwicy. */
+export const KPT_SIGNAL_GRID_DENSITY = 0.8;
+/** Wykładnik wygaszania ku przeciwnej krawędzi. */
+export const KPT_SIGNAL_GRID_FALLOFF = 1.4;
+/** Krycie komórki w dołku migotania. */
+export const KPT_SIGNAL_GRID_FLOOR = 0.18;
+/** Radiany na sekundę przy `speed = 1` — pełny cykl komórki to wtedy około siedmiu sekund. */
+export const KPT_SIGNAL_GRID_RATE = 0.9;
+/** Szczytowe krycie komórki przy przeciwnej krawędzi — tam, gdzie rampa już nic nie daje. */
+const MIN_PRESENCE = 0.35;
+const TAU = Math.PI * 2;
+const clamp01 = (value) => (value < 0 ? 0 : value > 1 ? 1 : value);
+/**
+ * Rampa gęstości: udział zapalonych komórek w odległości `distance` od kotwicy (0 przy kotwicy,
+ * 1 przy przeciwnej krawędzi). To ona robi cały efekt — gradient bierze się z tego, ile kwadratów
+ * się pali, nie z przezroczystości nałożonej na równomierną siatkę.
+ */
+export function signalGridDensity(distance, density, falloff) {
+    return density * Math.pow(1 - clamp01(distance), Math.max(0, falloff));
+}
+/**
+ * Buduje siatkę pod zadany obszar. Liczy się raz — przy starcie i przy zmianie rozmiaru — bo
+ * geometria i losowania komórek są w czasie stałe; w klatce zmienia się wyłącznie krycie.
+ *
+ * Siatka celowo wychodzi poza obszar: liczba kolumn zaokrągla się w górę, a nadmiar rozkłada się
+ * po równo na obie strony. Siatka kończąca się przed krawędzią wygląda na uciętą.
+ */
+export function buildSignalGrid(options) {
+    const cell = Math.max(1, options.cell ?? KPT_SIGNAL_GRID_CELL);
+    const gap = Math.max(0, options.gap ?? KPT_SIGNAL_GRID_GAP);
+    const anchor = options.anchor ?? 'right';
+    const density = clamp01(options.density ?? KPT_SIGNAL_GRID_DENSITY);
+    const falloff = Math.max(0, options.falloff ?? KPT_SIGNAL_GRID_FALLOFF);
+    const seed = options.seed ?? 0;
+    const width = Math.max(0, options.width);
+    const height = Math.max(0, options.height);
+    const stride = cell + gap;
+    const cols = width > 0 ? Math.ceil((width + gap) / stride) : 0;
+    const rows = height > 0 ? Math.ceil((height + gap) / stride) : 0;
+    const originX = Math.round((width - (cols * stride - gap)) / 2);
+    const originY = Math.round((height - (rows * stride - gap)) / 2);
+    const cells = [];
+    for (let col = 0; col < cols; col += 1) {
+        const span = cols > 1 ? col / (cols - 1) : 0;
+        const distance = anchor === 'right' ? 1 - span : span;
+        const ramp = Math.pow(1 - distance, falloff);
+        const lit = density * ramp;
+        // Rampę liczymy raz na kolumnę: w pionie siatka jest jednorodna, więc wnętrze pętli
+        // wierszy to już tylko trzy losowania.
+        if (lit <= 0)
+            continue;
+        const presence = MIN_PRESENCE + (1 - MIN_PRESENCE) * ramp;
+        for (let row = 0; row < rows; row += 1) {
+            if (kptHash01(col, row, seed) >= lit)
+                continue;
+            cells.push({
+                x: originX + col * stride,
+                y: originY + row * stride,
+                size: cell,
+                presence,
+                phase: kptHash01(col, row, seed + 101) * TAU,
+                // Tempo rozstrzelone w przedziale 0,45–1,55: przy jednym tempie cała siatka
+                // pulsowałaby zgodnie i zamiast migotania wyszedłby oddech.
+                rate: 0.45 + kptHash01(col, row, seed + 211) * 1.1,
+            });
+        }
+    }
+    return { cols, rows, cell, gap, cells };
+}
+/**
+ * Krycie komórki w chwili `time` (sekundy). Sinus przepuszczony przez wygładzenie — surowy
+ * zostawiałby komórki najdłużej w połowie jasności, a migotanie ma przystawać na końcach.
+ *
+ * `speed` równe zeru zatrzymuje obraz, nie gasi go: każda komórka zostaje na swojej fazie,
+ * więc statyczna klatka (ruch ograniczony w systemie) wciąż ma zróżnicowaną jasność.
+ */
+export function signalGridAlpha(cell, time, options = {}) {
+    const speed = options.speed ?? 1;
+    const floor = clamp01(options.floor ?? KPT_SIGNAL_GRID_FLOOR);
+    const wave = 0.5 + 0.5 * Math.sin(time * speed * KPT_SIGNAL_GRID_RATE * cell.rate + cell.phase);
+    const eased = wave * wave * (3 - 2 * wave);
+    return cell.presence * (floor + (1 - floor) * eased);
+}

package/dist/types.d.ts

@@ -0,0 +1,96 @@
+/** Krawędź, przy której siatka jest najgęstsza; ku przeciwnej wygasa do pustki. */
+export type KptBackdropAnchor = 'left' | 'right';
+/** Efekt tła. */
+export type KptBackdropEffect = 'signal-grid' | 'wave';
+/** Ustawienia siatki. Wymiary w pikselach CSS, nie w pikselach urządzenia. */
+export interface KptSignalGridOptions {
+    /** Szerokość obszaru rysowania (px CSS). */
+    width: number;
+    /** Wysokość obszaru rysowania (px CSS). */
+    height: number;
+    /** Bok kwadratu (px). */
+    cell?: number;
+    /** Odstęp między kwadratami (px). */
+    gap?: number;
+    /** Krawędź, przy której siatka jest najgęstsza. */
+    anchor?: KptBackdropAnchor;
+    /** Udział zapalonych komórek przy kotwicy, 0–1. */
+    density?: number;
+    /** Jak szybko gęstość spada ku przeciwnej krawędzi; >1 gasi gwałtowniej. */
+    falloff?: number;
+    /** Ziarno losowania — ta sama wartość daje ten sam układ przy każdym uruchomieniu. */
+    seed?: number;
+}
+/** Pojedynczy kwadrat. Geometria i losowania liczą się raz, przy zmianie rozmiaru. */
+export interface KptSignalGridCell {
+    /** Lewy górny róg w px CSS; może wypaść poza obszar, bo siatka celowo wychodzi za krawędź. */
+    x: number;
+    y: number;
+    /** Bok kwadratu (px). */
+    size: number;
+    /** Szczytowa krycie komórki, 0–1 — spada wraz z gęstością ku przeciwnej krawędzi. */
+    presence: number;
+    /** Przesunięcie fazy migotania (radiany). */
+    phase: number;
+    /** Mnożnik tempa migotania — bez niego cała siatka pulsowałaby zgodnie. */
+    rate: number;
+}
+/** Gotowa siatka: wymiary w komórkach i lista kwadratów do narysowania. */
+export interface KptSignalGridFrame {
+    cols: number;
+    rows: number;
+    cell: number;
+    gap: number;
+    cells: readonly KptSignalGridCell[];
+}
+/** Ustawienia wstęgi. Wymiary w pikselach CSS, nie w pikselach urządzenia. */
+export interface KptWaveOptions {
+    /** Szerokość obszaru rysowania (px CSS). */
+    width: number;
+    /** Wysokość obszaru rysowania (px CSS). */
+    height: number;
+    /** Kąt, pod jakim prąd przecina kadr (stopnie); 0 to poziomo w prawo. */
+    rotation?: number;
+    /** Szerokość wstęgi jako ułamek wysokości kadru. */
+    band?: number;
+    /** Wykładnik opadania od linii środkowej; 2 to krzywa Gaussa, więcej spłaszcza rdzeń. */
+    softness?: number;
+    /** Jak mocno faluje linia środkowa, w ułamkach wysokości kadru. */
+    amplitude?: number;
+    /** Ile rampy barw przypada na jednostkę długości wzdłuż wstęgi. */
+    spread?: number;
+    /** Ile rampy barw przesuwa się na sekundę. */
+    drift?: number;
+    /** Ziarno losowania — ta sama wartość daje ten sam przebieg falowania. */
+    seed?: number;
+}
+/** Jedna składowa linii środkowej wstęgi. */
+export interface KptWaveHarmonic {
+    frequency: number;
+    rate: number;
+    phase: number;
+    weight: number;
+}
+/**
+ * Ustawienia rozłożone na wartości gotowe do odczytu w pętli po pikselach.
+ * Powstają raz, przy zmianie wejść albo rozmiaru — nie na każdą klatkę.
+ */
+export interface KptWaveSettings {
+    /** Proporcja kadru; bez niej obrót skośnie ściskałby wstęgę. */
+    aspect: number;
+    cos: number;
+    sin: number;
+    band: number;
+    softness: number;
+    amplitude: number;
+    spread: number;
+    drift: number;
+    harmonics: readonly KptWaveHarmonic[];
+}
+/** Ustawienia krycia w czasie. */
+export interface KptSignalGridAlphaOptions {
+    /** Mnożnik tempa — 1 to domyślne tempo `KPT_SIGNAL_GRID_RATE`. */
+    speed?: number;
+    /** Krycie komórki w dołku migotania, 0–1. Zero gasi ją do końca. */
+    floor?: number;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/wave.d.ts

@@ -0,0 +1,58 @@
+import type { KptWaveOptions, KptWaveSettings } from './types.ts';
+/** Dłuższy bok bufora, w którym liczy się efekt (px). */
+export declare const KPT_WAVE_RESOLUTION = 160;
+/** Najmniejsza liczba próbek na bok bufora — chyba że sam obszar jest mniejszy. */
+export declare const KPT_WAVE_MIN_SIDE = 72;
+/** Szerokość wstęgi jako ułamek wysokości kadru. */
+export declare const KPT_WAVE_BAND = 0.34;
+/** Wykładnik opadania od linii środkowej; 2 to krzywa Gaussa. */
+export declare const KPT_WAVE_SOFTNESS = 2;
+/** Jak mocno faluje linia środkowa, w ułamkach wysokości kadru. */
+export declare const KPT_WAVE_AMPLITUDE = 0.16;
+/** Kąt, pod jakim prąd przecina kadr (stopnie). */
+export declare const KPT_WAVE_ROTATION = 12;
+/** Ile rampy barw przypada na jednostkę długości wzdłuż wstęgi. */
+export declare const KPT_WAVE_SPREAD = 0.55;
+/** Ile rampy barw przesuwa się na sekundę przy `speed = 1`. */
+export declare const KPT_WAVE_DRIFT = 0.07;
+/** Wymiary bufora, w którym efekt jest liczony. */
+export interface KptWaveBuffer {
+    cols: number;
+    rows: number;
+}
+/**
+ * Wymiary bufora pod zadany obszar.
+ *
+ * Wstęga nie ma detalu — jest samą miękkością — więc liczenie jej w pełnej rozdzielczości canvasu
+ * byłoby płaceniem za piksele, które i tak zostaną rozmyte. Bufor o dłuższym boku
+ * `KPT_WAVE_RESOLUTION` daje kilkanaście tysięcy pikseli na klatkę, a rozmycie robi za darmo
+ * interpolacja przeglądarki przy skalowaniu go w górę.
+ *
+ * Krótszy bok ma osobną podłogę `KPT_WAVE_MIN_SIDE`. W szerokim kadrze proporcjonalne skalowanie
+ * zostawiłoby kilkadziesiąt wierszy, a po obróceniu wstęgi o kąt bliski prostemu krzywa biegłaby
+ * właśnie wzdłuż tej osi i zaczynała się łamać. Bufor nie musi trzymać proporcji kadru —
+ * próbkowanie chodzi po współrzędnych znormalizowanych, a geometrię niesie `aspect` w ustawieniach.
+ */
+export declare function waveBuffer(width: number, height: number, resolution?: number): KptWaveBuffer;
+/**
+ * Rozkłada ustawienia na wartości, które w pętli po pikselach są już tylko odczytywane.
+ *
+ * Domyślne wartości, sinus i cosinus kąta oraz harmoniczne liczą się raz — przy zmianie wejść
+ * albo rozmiaru — bo inaczej szłyby kilkanaście tysięcy razy na klatkę.
+ */
+export declare function resolveWave(options: KptWaveOptions): KptWaveSettings;
+/**
+ * Jasność wstęgi w punkcie `(u, v)` znormalizowanego kadru, w chwili `time` (sekundy).
+ *
+ * Linia środkowa to suma harmonicznych o niewspółmiernych częstotliwościach — stąd prąd faluje
+ * bez powtarzalnego wzoru. Od niej jasność opada krzywą Gaussa, więc w całym kadrze nie ma ani
+ * jednej twardej krawędzi; to właśnie odróżnia prąd światła od paska.
+ */
+export declare function waveIntensity(u: number, v: number, time: number, settings: KptWaveSettings): number;
+/**
+ * Miejsce na rampie barw (0–1) dla punktu `(u, v)` w chwili `time`.
+ *
+ * Barwy przesuwają się wzdłuż wstęgi, nie w poprzek — dlatego liczy się tylko współrzędna `s`.
+ * Wynik zawsze zawija się do 0–1, więc rosnący czas nie wyprowadza go poza rampę.
+ */
+export declare function waveRamp(u: number, v: number, time: number, settings: KptWaveSettings): number;