@konce-pt/motion 0.0.0-stage → 0.15.0

package/dist/loader.d.ts

@@ -0,0 +1,177 @@
+/**
+ * Rdzeń `kpt-loader`: geometria i fizyka wariantów jako czyste funkcje czasu.
+ *
+ * Każda klatka loadera to liczby - promień orbity, pozycja kuli nad ziemią, napis ścieżki SVG.
+ * Liczymy je tutaj, bez DOM-u, więc da się je przetestować; warstwa `loader-dom.ts` tylko je
+ * nakłada na elementy. Współrzędne są w jednostkach rysunku (`LOADER_VIEWBOX`), a nie w pikselach:
+ * SVG skaluje je do rozmiaru, który poda komponent.
+ */
+/** Warianty: ciecz, most z cieczy, kształty, pierścień, fala i skaczące bąbelki. */
+export type KptLoaderVariant = 'bubbles' | 'bridge' | 'shapes' | 'ring' | 'wave' | 'bounce';
+/** `loading` kręci pętlę, `success` i `error` grają wynik - loader przechodzi w znak zamiast znikać. */
+export type KptLoaderStatus = 'loading' | 'success' | 'error';
+export type KptLoaderResult = 'success' | 'error';
+/** Role motywu, które loader zamienia na tokeny `--kpt-color-*`. */
+export type KptLoaderRole = 'primary' | 'info' | 'success' | 'warning' | 'danger';
+/** Rola motywu albo dowolny kolor CSS (`oklch(...)`, `var(--brand)`). */
+export type KptLoaderColor = KptLoaderRole | (string & {});
+export declare const KPT_LOADER_VARIANTS: readonly KptLoaderVariant[];
+/** Domyślne barwy pętli - tyle, ile wariant ma elementów w różnych kolorach. */
+export declare const LOADER_PALETTE: Readonly<Record<KptLoaderVariant, readonly KptLoaderRole[]>>;
+/**
+ * Pole rysunku wariantu: `[x, y, szerokość, wysokość]`. Wspólna skala - 100 jednostek to `size`
+ * komponentu - więc warianty obok siebie mają ten sam rozmiar elementów, a nie to samo pudełko.
+ */
+export declare const LOADER_VIEWBOX: Readonly<Record<KptLoaderVariant, readonly [number, number, number, number]>>;
+/** Czas choreografii wyniku w ms - po nim komponent zgłasza `settled`. */
+export declare const LOADER_RESULT_MS: Readonly<Record<KptLoaderVariant, Readonly<Record<KptLoaderResult, number>>>>;
+/** Wynik w wersji z ograniczonym ruchem: loader gaśnie, znak pojawia się na miejscu. */
+export declare const LOADER_QUIET_MS = 400;
+export declare const clamp01: (x: number) => number;
+export declare const mix: (a: number, b: number, p: number) => number;
+export declare const easeIn: (q: number) => number;
+export declare const easeOut: (q: number) => number;
+export declare const easeInOut: (q: number) => number;
+/**
+ * `cubic-bezier()` z CSS jako funkcja postępu - te same krzywe co w przejściach biblioteki, ale
+ * liczone w klatce `rAF`. Newton z bisekcją jako siatką bezpieczeństwa (płaskie odcinki krzywej).
+ */
+export declare function cubicBezier(x1: number, y1: number, x2: number, y2: number): (q: number) => number;
+/** Krzywe ruchu loaderów: wyjście, wejście, przejście i cztery sprężyny o różnym odbiciu. */
+export declare const LOADER_EASE: {
+    readonly out: (q: number) => number;
+    readonly in: (q: number) => number;
+    readonly inOut: (q: number) => number;
+    readonly splash: (q: number) => number;
+    readonly snap: (q: number) => number;
+    readonly pop: (q: number) => number;
+    readonly wobble: (q: number) => number;
+};
+/**
+ * Wartość postępu sprowadzona do 0..1, jak w `kpt-progress` (`value`, `min`, `max`).
+ * `null` = postęp nieokreślony (brak wartości, `NaN` albo pusty zakres).
+ */
+export declare function loaderProgress(value: number | null | undefined, min?: number, max?: number): number | null;
+/** Rola motywu -> `var(--kpt-color-<rola>)`; każdy inny napis idzie bez zmian jako kolor CSS. */
+export declare function loaderColor(color: KptLoaderColor): string;
+/** Kolor znaku na tle barwy: kontrast roli albo powierzchnia, gdy kolor jest spoza ról. */
+export declare function loaderOnColor(color: KptLoaderColor): string;
+/** Delikatne tło w barwie: `-subtle` roli albo ten sam kolor rozcieńczony w powierzchni. */
+export declare function loaderSubtle(color: KptLoaderColor): string;
+/**
+ * Barwy elementów pętli: własne `colors` powtarzane po kolei do liczby elementów wariantu,
+ * a bez nich - paleta wariantu. Zawsze tyle pozycji, ile wariant potrzebuje.
+ */
+export declare function loaderPalette(variant: KptLoaderVariant, colors?: readonly KptLoaderColor[] | null): string[];
+export declare const LOADER_MARKS: {
+    readonly check: readonly ["M5 12l5 5l10 -10"];
+    readonly x: readonly ["M18 6l-12 12", "M6 6l12 12"];
+    readonly alert: readonly ["M12 7v6", "M12 17v.01"];
+};
+export type KptLoaderMark = keyof typeof LOADER_MARKS;
+/**
+ * Promień orbity kropel w pętli 2,8 s: rozprysk na sprężynie, chwila w rozstawieniu, zbiegnięcie
+ * i chwila w jednej kropli. Od 6 do 36 jednostek.
+ */
+export declare function bubblesOrbit(t: number): number;
+/** Prędkość kątowa (rad/s): im ciaśniej, tym szybciej - jak łyżwiarz przyciągający ręce. */
+export declare function bubblesSpin(radius: number): number;
+/** Kropla w pętli: wahadło przez rząd kropek, rozciągnięte w kierunku lotu. */
+export declare function bridgeTraveler(t: number): {
+    x: number;
+    sx: number;
+    sy: number;
+};
+/**
+ * Kropka rzędu przy przelatującej kropli: przyciągnięta ku niej i nabrzmiała, gdy kropla jest
+ * blisko (mostek cieczy robi filtr). `gather` 1 -> 0 zbiera rząd do środka przy wyniku.
+ */
+export declare function bridgeDot(home: number, x: number, gather?: number): {
+    x: number;
+    scale: number;
+};
+/** Kapsuła wyniku: znak 18 + odstęp + napis, z marginesem 17 z każdej strony. */
+export declare function bridgePillWidth(textWidth: number): number;
+export declare const SHAPE_SAMPLES = 120;
+/** Kształty pętli po kolei: ciastko, kwadrat, koniczyna, pięciokąt, pigułka, słońce, trójkąt. */
+export declare const LOADER_SHAPES: readonly (readonly number[])[];
+/** Kształt sukcesu (koło) i błędu (zaokrąglony kwadrat). */
+export declare const SHAPE_CIRCLE: readonly number[];
+export declare const SHAPE_SQUIRCLE: readonly number[];
+export declare function mixRadii(a: readonly number[], b: readonly number[], p: number): number[];
+/** Zamknięta ścieżka kształtu o promieniach `radii`, obrócona o `rotation` (rad) i przeskalowana. */
+export declare function shapePath(radii: readonly number[], rotation: number, scale: number): string;
+/**
+ * Klatka pętli kształtów: co 0,8 s morf do następnego kształtu na sprężynie i obrót o ćwierć
+ * obrotu z dociągnięciem, a pod spodem stały, wolny obrót i oddech skali.
+ */
+export declare function shapesFrame(t: number): {
+    radii: number[];
+    rotation: number;
+    scale: number;
+};
+export declare const RING_RADIUS = 44;
+/**
+ * Łuk pierścienia od `a0` do `a1` (stopnie, 0 = godzina 3) z falą o amplitudzie `amp`.
+ * Fala gaśnie przy końcach łuku (obwiednia 10 stopni), więc końce są gładkie. Pusty napis,
+ * gdy łuk jest krótszy niż pół stopnia.
+ */
+export declare function ringArcPath(a0: number, a1: number, amp: number, phase: number, radius?: number): string;
+/**
+ * Łuk nieokreślony: głowa i ogon gonią się co 1,5 s (głowa rusza pierwsza, ogon dogania),
+ * a całość obraca się stale. Kąty w stopniach, start u góry.
+ */
+export declare function ringIdleArc(t: number): {
+    a0: number;
+    a1: number;
+};
+/** Najbliższa "dwunasta" nie wcześniej niż `a0` - stąd łuk określony liczy postęp. */
+export declare function ringBase(a0: number): number;
+export declare const WAVE_WIDTH = 240;
+/** Odcinek fali od `x0` do `x1` (oś na y = 0), z obwiednią 8 jednostek przy końcach. */
+export declare function wavePath(x0: number, x1: number, amp: number, phase: number): string;
+/** Prosty odcinek toru; pusty, gdy krótszy niż jednostka. */
+export declare function flatPath(x0: number, x1: number): string;
+/** Odcinek nieokreślony: wjeżdża z lewej, rośnie i ucieka w prawo co 1,8 s (nieprzycięty do toru). */
+export declare function waveIdleSpan(t: number): {
+    x0: number;
+    x1: number;
+};
+/**
+ * Wynik fali w chwili `rt` (s od wyniku): sukces wygładza falę, błąd szarpie nią; potem odcinek
+ * kurczy się do kreski na środku, a kreska zgina się w ptaszek albo rozcina w krzyżyk.
+ * `mark` mówi, że rysujemy już znak (grubsza kreska).
+ */
+export declare function waveResultPath(kind: KptLoaderResult, rt: number, x0: number, x1: number, phase: number): {
+    d: string;
+    mark: boolean;
+};
+/** Poziom ziemi: na nim stoją kule i leżą ich cienie. */
+export declare const BOUNCE_GROUND = 34;
+/** Kula w chwili: przesunięcie, wysokość nad ziemią, spłaszczenie i mnożnik rozmiaru. */
+export interface KptBounceBall {
+    x: number;
+    h: number;
+    sx: number;
+    sy: number;
+    k: number;
+}
+/**
+ * Kula `index` w pętli: skok co 0,9 s z przesunięciem fazy 0,15 s. Przy ziemi spłaszcza się
+ * (do 7% okresu od lądowania), w locie wyciąga w pionie proporcjonalnie do prędkości.
+ */
+export declare function bounceIdle(t: number, index: number, x: number): KptBounceBall;
+/**
+ * Wynik kul w chwili `rt`: sukces to wspólny skok do środka, zlanie w jedną kulę i lądowanie
+ * z wygaszonym przysiadem; błąd - opadnięcie bez odbicia, kałuże bocznych kul spływają do
+ * środkowej, a ta nadmuchuje się w znak. `from` to pozycja kuli w chwili wyniku.
+ */
+export declare function bounceResult(kind: KptLoaderResult, rt: number, index: number, from: {
+    x: number;
+    h: number;
+}): KptBounceBall;
+/** Cień kuli: maleje z wysokością, rośnie ze spłaszczeniem; znika razem z kulą. */
+export declare function bounceShadow(ball: KptBounceBall): {
+    scale: number;
+    opacity: number;
+};

package/dist/loader.js

@@ -0,0 +1,400 @@
+import { springProgress } from "./spring.js";
+export const KPT_LOADER_VARIANTS = ['bubbles', 'bridge', 'shapes', 'ring', 'wave', 'bounce'];
+const ROLES = new Set(['primary', 'info', 'success', 'warning', 'danger']);
+/** Domyślne barwy pętli - tyle, ile wariant ma elementów w różnych kolorach. */
+export const LOADER_PALETTE = {
+    bubbles: ['primary', 'info', 'success', 'warning'],
+    bridge: ['primary', 'info'],
+    shapes: ['primary'],
+    ring: ['info'],
+    wave: ['primary'],
+    bounce: ['info', 'success', 'warning'],
+};
+/**
+ * Pole rysunku wariantu: `[x, y, szerokość, wysokość]`. Wspólna skala - 100 jednostek to `size`
+ * komponentu - więc warianty obok siebie mają ten sam rozmiar elementów, a nie to samo pudełko.
+ */
+export const LOADER_VIEWBOX = {
+    bubbles: [-64, -64, 128, 128],
+    bridge: [-100, -32, 200, 64],
+    shapes: [-66, -66, 132, 132],
+    ring: [-50, -50, 100, 100],
+    wave: [0, -24, 240, 48],
+    bounce: [-60, -48, 120, 92],
+};
+/** Czas choreografii wyniku w ms - po nim komponent zgłasza `settled`. */
+export const LOADER_RESULT_MS = {
+    bubbles: { success: 1700, error: 2000 },
+    bridge: { success: 1300, error: 1600 },
+    shapes: { success: 1500, error: 1700 },
+    ring: { success: 1400, error: 1500 },
+    wave: { success: 1500, error: 1600 },
+    bounce: { success: 1600, error: 1700 },
+};
+/** Wynik w wersji z ograniczonym ruchem: loader gaśnie, znak pojawia się na miejscu. */
+export const LOADER_QUIET_MS = 400;
+// -- liczby --
+export const clamp01 = (x) => (x < 0 ? 0 : x > 1 ? 1 : x);
+export const mix = (a, b, p) => a + (b - a) * p;
+export const easeIn = (q) => q * q * q;
+export const easeOut = (q) => 1 - Math.pow(1 - q, 3);
+export const easeInOut = (q) => (q < 0.5 ? 4 * q * q * q : 1 - Math.pow(-2 * q + 2, 3) / 2);
+/**
+ * `cubic-bezier()` z CSS jako funkcja postępu - te same krzywe co w przejściach biblioteki, ale
+ * liczone w klatce `rAF`. Newton z bisekcją jako siatką bezpieczeństwa (płaskie odcinki krzywej).
+ */
+export function cubicBezier(x1, y1, x2, y2) {
+    const cx = 3 * x1;
+    const bx = 3 * (x2 - x1) - cx;
+    const ax = 1 - cx - bx;
+    const cy = 3 * y1;
+    const by = 3 * (y2 - y1) - cy;
+    const ay = 1 - cy - by;
+    const sx = (u) => ((ax * u + bx) * u + cx) * u;
+    const sy = (u) => ((ay * u + by) * u + cy) * u;
+    const dx = (u) => (3 * ax * u + 2 * bx) * u + cx;
+    return (q) => {
+        if (q <= 0)
+            return 0;
+        if (q >= 1)
+            return 1;
+        let u = q;
+        for (let i = 0; i < 8; i++) {
+            const e = sx(u) - q;
+            if (Math.abs(e) < 1e-6)
+                return sy(u);
+            const d = dx(u);
+            if (Math.abs(d) < 1e-6)
+                break;
+            u -= e / d;
+        }
+        let lo = 0;
+        let hi = 1;
+        u = q;
+        for (let i = 0; i < 40 && Math.abs(sx(u) - q) > 1e-6; i++) {
+            if (sx(u) < q)
+                lo = u;
+            else
+                hi = u;
+            u = (lo + hi) / 2;
+        }
+        return sy(u);
+    };
+}
+/** Krzywe ruchu loaderów: wyjście, wejście, przejście i cztery sprężyny o różnym odbiciu. */
+export const LOADER_EASE = {
+    out: cubicBezier(0.2, 0, 0, 1),
+    in: cubicBezier(0.4, 0, 1, 1),
+    inOut: cubicBezier(0.65, 0, 0.35, 1),
+    splash: cubicBezier(0.15, 0.7, 0.3, 1),
+    snap: springProgress(0.32),
+    pop: springProgress(0.5),
+    wobble: springProgress(0.45),
+};
+/**
+ * Wartość postępu sprowadzona do 0..1, jak w `kpt-progress` (`value`, `min`, `max`).
+ * `null` = postęp nieokreślony (brak wartości, `NaN` albo pusty zakres).
+ */
+export function loaderProgress(value, min = 0, max = 100) {
+    if (value == null || !Number.isFinite(value) || !(max > min))
+        return null;
+    return clamp01((value - min) / (max - min));
+}
+// -- barwy --
+/** Rola motywu -> `var(--kpt-color-<rola>)`; każdy inny napis idzie bez zmian jako kolor CSS. */
+export function loaderColor(color) {
+    return ROLES.has(color) ? `var(--kpt-color-${color})` : color;
+}
+/** Kolor znaku na tle barwy: kontrast roli albo powierzchnia, gdy kolor jest spoza ról. */
+export function loaderOnColor(color) {
+    return ROLES.has(color) ? `var(--kpt-color-${color}-contrast)` : 'var(--kpt-color-surface)';
+}
+/** Delikatne tło w barwie: `-subtle` roli albo ten sam kolor rozcieńczony w powierzchni. */
+export function loaderSubtle(color) {
+    return ROLES.has(color)
+        ? `var(--kpt-color-${color}-subtle)`
+        : `color-mix(in oklch, ${color} 18%, var(--kpt-color-surface))`;
+}
+/**
+ * Barwy elementów pętli: własne `colors` powtarzane po kolei do liczby elementów wariantu,
+ * a bez nich - paleta wariantu. Zawsze tyle pozycji, ile wariant potrzebuje.
+ */
+export function loaderPalette(variant, colors) {
+    const base = LOADER_PALETTE[variant];
+    const own = colors?.filter((c) => c.trim() !== '') ?? [];
+    return base.map((role, i) => loaderColor(own.length ? own[i % own.length] : role));
+}
+// -- znaki wyniku (pole 24 x 24, środek w 12,12) --
+export const LOADER_MARKS = {
+    check: ['M5 12l5 5l10 -10'],
+    x: ['M18 6l-12 12', 'M6 6l12 12'],
+    alert: ['M12 7v6', 'M12 17v.01'],
+};
+// -- 1: bąbelki --
+/**
+ * Promień orbity kropel w pętli 2,8 s: rozprysk na sprężynie, chwila w rozstawieniu, zbiegnięcie
+ * i chwila w jednej kropli. Od 6 do 36 jednostek.
+ */
+export function bubblesOrbit(t) {
+    const ph = (t % 2.8) / 2.8;
+    let k;
+    if (ph < 0.1)
+        k = 0;
+    else if (ph < 0.42)
+        k = LOADER_EASE.pop((ph - 0.1) / 0.32);
+    else if (ph < 0.62)
+        k = 1;
+    else if (ph < 0.86)
+        k = 1 - easeIn((ph - 0.62) / 0.24);
+    else
+        k = 0;
+    return 6 + 30 * k;
+}
+/** Prędkość kątowa (rad/s): im ciaśniej, tym szybciej - jak łyżwiarz przyciągający ręce. */
+export function bubblesSpin(radius) {
+    return 1.4 + 4.2 * (1 - radius / 36);
+}
+// -- 2: płynny most --
+/** Kropla w pętli: wahadło przez rząd kropek, rozciągnięte w kierunku lotu. */
+export function bridgeTraveler(t) {
+    const x = 58 * Math.sin(t * 2.3);
+    const stretch = Math.min(0.35, Math.abs(58 * 2.3 * Math.cos(t * 2.3)) / 380);
+    return { x, sx: 1 + stretch, sy: 1 / (1 + stretch * 0.7) };
+}
+/**
+ * Kropka rzędu przy przelatującej kropli: przyciągnięta ku niej i nabrzmiała, gdy kropla jest
+ * blisko (mostek cieczy robi filtr). `gather` 1 -> 0 zbiera rząd do środka przy wyniku.
+ */
+export function bridgeDot(home, x, gather = 1) {
+    const dx = home * gather;
+    const near = Math.max(0, 1 - Math.abs(x - dx) / 34);
+    return { x: dx + (x - dx) * 0.18 * near, scale: 1 + 0.4 * near * gather };
+}
+/** Kapsuła wyniku: znak 18 + odstęp + napis, z marginesem 17 z każdej strony. */
+export function bridgePillWidth(textWidth) {
+    return 18 + 6.4 + Math.max(0, textWidth) + 34;
+}
+// -- 3: kształty --
+export const SHAPE_SAMPLES = 120;
+function sampleRadius(fn) {
+    return Array.from({ length: SHAPE_SAMPLES }, (_, j) => fn((j / SHAPE_SAMPLES) * Math.PI * 2));
+}
+/** Wielokąt foremny jako promień od kąta (bok przy `cos(m) = cos(pi/n)`). */
+function polygonRadius(n) {
+    const step = (2 * Math.PI) / n;
+    return (theta) => {
+        const m = (((theta % step) + step) % step) - step / 2;
+        return Math.cos(Math.PI / n) / Math.cos(m);
+    };
+}
+/** Wygładzenie promienia (okno trójkątne 5 próbek) - zaokrągla rogi wielokątów. */
+function smoothRadius(radii, passes) {
+    let a = radii;
+    for (let p = 0; p < passes; p++) {
+        a = a.map((_, j) => {
+            let s = 0;
+            for (let k = -2; k <= 2; k++)
+                s += a[(j + k + SHAPE_SAMPLES) % SHAPE_SAMPLES] * (3 - Math.abs(k));
+            return s / 9;
+        });
+    }
+    return a;
+}
+/** Promień o średniej 1 - wszystkie kształty mają to samo "pole", więc morf nie pompuje. */
+function normalizeRadius(radii) {
+    const mean = radii.reduce((x, y) => x + y, 0) / SHAPE_SAMPLES;
+    return radii.map((v) => v / mean);
+}
+/** Kształty pętli po kolei: ciastko, kwadrat, koniczyna, pięciokąt, pigułka, słońce, trójkąt. */
+export const LOADER_SHAPES = [
+    normalizeRadius(sampleRadius((th) => 1 + 0.085 * Math.cos(9 * th))),
+    normalizeRadius(smoothRadius(sampleRadius(polygonRadius(4)), 5)),
+    normalizeRadius(sampleRadius((th) => 1 + 0.16 * Math.cos(4 * th))),
+    normalizeRadius(smoothRadius(sampleRadius(polygonRadius(5)), 4)),
+    normalizeRadius(sampleRadius((th) => 1 / Math.sqrt(Math.pow(Math.cos(th) / 1.22, 2) + Math.pow(Math.sin(th) / 0.78, 2)))),
+    normalizeRadius(sampleRadius((th) => 1 + 0.07 * Math.cos(8 * th))),
+    normalizeRadius(smoothRadius(sampleRadius(polygonRadius(3)), 6)),
+];
+/** Kształt sukcesu (koło) i błędu (zaokrąglony kwadrat). */
+export const SHAPE_CIRCLE = sampleRadius(() => 1);
+export const SHAPE_SQUIRCLE = normalizeRadius(smoothRadius(sampleRadius(polygonRadius(4)), 3));
+export function mixRadii(a, b, p) {
+    return a.map((v, j) => v + (b[j] - v) * p);
+}
+/** Zamknięta ścieżka kształtu o promieniach `radii`, obrócona o `rotation` (rad) i przeskalowana. */
+export function shapePath(radii, rotation, scale) {
+    let d = '';
+    for (let j = 0; j < radii.length; j++) {
+        const th = (j / radii.length) * Math.PI * 2 + rotation;
+        d += `${j ? 'L' : 'M'}${(Math.cos(th) * radii[j] * scale).toFixed(2)} ${(Math.sin(th) * radii[j] * scale).toFixed(2)}`;
+    }
+    return d + 'Z';
+}
+/**
+ * Klatka pętli kształtów: co 0,8 s morf do następnego kształtu na sprężynie i obrót o ćwierć
+ * obrotu z dociągnięciem, a pod spodem stały, wolny obrót i oddech skali.
+ */
+export function shapesFrame(t) {
+    const seg = 0.8;
+    const k = Math.floor(t / seg);
+    const q = clamp01((t - k * seg) / seg / 0.68);
+    const n = LOADER_SHAPES.length;
+    return {
+        radii: mixRadii(LOADER_SHAPES[k % n], LOADER_SHAPES[(k + 1) % n], LOADER_EASE.pop(q)),
+        rotation: ((t * 45 + 90 * (k + LOADER_EASE.snap(q))) * Math.PI) / 180,
+        scale: 30 * (1 + 0.035 * Math.sin(t * 4.4)),
+    };
+}
+// -- 4: pierścień --
+export const RING_RADIUS = 44;
+/**
+ * Łuk pierścienia od `a0` do `a1` (stopnie, 0 = godzina 3) z falą o amplitudzie `amp`.
+ * Fala gaśnie przy końcach łuku (obwiednia 10 stopni), więc końce są gładkie. Pusty napis,
+ * gdy łuk jest krótszy niż pół stopnia.
+ */
+export function ringArcPath(a0, a1, amp, phase, radius = RING_RADIUS) {
+    if (a1 - a0 < 0.5)
+        return '';
+    const n = Math.max(2, Math.ceil((a1 - a0) / 3));
+    let d = '';
+    for (let i = 0; i <= n; i++) {
+        const a = a0 + ((a1 - a0) * i) / n;
+        const rad = (a * Math.PI) / 180;
+        const env = Math.min(1, (a - a0) / 10, (a1 - a) / 10);
+        const r = radius + amp * env * Math.sin(rad * 14 - phase);
+        d += `${i ? 'L' : 'M'}${(Math.cos(rad) * r).toFixed(2)} ${(Math.sin(rad) * r).toFixed(2)}`;
+    }
+    return d;
+}
+/**
+ * Łuk nieokreślony: głowa i ogon gonią się co 1,5 s (głowa rusza pierwsza, ogon dogania),
+ * a całość obraca się stale. Kąty w stopniach, start u góry.
+ */
+export function ringIdleArc(t) {
+    const period = 1.5;
+    const n = Math.floor(t / period);
+    const ph = (t - n * period) / period;
+    const head = t * 150 + 260 * (n + easeInOut(clamp01(ph / 0.55)));
+    const tail = t * 150 + 260 * (n + easeInOut(clamp01((ph - 0.45) / 0.55)));
+    return { a0: tail - 90, a1: head - 90 + 16 };
+}
+/** Najbliższa "dwunasta" nie wcześniej niż `a0` - stąd łuk określony liczy postęp. */
+export function ringBase(a0) {
+    return -90 + 360 * Math.ceil((a0 + 90) / 360);
+}
+// -- 6: fala --
+export const WAVE_WIDTH = 240;
+/** Odcinek fali od `x0` do `x1` (oś na y = 0), z obwiednią 8 jednostek przy końcach. */
+export function wavePath(x0, x1, amp, phase) {
+    if (x1 - x0 < 0.5)
+        return '';
+    const n = Math.max(2, Math.ceil((x1 - x0) / 2));
+    let d = '';
+    for (let i = 0; i <= n; i++) {
+        const x = x0 + ((x1 - x0) * i) / n;
+        const env = Math.min(1, (x - x0) / 8, (x1 - x) / 8);
+        d += `${i ? 'L' : 'M'}${x.toFixed(2)} ${(amp * env * Math.sin(x * 0.314 - phase)).toFixed(2)}`;
+    }
+    return d;
+}
+/** Prosty odcinek toru; pusty, gdy krótszy niż jednostka. */
+export function flatPath(x0, x1) {
+    return x1 - x0 > 1 ? `M${x0.toFixed(2)} 0L${x1.toFixed(2)} 0` : '';
+}
+/** Odcinek nieokreślony: wjeżdża z lewej, rośnie i ucieka w prawo co 1,8 s (nieprzycięty do toru). */
+export function waveIdleSpan(t) {
+    const c = (t % 1.8) / 1.8;
+    return {
+        x0: -30 + 300 * easeInOut(clamp01((c - 0.3) / 0.7)),
+        x1: -30 + 300 * easeInOut(clamp01(c / 0.7)),
+    };
+}
+/**
+ * Wynik fali w chwili `rt` (s od wyniku): sukces wygładza falę, błąd szarpie nią; potem odcinek
+ * kurczy się do kreski na środku, a kreska zgina się w ptaszek albo rozcina w krzyżyk.
+ * `mark` mówi, że rysujemy już znak (grubsza kreska).
+ */
+export function waveResultPath(kind, rt, x0, x1, phase) {
+    const ok = kind === 'success';
+    if (ok && rt < 0.3)
+        return { d: wavePath(x0, x1, 3 * (1 - easeOut(rt / 0.3)), phase), mark: false };
+    if (!ok && rt < 0.35) {
+        return { d: wavePath(x0, x1, 3 + 5 * Math.sin(rt * 90) * (1 - rt / 0.35), phase + 2 * Math.sin(rt * 53)), mark: false };
+    }
+    const shrinkAt = ok ? 0.3 : 0.35;
+    const bendAt = ok ? 0.7 : 0.75;
+    if (rt < bendAt) {
+        const p = easeInOut((rt - shrinkAt) / 0.4);
+        return { d: wavePath(mix(x0, 80, p), mix(x1, 160, p), ok ? 0 : 3 * (1 - p), phase), mark: false };
+    }
+    const p = LOADER_EASE.pop(clamp01((rt - bendAt) / 0.6));
+    const from = ok ? [[80, 0], [120, 0], [160, 0]] : [[80, 0], [120, 0], [120, 0], [160, 0]];
+    const to = ok ? [[102, 0], [114, 12], [140, -14]] : [[106, -14], [134, 14], [106, 14], [134, -14]];
+    const pt = from.map((f, i) => `${mix(f[0], to[i][0], p).toFixed(2)} ${mix(f[1], to[i][1], p).toFixed(2)}`);
+    return { d: ok ? `M${pt[0]}L${pt[1]}L${pt[2]}` : `M${pt[0]}L${pt[1]}M${pt[2]}L${pt[3]}`, mark: true };
+}
+// -- 8: skaczące bąbelki --
+/** Poziom ziemi: na nim stoją kule i leżą ich cienie. */
+export const BOUNCE_GROUND = 34;
+/**
+ * Kula `index` w pętli: skok co 0,9 s z przesunięciem fazy 0,15 s. Przy ziemi spłaszcza się
+ * (do 7% okresu od lądowania), w locie wyciąga w pionie proporcjonalnie do prędkości.
+ */
+export function bounceIdle(t, index, x) {
+    const period = 0.9;
+    let q = ((t - index * 0.15) / period) % 1;
+    if (q < 0)
+        q += 1;
+    const v = Math.abs(1 - 2 * q);
+    const c = Math.max(0, 1 - Math.min(q, 1 - q) / 0.07);
+    return {
+        x,
+        h: 48 * 4 * q * (1 - q),
+        sx: 1 + 0.38 * c - 0.1 * v * (1 - c),
+        sy: 1 - 0.32 * c + 0.14 * v * (1 - c),
+        k: 1,
+    };
+}
+/**
+ * Wynik kul w chwili `rt`: sukces to wspólny skok do środka, zlanie w jedną kulę i lądowanie
+ * z wygaszonym przysiadem; błąd - opadnięcie bez odbicia, kałuże bocznych kul spływają do
+ * środkowej, a ta nadmuchuje się w znak. `from` to pozycja kuli w chwili wyniku.
+ */
+export function bounceResult(kind, rt, index, from) {
+    if (kind === 'success') {
+        if (rt < 0.5) {
+            const p = rt / 0.5;
+            return { x: mix(from.x, 0, easeInOut(p)), h: mix(from.h, 58, easeOut(p)), sx: 1, sy: 1, k: 1 };
+        }
+        if (index > 0)
+            return { x: 0, h: 0, sx: 1, sy: 1, k: 0 };
+        if (rt < 0.85) {
+            const p = (rt - 0.5) / 0.35;
+            return { x: 0, h: 58 * (1 - p * p), sx: 0.92, sy: 1.1, k: 1 + 1.6 * easeOut(Math.min(1, p * 1.6)) };
+        }
+        const u = rt - 0.85;
+        const squash = Math.exp(-u * 6) * Math.cos(u * 18);
+        return { x: 0, h: 0, sx: 1 + 0.25 * squash, sy: 1 - 0.25 * squash, k: 2.6 };
+    }
+    if (rt < 0.35) {
+        const p = easeIn(rt / 0.35);
+        return { x: from.x, h: from.h * (1 - p), sx: 1, sy: 1 + 0.15 * p, k: 1 };
+    }
+    const flat = LOADER_EASE.wobble(clamp01((rt - 0.35) / 0.5));
+    const sx = 1 + 0.7 * flat;
+    const sy = 1 - 0.55 * flat;
+    if (index !== 1) {
+        const p = easeIn(clamp01((rt - 0.75) / 0.3));
+        return { x: mix(from.x, 0, p), h: 0, sx, sy, k: 1 - p };
+    }
+    const w = LOADER_EASE.wobble(clamp01((rt - 0.8) / 0.6));
+    return { x: 0, h: 0, sx: mix(sx, 1, w), sy: mix(sy, 1, w), k: 1 + 0.7 * w };
+}
+/** Cień kuli: maleje z wysokością, rośnie ze spłaszczeniem; znika razem z kulą. */
+export function bounceShadow(ball) {
+    const f = Math.max(0.3, 1 - ball.h / 80);
+    return {
+        scale: f * Math.pow(Math.max(0, ball.k), 0.8) * (ball.sx > 1 ? ball.sx : 1),
+        opacity: ball.k < 0.05 ? 0 : 0.12 + 0.3 * f,
+    };
+}

package/dist/spring.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Sprężyna jako funkcja postępu: tłumiony oscylator rozpięty na `q` od 0 do 1.
+ *
+ * Nie symulujemy w czasie rzeczywistym - krzywą liczy się raz i próbkuje do klatek WAAPI
+ * albo do `linear()` w CSS. Dzięki temu ruch zostaje zwykłą animacją przeglądarki (pauza,
+ * `cancel()`, `finished`), a nie pętlą `requestAnimationFrame`, którą trzeba sprzątać.
+ *
+ * `bounce` 0 = bez przestrzelenia (tłumienie krytyczne), 0.5 = wyraźne odbicie. Częstotliwość
+ * i rozciągnięcie czasu są dobrane tak, żeby przy `bounce <= 0.5` drgania wygasły przed `q = 1`
+ * (resztę ucina `q >= 1 -> 1`, więc ostatnia klatka zawsze trafia dokładnie w cel).
+ */
+export declare function springProgress(bounce: number): (q: number) => number;
+/** Ta sama sprężyna jako `linear(...)` - do `transition-timing-function` i `easing` w WAAPI. */
+export declare function springEasing(bounce: number, steps?: number): string;
+/** Zaokrąglenie do zapisu w CSS - krótszy napis, a różnica poniżej piksela. */
+export declare function round(value: number, digits: number): number;

package/dist/spring.js

@@ -0,0 +1,41 @@
+/**
+ * Sprężyna jako funkcja postępu: tłumiony oscylator rozpięty na `q` od 0 do 1.
+ *
+ * Nie symulujemy w czasie rzeczywistym - krzywą liczy się raz i próbkuje do klatek WAAPI
+ * albo do `linear()` w CSS. Dzięki temu ruch zostaje zwykłą animacją przeglądarki (pauza,
+ * `cancel()`, `finished`), a nie pętlą `requestAnimationFrame`, którą trzeba sprzątać.
+ *
+ * `bounce` 0 = bez przestrzelenia (tłumienie krytyczne), 0.5 = wyraźne odbicie. Częstotliwość
+ * i rozciągnięcie czasu są dobrane tak, żeby przy `bounce <= 0.5` drgania wygasły przed `q = 1`
+ * (resztę ucina `q >= 1 -> 1`, więc ostatnia klatka zawsze trafia dokładnie w cel).
+ */
+export function springProgress(bounce) {
+    const zeta = 1 - Math.min(Math.max(bounce, 0), 0.95);
+    const omega = 2 * Math.PI * 1.4;
+    return (q) => {
+        if (q <= 0)
+            return 0;
+        if (q >= 1)
+            return 1;
+        const t = q * 1.6;
+        if (zeta < 1) {
+            const wd = omega * Math.sqrt(1 - zeta * zeta);
+            return 1 - Math.exp(-zeta * omega * t) * (Math.cos(wd * t) + ((zeta * omega) / wd) * Math.sin(wd * t));
+        }
+        return 1 - Math.exp(-omega * t) * (1 + omega * t);
+    };
+}
+/** Ta sama sprężyna jako `linear(...)` - do `transition-timing-function` i `easing` w WAAPI. */
+export function springEasing(bounce, steps = 40) {
+    const fn = springProgress(bounce);
+    const n = Math.max(2, Math.round(steps));
+    const points = [];
+    for (let i = 0; i <= n; i++)
+        points.push(i === n ? '1' : String(round(fn(i / n), 4)));
+    return `linear(${points.join(', ')})`;
+}
+/** Zaokrąglenie do zapisu w CSS - krótszy napis, a różnica poniżej piksela. */
+export function round(value, digits) {
+    const k = 10 ** digits;
+    return Math.round(value * k) / k;
+}

package/dist/stepper-dom.d.ts

@@ -0,0 +1,9 @@
+import type { KptStepperSchedule } from './stepper.ts';
+/**
+ * Światło przejścia kreatora wg `stepperSchedule`: kometa (`comet`, pozycjonowana względem tego
+ * samego przodka co linie) jedzie po kolejnych odcinkach `connectors`, gaśnie na ich końcu,
+ * a znacznik, do którego dociera kolor, wypuszcza falę - `::before` animowany z WAAPI, więc
+ * nie potrzebuje dodatkowego węzła. Wołaj po renderze nowego stanu. Przy "ogranicz ruch" nic
+ * nie robi.
+ */
+export declare function playStepperLight(schedule: KptStepperSchedule, comet: HTMLElement | null, connectors: readonly HTMLElement[], markers: readonly HTMLElement[]): void;