@konce-pt/backdrop 0.8.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 konce.pt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,84 @@
+<p align="center">
+  <img src="https://ui.konce.pt/images/koncept_ui_lib.png" alt="Koncept UI — Angular component library" width="100%" />
+</p>
+
+# @konce-pt/backdrop
+
+Animowane tło [Koncept UI](https://gitlab.com/konce-pt/koncept-ui) to dekoracyjna warstwa pod
+sekcję — rysowana na canvasie zamiast wczytywana jako obraz, więc nie kosztuje transferu, skaluje
+się bez rozdzielczości i bierze kolory z tokenów motywu.
+
+Ta paczka jest jego rdzeniem: układ siatki i rampa gęstości efektu **signal-grid**, płynąca wstęga
+i rampa barw efektu **wave**, oraz renderery canvas dla obu. Czysty TypeScript, **zero zależności
+runtime**, bez wiązania z frameworkiem.
+
+Zwykle nie instalujesz go samodzielnie: używa go `KptBackdrop` z `@konce-pt/angular`
+i z `@konce-pt/react`. Sięgnij po niego wprost, gdy rysujesz ten sam efekt własnym rendererem.
+
+```bash
+npm i @konce-pt/backdrop
+```
+
+```ts
+import { createBackdropRenderer } from '@konce-pt/backdrop';
+
+// Renderer żyje tyle, co jeden zestaw ustawień — zmiana wejść buduje nowy.
+const renderer = createBackdropRenderer({
+  effect: 'wave',
+  colors: ['#5B8AF2', '#A86DF2', '#F25B9E'],
+  rotation: 12,
+});
+
+renderer.resize(1200, 480);   // przy starcie i przy zmianie rozmiaru
+renderer.draw(context, 3.4);  // klatka dla 3,4 sekundy animacji
+```
+
+## Dwa efekty, jedna zasada
+
+**signal-grid** bierze gradient z tego, **ile** kwadratów się pali w danej odległości od kotwicy —
+nie przyciemnia gotowej, równomiernej siatki. **wave** opada od linii środkowej 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.
+
+W obu wypadkach losowania wyprowadzają się z pozycji, a nie z zapamiętanego stanu, więc zmiana
+rozmiaru okna zostawia obraz rozpoznawalnym zamiast tasować go od nowa.
+
+## Barwy mieszają się dookoła koła
+
+Rampa wstęgi jest zamknięta w pętlę i mieszana po biegunowej postaci OKLab. Interpolacja sRGB
+miesza wartości po gammie i wychodzi błotem; nawet prostokątny OKLab przecina oś achromatyczną dla
+przeciwnych odcieni, więc w połowie drogi z niebieskiego w żółty zostaje szarość — dokładnie tam,
+gdzie prąd świeci najmocniej.
+
+## Wstęga liczy się w małym buforze
+
+Efekt nie ma detalu, tylko miękkość. Liczymy go więc w buforze o dłuższym boku 160 px i skalujemy
+w górę — rozmycie robi za darmo interpolacja przeglądarki. Kilka tysięcy pikseli na klatkę
+obsługuje kadr dowolnej wielkości.
+
+## API
+
+- **Renderery** — `createBackdropRenderer`, `createSignalGridRenderer`, `createWaveRenderer`,
+  `resolveBackdropColors`, typy `KptBackdropRenderer`, `KptBackdropRenderOptions`,
+  `KptBackdropColors`
+- **Siatka** — `buildSignalGrid`, `signalGridDensity`, `signalGridAlpha`, typy
+  `KptSignalGridOptions`, `KptSignalGridFrame`, `KptSignalGridCell`
+- **Wstęga** — `resolveWave`, `waveIntensity`, `waveRamp`, `waveBuffer`, typy `KptWaveOptions`,
+  `KptWaveSettings`, `KptWaveBuffer`, `KptWaveHarmonic`
+- **Barwy** — `mixOklch`, `shiftHue`, `readCssColor`, `parseHexColor`, `toHexColor`,
+  `srgbToOklab`, `oklabToSrgb`, typy `KptRgb`, `KptOklab`
+- **Losowanie** — `kptHash01`
+- **Stałe** — `KPT_SIGNAL_GRID_*`, `KPT_WAVE_*`, `KPT_BACKDROP_MAX_DPR`, `KPT_BACKDROP_MAX_STEP`
+- **Model** — typy `KptBackdropAnchor`, `KptBackdropEffect`
+
+Pełny opis: [`llms.txt`](https://ui.konce.pt/llms/backdrop/llms.txt) (EN)
+i [`llms-pl.txt`](https://ui.konce.pt/llms/backdrop/llms-pl.txt) (PL).
+
+## Testy
+
+```bash
+pnpm --filter @konce-pt/backdrop exec node --test "src/**/*.test.ts"
+```
+
+## Licencja
+
+MIT © [konce.pt](https://konce.pt)

package/dist/color.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Barwy wstęgi. Mieszanie idzie po współrzędnych biegunowych OKLab (czyli OKLCH), nie po
+ * składowych sRGB ani nawet nie po prostokątnym OKLab.
+ *
+ * Interpolacja sRGB prowadzi mieszankę przez błoto, bo miesza wartości po gammie. Prostokątny
+ * OKLab naprawia jasność, ale dla odcieni leżących naprzeciwko siebie — a takie są w rampie
+ * wstęgi — i tak przecina oś achromatyczną: w połowie przejścia z niebieskiego w żółty zostaje
+ * szarość dokładnie tam, gdzie wstęga świeci najmocniej. Dopiero rozbicie na jasność, nasycenie
+ * i kąt odcienia pozwala obejść koło dookoła z zachowanym nasyceniem.
+ *
+ * Konwersje wg modelu OKLab Björna Ottossona.
+ */
+/** Kolor w sRGB, składowe 0–255. */
+export interface KptRgb {
+    r: number;
+    g: number;
+    b: number;
+}
+/** Kolor w OKLab: jasność `l` oraz para składowych chromatycznych. */
+export interface KptOklab {
+    l: number;
+    a: number;
+    b: number;
+}
+/**
+ * Zapis heksadecymalny (`#rgb` albo `#rrggbb`, z krzyżykiem lub bez) na składowe.
+ * Zwraca `null` na wszystkim innym — kolor przychodzi z wejścia komponentu albo z konfiguratora,
+ * więc śmieci są normalnym przypadkiem, a nie wyjątkiem.
+ */
+export declare function parseHexColor(hex: string): KptRgb | null;
+/**
+ * Dowolny zapis koloru CSS na składowe — także `oklch()`, `color-mix()` czy nazwa własna.
+ *
+ * Tokeny biblioteki są zapisane w OKLCH, a barwy wstęgi trzeba wymieszać, nie tylko podać dalej.
+ * Zamiast pisać własny parser każdej składni CSS, malujemy kolor na canvasie 1×1 i odczytujemy
+ * piksel: przeglądarka rozumie każdy zapis, który sama akceptuje, i nigdy nie rozejdzie się
+ * z tym, co widać na stronie.
+ *
+ * Zapis nieprawidłowy daje `null`, tak samo jak środowisko bez DOM. `fillStyle` odrzuca taką
+ * wartość po cichu, zostawiając poprzednią, więc sam odczyt piksela nie odróżniłby śmiecia od
+ * legalnej czerni — stąd dwa różne wartowniki: przy wartości nieprawidłowej każdy z nich zostaje
+ * na swoim miejscu i oba przebiegi dają inny wynik. Getter zwraca kolor już zserializowany,
+ * więc bramka nie potrzebuje odczytu piksela.
+ */
+export declare function readCssColor(value: string): KptRgb | null;
+/** Składowe na `#rrggbb`. */
+export declare function toHexColor(rgb: KptRgb): string;
+export declare function srgbToOklab(rgb: KptRgb): KptOklab;
+export declare function oklabToSrgb(lab: KptOklab): KptRgb;
+/**
+ * Obrót odcienia o zadany kąt (stopnie) przy zachowanej jasności i nasyceniu.
+ *
+ * Stąd biorą się domyślne barwy wstęgi: paleta biblioteki jest neutralna, więc zamiast sięgać
+ * po tokeny statusowe (`info`, `success`) do celów dekoracyjnych, dwie towarzyszące barwy
+ * wyprowadzamy z koloru wiodącego. Wstęga zostaje w kolorach aplikacji niezależnie od motywu.
+ */
+export declare function shiftHue(rgb: KptRgb, degrees: number): KptRgb;
+/**
+ * Kolor na zamkniętej rampie `colors` w miejscu `position`.
+ *
+ * Rampa jest cykliczna: ostatni przystanek wraca do pierwszego, bo barwy przesuwają się wzdłuż
+ * wstęgi bez końca i szew w środku kadru byłby widoczny. `position` poza zakresem 0–1 zawija się,
+ * więc wywołujący nie musi pilnować rosnącego czasu.
+ *
+ * Odcień idzie krótszym łukiem koła. Przystanek bez nasycenia przejmuje odcień sąsiada — inaczej
+ * przejście do szarości i z powrotem szarpnęłoby barwą, bo `atan2` na zerowym nasyceniu zwraca
+ * kąt przypadkowy.
+ */
+export declare function mixOklch(colors: readonly KptRgb[], position: number): KptRgb;
+/**
+ * Jasność przeniesiona na powierzchnię bieżącego motywu z zachowaniem odległości od niej.
+ *
+ * Barwa zapisana na biel odsuwa się od niej o `d`; na ciemnej powierzchni ma się odsunąć o to samo
+ * `d`, tyle że w drugą stronę — bo tam właśnie jest miejsce. Stąd czerń na bieli staje się bielą
+ * na ciemnym tle, a biel staje się dokładnie powierzchnią. Barwa w połowie skali zostaje mniej
+ * więcej tam, gdzie była, i dalej odcina się od tła.
+ *
+ * Na jasnej powierzchni wychodzi tożsamość: `1 - (1 - L)` to `L`.
+ */
+export declare function adaptLightness(lightness: number, surface: number): number;
+/**
+ * Barwa przeniesiona na zadaną powierzchnię. Rusza wyłącznie jasność — odcień i nasycenie zostają,
+ * więc barwa marki nie zmienia się w inną barwę, tylko dobiera jasność do tła.
+ */
+export declare function adaptToSurface(rgb: KptRgb, surface: KptRgb): KptRgb;
+/**
+ * Jasność względna wg WCAG (0 = czerń, 1 = biel).
+ *
+ * To nie to samo co jasność OKLab: OKLab opisuje, jak jasno barwa *wygląda*, a ta liczba mówi,
+ * ile z niej wychodzi światła — i tylko na niej stoi rachunek kontrastu, którym rozstrzygamy,
+ * czy na danym tle czytelniejszy jest napis ciemny czy jasny.
+ */
+export declare function relativeLuminance(rgb: KptRgb): number;
+/**
+ * Czy na tej powierzchni czytelniejsza jest treść ciemna.
+ *
+ * Sekcja z własnym tłem przestaje być powierzchnią strony, więc `--kpt-color-on-surface` opisuje
+ * już nie to tło, tylko sąsiada. Bez tego rachunku treść w sekcji z ciemnym tłem w motywie jasnym
+ * wychodzi czarna na czarnym.
+ */
+export declare function prefersDarkContent(surface: KptRgb): boolean;

package/dist/color.js

@@ -0,0 +1,228 @@
+/**
+ * Barwy wstęgi. Mieszanie idzie po współrzędnych biegunowych OKLab (czyli OKLCH), nie po
+ * składowych sRGB ani nawet nie po prostokątnym OKLab.
+ *
+ * Interpolacja sRGB prowadzi mieszankę przez błoto, bo miesza wartości po gammie. Prostokątny
+ * OKLab naprawia jasność, ale dla odcieni leżących naprzeciwko siebie — a takie są w rampie
+ * wstęgi — i tak przecina oś achromatyczną: w połowie przejścia z niebieskiego w żółty zostaje
+ * szarość dokładnie tam, gdzie wstęga świeci najmocniej. Dopiero rozbicie na jasność, nasycenie
+ * i kąt odcienia pozwala obejść koło dookoła z zachowanym nasyceniem.
+ *
+ * Konwersje wg modelu OKLab Björna Ottossona.
+ */
+const TAU = Math.PI * 2;
+const clamp255 = (value) => (value < 0 ? 0 : value > 255 ? 255 : Math.round(value));
+/** Gamma sRGB → liniowo. */
+const toLinear = (channel) => {
+    const value = channel / 255;
+    return value <= 0.04045 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4;
+};
+/** Liniowo → gamma sRGB. */
+const toGamma = (value) => {
+    const encoded = value <= 0.0031308 ? 12.92 * value : 1.055 * value ** (1 / 2.4) - 0.055;
+    return clamp255(encoded * 255);
+};
+/**
+ * Zapis heksadecymalny (`#rgb` albo `#rrggbb`, z krzyżykiem lub bez) na składowe.
+ * Zwraca `null` na wszystkim innym — kolor przychodzi z wejścia komponentu albo z konfiguratora,
+ * więc śmieci są normalnym przypadkiem, a nie wyjątkiem.
+ */
+export function parseHexColor(hex) {
+    const value = hex.trim().replace(/^#/, '');
+    const full = value.length === 3 ? value.replace(/./g, (char) => char + char) : value;
+    if (!/^[0-9a-f]{6}$/i.test(full))
+        return null;
+    return {
+        r: Number.parseInt(full.slice(0, 2), 16),
+        g: Number.parseInt(full.slice(2, 4), 16),
+        b: Number.parseInt(full.slice(4, 6), 16),
+    };
+}
+/** Leniwy kontekst 1×1 — służy wyłącznie do pytania przeglądarki o znaczenie zapisu koloru. */
+let probe;
+/**
+ * Dowolny zapis koloru CSS na składowe — także `oklch()`, `color-mix()` czy nazwa własna.
+ *
+ * Tokeny biblioteki są zapisane w OKLCH, a barwy wstęgi trzeba wymieszać, nie tylko podać dalej.
+ * Zamiast pisać własny parser każdej składni CSS, malujemy kolor na canvasie 1×1 i odczytujemy
+ * piksel: przeglądarka rozumie każdy zapis, który sama akceptuje, i nigdy nie rozejdzie się
+ * z tym, co widać na stronie.
+ *
+ * Zapis nieprawidłowy daje `null`, tak samo jak środowisko bez DOM. `fillStyle` odrzuca taką
+ * wartość po cichu, zostawiając poprzednią, więc sam odczyt piksela nie odróżniłby śmiecia od
+ * legalnej czerni — stąd dwa różne wartowniki: przy wartości nieprawidłowej każdy z nich zostaje
+ * na swoim miejscu i oba przebiegi dają inny wynik. Getter zwraca kolor już zserializowany,
+ * więc bramka nie potrzebuje odczytu piksela.
+ */
+export function readCssColor(value) {
+    const direct = parseHexColor(value);
+    if (direct)
+        return direct;
+    if (typeof document === 'undefined')
+        return null;
+    if (probe === undefined) {
+        const canvas = document.createElement('canvas');
+        canvas.width = 1;
+        canvas.height = 1;
+        probe = canvas.getContext('2d', { willReadFrequently: true });
+    }
+    if (!probe)
+        return null;
+    probe.fillStyle = '#000000';
+    probe.fillStyle = value;
+    const first = probe.fillStyle;
+    probe.fillStyle = '#ffffff';
+    probe.fillStyle = value;
+    if (probe.fillStyle !== first)
+        return null;
+    // Sonda musi zaczynać od przezroczystości: barwa z kanałem alfa nałożyłaby się na poprzedni
+    // odczyt i wyszłaby mieszanka dwóch niezwiązanych ze sobą wywołań.
+    probe.clearRect(0, 0, 1, 1);
+    probe.fillRect(0, 0, 1, 1);
+    const [r, g, b] = probe.getImageData(0, 0, 1, 1).data;
+    return { r, g, b };
+}
+/** Składowe na `#rrggbb`. */
+export function toHexColor(rgb) {
+    const part = (value) => clamp255(value).toString(16).padStart(2, '0');
+    return `#${part(rgb.r)}${part(rgb.g)}${part(rgb.b)}`;
+}
+export function srgbToOklab(rgb) {
+    const r = toLinear(rgb.r);
+    const g = toLinear(rgb.g);
+    const b = toLinear(rgb.b);
+    const l = Math.cbrt(0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b);
+    const m = Math.cbrt(0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b);
+    const s = Math.cbrt(0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b);
+    return {
+        l: 0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s,
+        a: 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s,
+        b: 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s,
+    };
+}
+export function oklabToSrgb(lab) {
+    const l = (lab.l + 0.3963377774 * lab.a + 0.2158037573 * lab.b) ** 3;
+    const m = (lab.l - 0.1055613458 * lab.a - 0.0638541728 * lab.b) ** 3;
+    const s = (lab.l - 0.0894841775 * lab.a - 1.291485548 * lab.b) ** 3;
+    return {
+        r: toGamma(4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s),
+        g: toGamma(-1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s),
+        b: toGamma(-0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s),
+    };
+}
+/**
+ * Obrót odcienia o zadany kąt (stopnie) przy zachowanej jasności i nasyceniu.
+ *
+ * Stąd biorą się domyślne barwy wstęgi: paleta biblioteki jest neutralna, więc zamiast sięgać
+ * po tokeny statusowe (`info`, `success`) do celów dekoracyjnych, dwie towarzyszące barwy
+ * wyprowadzamy z koloru wiodącego. Wstęga zostaje w kolorach aplikacji niezależnie od motywu.
+ */
+export function shiftHue(rgb, degrees) {
+    const lab = srgbToOklab(rgb);
+    const chroma = Math.hypot(lab.a, lab.b);
+    const hue = Math.atan2(lab.b, lab.a) + (degrees / 360) * TAU;
+    return oklabToSrgb({ l: lab.l, a: Math.cos(hue) * chroma, b: Math.sin(hue) * chroma });
+}
+/** Poniżej tego nasycenia odcień przestaje cokolwiek znaczyć — szarość nie ma kąta. */
+const ACHROMATIC = 1e-4;
+/**
+ * Kolor na zamkniętej rampie `colors` w miejscu `position`.
+ *
+ * Rampa jest cykliczna: ostatni przystanek wraca do pierwszego, bo barwy przesuwają się wzdłuż
+ * wstęgi bez końca i szew w środku kadru byłby widoczny. `position` poza zakresem 0–1 zawija się,
+ * więc wywołujący nie musi pilnować rosnącego czasu.
+ *
+ * Odcień idzie krótszym łukiem koła. Przystanek bez nasycenia przejmuje odcień sąsiada — inaczej
+ * przejście do szarości i z powrotem szarpnęłoby barwą, bo `atan2` na zerowym nasyceniu zwraca
+ * kąt przypadkowy.
+ */
+export function mixOklch(colors, position) {
+    if (colors.length === 0)
+        return { r: 0, g: 0, b: 0 };
+    if (colors.length === 1)
+        return colors[0];
+    const wrapped = position - Math.floor(position);
+    const scaled = wrapped * colors.length;
+    const index = Math.min(Math.floor(scaled), colors.length - 1);
+    const blend = scaled - index;
+    const from = srgbToOklab(colors[index]);
+    const to = srgbToOklab(colors[(index + 1) % colors.length]);
+    const fromChroma = Math.hypot(from.a, from.b);
+    const toChroma = Math.hypot(to.a, to.b);
+    const chroma = fromChroma + (toChroma - fromChroma) * blend;
+    let hue;
+    if (fromChroma < ACHROMATIC && toChroma < ACHROMATIC) {
+        hue = 0;
+    }
+    else if (fromChroma < ACHROMATIC) {
+        hue = Math.atan2(to.b, to.a);
+    }
+    else if (toChroma < ACHROMATIC) {
+        hue = Math.atan2(from.b, from.a);
+    }
+    else {
+        const start = Math.atan2(from.b, from.a);
+        const end = Math.atan2(to.b, to.a);
+        // Krótszy łuk: różnicę sprowadzamy do (-π, π], zamiast iść dookoła przez pół koła.
+        const delta = ((end - start + Math.PI * 3) % TAU) - Math.PI;
+        hue = start + delta * blend;
+    }
+    return oklabToSrgb({
+        l: from.l + (to.l - from.l) * blend,
+        a: Math.cos(hue) * chroma,
+        b: Math.sin(hue) * chroma,
+    });
+}
+/**
+ * Jasność powierzchni, względem której zapisano barwę. Biblioteka trzyma motyw jasny w `:root`,
+ * a ciemny jako nadpisanie, więc wartość wpisana do szablonu jest z założenia dobrana do jasnego —
+ * i to jest jedyne założenie, jakie robi adaptacja.
+ */
+const REFERENCE_SURFACE = 1;
+/** Powyżej tej jasności powierzchnię uznajemy za jasną, poniżej za ciemną. */
+const SURFACE_MIDPOINT = 0.5;
+const clamp01 = (value) => (value < 0 ? 0 : value > 1 ? 1 : value);
+/**
+ * Jasność przeniesiona na powierzchnię bieżącego motywu z zachowaniem odległości od niej.
+ *
+ * Barwa zapisana na biel odsuwa się od niej o `d`; na ciemnej powierzchni ma się odsunąć o to samo
+ * `d`, tyle że w drugą stronę — bo tam właśnie jest miejsce. Stąd czerń na bieli staje się bielą
+ * na ciemnym tle, a biel staje się dokładnie powierzchnią. Barwa w połowie skali zostaje mniej
+ * więcej tam, gdzie była, i dalej odcina się od tła.
+ *
+ * Na jasnej powierzchni wychodzi tożsamość: `1 - (1 - L)` to `L`.
+ */
+export function adaptLightness(lightness, surface) {
+    const distance = Math.abs(REFERENCE_SURFACE - lightness);
+    return clamp01(surface > SURFACE_MIDPOINT ? REFERENCE_SURFACE - distance : surface + distance);
+}
+/**
+ * Barwa przeniesiona na zadaną powierzchnię. Rusza wyłącznie jasność — odcień i nasycenie zostają,
+ * więc barwa marki nie zmienia się w inną barwę, tylko dobiera jasność do tła.
+ */
+export function adaptToSurface(rgb, surface) {
+    const lab = srgbToOklab(rgb);
+    return oklabToSrgb({ ...lab, l: adaptLightness(lab.l, srgbToOklab(surface).l) });
+}
+/**
+ * Jasność względna wg WCAG (0 = czerń, 1 = biel).
+ *
+ * To nie to samo co jasność OKLab: OKLab opisuje, jak jasno barwa *wygląda*, a ta liczba mówi,
+ * ile z niej wychodzi światła — i tylko na niej stoi rachunek kontrastu, którym rozstrzygamy,
+ * czy na danym tle czytelniejszy jest napis ciemny czy jasny.
+ */
+export function relativeLuminance(rgb) {
+    return 0.2126 * toLinear(rgb.r) + 0.7152 * toLinear(rgb.g) + 0.0722 * toLinear(rgb.b);
+}
+/** Próg WCAG na wybór treści ciemnej albo jasnej — powyżej niego ciemna wygrywa kontrastem. */
+const CONTENT_THRESHOLD = 0.179;
+/**
+ * Czy na tej powierzchni czytelniejsza jest treść ciemna.
+ *
+ * Sekcja z własnym tłem przestaje być powierzchnią strony, więc `--kpt-color-on-surface` opisuje
+ * już nie to tło, tylko sąsiada. Bez tego rachunku treść w sekcji z ciemnym tłem w motywie jasnym
+ * wychodzi czarna na czarnym.
+ */
+export function prefersDarkContent(surface) {
+    return relativeLuminance(surface) > CONTENT_THRESHOLD;
+}

package/dist/hash.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Deterministyczna liczba 0–1 z pary współrzędnych i ziarna.
+ *
+ * Siatka nie może trzymać stanu per komórka między klatkami — przy zmianie rozmiaru komórki
+ * wędrują, a tablica `Math.random()` rozsypałaby cały obraz. Zamiast tego każda komórka wylicza
+ * swoje losowania z własnej pozycji: ta sama kolumna i wiersz zawsze dają ten sam wynik, więc
+ * po zmianie rozmiaru układ pozostaje sobą, a nie mruga od nowa.
+ *
+ * Miks jest wariantem lawiny z `Math.imul` — tanio i z porządnym rozrzutem na sąsiednich
+ * współrzędnych, gdzie zwykłe mnożenie zostawiałoby widoczne pasy.
+ */
+export declare function kptHash01(x: number, y: number, seed?: number): number;

package/dist/hash.js

@@ -0,0 +1,19 @@
+/**
+ * Deterministyczna liczba 0–1 z pary współrzędnych i ziarna.
+ *
+ * Siatka nie może trzymać stanu per komórka między klatkami — przy zmianie rozmiaru komórki
+ * wędrują, a tablica `Math.random()` rozsypałaby cały obraz. Zamiast tego każda komórka wylicza
+ * swoje losowania z własnej pozycji: ta sama kolumna i wiersz zawsze dają ten sam wynik, więc
+ * po zmianie rozmiaru układ pozostaje sobą, a nie mruga od nowa.
+ *
+ * Miks jest wariantem lawiny z `Math.imul` — tanio i z porządnym rozrzutem na sąsiednich
+ * współrzędnych, gdzie zwykłe mnożenie zostawiałoby widoczne pasy.
+ */
+export function kptHash01(x, y, seed = 0) {
+    let h = Math.imul(x | 0, 0x1f1f_1f1f) ^ Math.imul(y | 0, 0x27d4_eb2f) ^ Math.imul(seed | 0, 0x1656_67b1);
+    h = Math.imul(h ^ (h >>> 15), 0x2545_f491);
+    h ^= h >>> 13;
+    h = Math.imul(h, 0x27d4_eb2d);
+    h ^= h >>> 16;
+    return (h >>> 0) / 4_294_967_296;
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export type { KptBackdropAnchor, KptBackdropEffect, KptSignalGridAlphaOptions, KptSignalGridCell, KptSignalGridFrame, KptSignalGridOptions, KptWaveHarmonic, KptWaveOptions, KptWaveSettings, } from './types.ts';
+export { buildSignalGrid, signalGridAlpha, signalGridDensity, KPT_SIGNAL_GRID_CELL, KPT_SIGNAL_GRID_DENSITY, KPT_SIGNAL_GRID_FALLOFF, KPT_SIGNAL_GRID_FLOOR, KPT_SIGNAL_GRID_GAP, KPT_SIGNAL_GRID_RATE, } from './signal-grid.ts';
+export { resolveWave, waveBuffer, waveIntensity, waveRamp, KPT_WAVE_AMPLITUDE, KPT_WAVE_BAND, KPT_WAVE_DRIFT, KPT_WAVE_MIN_SIDE, KPT_WAVE_RESOLUTION, KPT_WAVE_ROTATION, KPT_WAVE_SOFTNESS, KPT_WAVE_SPREAD, } from './wave.ts';
+export type { KptWaveBuffer } from './wave.ts';
+export { adaptLightness, adaptToSurface, mixOklch, oklabToSrgb, parseHexColor, prefersDarkContent, relativeLuminance, readCssColor, shiftHue, srgbToOklab, toHexColor, } from './color.ts';
+export type { KptOklab, KptRgb } from './color.ts';
+export { createBackdropRenderer, createSignalGridRenderer, adaptBackdropValue, createWaveRenderer, observeBackdropTheme, readBackdropInk, readBackdropLead, readBackdropSurface, resolveBackdropColors, resolveCssValue, KPT_BACKDROP_MAX_DPR, KPT_BACKDROP_MAX_STEP, KPT_BACKDROP_RAMP_SPREAD, } from './renderer.ts';
+export type { KptBackdropColors, KptBackdropInk, KptBackdropRenderer, KptBackdropRenderOptions } from './renderer.ts';
+export { kptHash01 } from './hash.ts';

package/dist/index.js

@@ -0,0 +1,5 @@
+export { buildSignalGrid, signalGridAlpha, signalGridDensity, KPT_SIGNAL_GRID_CELL, KPT_SIGNAL_GRID_DENSITY, KPT_SIGNAL_GRID_FALLOFF, KPT_SIGNAL_GRID_FLOOR, KPT_SIGNAL_GRID_GAP, KPT_SIGNAL_GRID_RATE, } from "./signal-grid.js";
+export { resolveWave, waveBuffer, waveIntensity, waveRamp, KPT_WAVE_AMPLITUDE, KPT_WAVE_BAND, KPT_WAVE_DRIFT, KPT_WAVE_MIN_SIDE, KPT_WAVE_RESOLUTION, KPT_WAVE_ROTATION, KPT_WAVE_SOFTNESS, KPT_WAVE_SPREAD, } from "./wave.js";
+export { adaptLightness, adaptToSurface, mixOklch, oklabToSrgb, parseHexColor, prefersDarkContent, relativeLuminance, readCssColor, shiftHue, srgbToOklab, toHexColor, } from "./color.js";
+export { createBackdropRenderer, createSignalGridRenderer, adaptBackdropValue, createWaveRenderer, observeBackdropTheme, readBackdropInk, readBackdropLead, readBackdropSurface, resolveBackdropColors, resolveCssValue, KPT_BACKDROP_MAX_DPR, KPT_BACKDROP_MAX_STEP, KPT_BACKDROP_RAMP_SPREAD, } from "./renderer.js";
+export { kptHash01 } from "./hash.js";

package/dist/renderer.d.ts

@@ -0,0 +1,176 @@
+/**
+ * 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 type { KptRgb } from './color.ts';
+import type { KptBackdropAnchor, KptBackdropEffect } from './types.ts';
+/** Gęstość pikseli powyżej dwóch nic nie wnosi przy tych efektach, a kosztuje kwadratowo. */
+export declare 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 declare const KPT_BACKDROP_MAX_STEP = 100;
+/** O tyle stopni rozchodzą się domyślne barwy wstęgi względem koloru wiodącego. */
+export declare const KPT_BACKDROP_RAMP_SPREAD = 28;
+/**
+ * Renderer jednego efektu. Żyje tyle, co zestaw ustawień — zmiana wejść buduje nowy,
+ * zamiast doklejać do istniejącego ścieżki „co się zmieniło".
+ */
+export interface KptBackdropRenderer {
+    /** Nowy rozmiar obszaru w pikselach CSS. */
+    resize(width: number, height: number): void;
+    /** Jedna klatka; `time` w sekundach od startu animacji. */
+    draw(context: CanvasRenderingContext2D, time: number): void;
+    /** Zwalnia bufory. Po tym renderer już nie rysuje. */
+    dispose(): void;
+}
+/** Ustawienia renderera — płaskie, tak jak wejścia komponentu. */
+export interface KptBackdropRenderOptions {
+    effect?: KptBackdropEffect;
+    /** signal-grid: kolor kwadratów, dowolny zapis CSS. */
+    color?: string;
+    anchor?: KptBackdropAnchor;
+    cell?: number;
+    gap?: number;
+    density?: number;
+    falloff?: number;
+    /**
+     * wave: rampa barw; zapis heksadecymalny, bo barwy trzeba wymieszać, nie tylko podać dalej.
+     * Zapis CSS zna wyłącznie `resolveBackdropColors` i to on sprowadza rampę do tej postaci.
+     */
+    colors?: readonly string[];
+    rotation?: number;
+    band?: number;
+    amplitude?: number;
+    seed?: number;
+}
+/** Kolory gotowe do podania rendererowi. */
+export interface KptBackdropColors {
+    /** Kolor wiodący — dowolny zapis CSS, tak jak przyszedł. */
+    color: string;
+    /** Rampa wstęgi w zapisie heksadecymalnym. */
+    colors: readonly string[];
+    /** Wpisy `colors`, których przeglądarka nie uznała za kolor — do ostrzeżenia w buildzie dev. */
+    invalid: readonly string[];
+}
+/**
+ * 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 declare function resolveCssValue(scope: HTMLElement, value: string): string;
+/**
+ * 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 declare function readBackdropLead(scope: HTMLElement, color: string): string;
+/** Powierzchnia bieżącego motywu — punkt odniesienia adaptacji. */
+export declare function readBackdropSurface(scope: HTMLElement): KptRgb | null;
+/**
+ * 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 declare function adaptBackdropValue(value: string, surface: KptRgb | null): string;
+/** Czym sekcja pisze po swoim tle. */
+export interface KptBackdropInk {
+    /**
+     * Jasność tła sekcji: `light` znaczy jasne tło i ciemną treść. Puste znaczy „sekcja nie ma
+     * własnego tła" i wtedy nie ma czego ogłaszać.
+     */
+    tone: '' | 'light' | 'dark';
+    /** Kolor treści dobrany do tego tła; pusty, gdy nie ma własnego tła. */
+    color: string;
+}
+/**
+ * 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 declare function readBackdropInk(scope: HTMLElement, background: string): KptBackdropInk;
+/**
+ * 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 declare function observeBackdropTheme(host: HTMLElement, onChange: () => void): () => void;
+/**
+ * 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 declare function resolveBackdropColors(scope: HTMLElement, color: string, colors: readonly string[], adaptive?: boolean): KptBackdropColors;
+/**
+ * Drobna siatka migoczących kwadratów. Cała matematyka siedzi w `signal-grid.ts`;
+ * tutaj zostaje pętla po komórkach.
+ */
+export declare function createSignalGridRenderer(options: KptBackdropRenderOptions): KptBackdropRenderer;
+/**
+ * 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 declare function createWaveRenderer(options: KptBackdropRenderOptions): KptBackdropRenderer;
+/** Renderer wskazanego efektu. Nieznany efekt nie rysuje niczego, zamiast wywracać klatkę. */
+export declare function createBackdropRenderer(options: KptBackdropRenderOptions): KptBackdropRenderer;