@konce-pt/theme 0.9.0

package/dist/resolve.js

@@ -0,0 +1,192 @@
+/**
+ * Rozwiązywanie motywu: stock → recipe → overrides → custom.
+ *
+ * Wartości stockowe są trzymane surowo, z referencjami `{--kpt-nazwa}`, i to jest tu cała sztuczka.
+ * Gdyby stock był spłaszczony do liczb, nadpisanie prymitywu `--kpt-radius-md` nie ruszyłoby
+ * `--kpt-button-radius`, który się na niego powołuje — a w przeglądarce ruszyłoby, bo tam robi to
+ * kaskada przez `var()`. Podgląd rozjeżdżałby się z eksportem dokładnie w tym miejscu, w którym
+ * użytkownik akurat kręci suwakiem promienia.
+ *
+ * Wartości z przepisu wchodzą tą samą drogą co ręczne nadpisania, ale **przed** nimi: ręczna
+ * zmiana roli zawsze wygrywa z generatorem i przeliczenie palety od nowa jej nie kasuje.
+ */
+import { buildRamp, readSeed } from "./ramp.js";
+import { derivePrimary } from "./roles.js";
+import { KPT_RAW, KPT_SEMANTIC_TOKENS } from "./generated/tokens.js";
+const MODES = ['light', 'dark'];
+const REFERENCE = /\{(--[a-z0-9-]+)\}/g;
+const LENGTH = /^(-?(?:\d*\.\d+|\d+))([a-z%]*)$/i;
+/**
+ * Mnoży wartość długości przez współczynnik, zachowując jednostkę. Wartość, która nie jest
+ * pojedynczą liczbą z jednostką (np. `clamp()` albo lista), wraca bez zmiany — skalowanie czegoś,
+ * czego nie rozumiemy, dawałoby wynik gorszy niż zostawienie tego w spokoju.
+ */
+export function scaleLength(value, factor) {
+    const match = LENGTH.exec(value.trim());
+    if (!match)
+        return value;
+    const scaled = Number(match[1]) * factor;
+    // Trzy miejsca wystarczą dla rem i px, a ucięcie zer trzyma wartości czytelnymi w diffie.
+    return `${Number(scaled.toFixed(3))}${match[2]}`;
+}
+const namesStartingWith = (prefix) => Object.keys(KPT_RAW).filter((n) => n.startsWith(prefix));
+/**
+ * Tokeny skalowalne z danej rodziny: te, których wartość stockowa jest liczbą z jednostką.
+ * `--kpt-radius-full` (9999px) i `--kpt-radius-none` (0) przechodzą przez mnożenie bez szkody —
+ * zero zostaje zerem, a „pełny" promień i tak jest tylko umownie dużą liczbą.
+ */
+const scaleFamily = (prefix, factor, mode, into) => {
+    for (const name of namesStartingWith(prefix)) {
+        into[name] = scaleLength(KPT_RAW[name][mode], factor);
+    }
+};
+/**
+ * Wartości wynikające z przepisu, osobno dla każdego motywu. To jest jedyne miejsce, w którym
+ * `recipe` zamienia się w tokeny — dalej wszystko jest już zwykłym nadpisaniem.
+ */
+export function recipeLayer(doc, mode) {
+    const recipe = doc.recipe;
+    if (!recipe)
+        return {};
+    const out = {};
+    const seedValue = recipe.color?.seed?.primary;
+    if (seedValue) {
+        const seed = readSeed(seedValue);
+        if (!seed)
+            throw new TypeError(`recipe.color.seed.primary: "${seedValue}" nie jest kolorem`);
+        Object.assign(out, derivePrimary(buildRamp(seed), mode));
+    }
+    const radius = recipe.radius;
+    if (radius) {
+        // `base` wyrażamy przez współczynnik, żeby cała skala promieni zachowała swoje proporcje:
+        // ustawienie samego `md` rozjechałoby `sm` i `lg` względem niego.
+        const stockBase = Number(LENGTH.exec(KPT_RAW['--kpt-radius-md'].light)?.[1] ?? 0);
+        const fromBase = radius.base ? Number(LENGTH.exec(radius.base)?.[1] ?? NaN) / stockBase : 1;
+        const factor = (Number.isFinite(fromBase) ? fromBase : 1) * (radius.scale ?? 1);
+        if (factor !== 1)
+            scaleFamily('--kpt-radius-', factor, mode, out);
+    }
+    const typography = recipe.typography;
+    if (typography) {
+        if (typography.sans)
+            out['--kpt-font-family-sans'] = typography.sans;
+        if (typography.mono)
+            out['--kpt-font-family-mono'] = typography.mono;
+        const stockBase = Number(LENGTH.exec(KPT_RAW['--kpt-font-size-md'].light)?.[1] ?? 0);
+        const fromBase = typography.baseSize ? Number(LENGTH.exec(typography.baseSize)?.[1] ?? NaN) / stockBase : 1;
+        const factor = (Number.isFinite(fromBase) ? fromBase : 1) * (typography.sizeScale ?? 1);
+        if (factor !== 1)
+            scaleFamily('--kpt-font-size-', factor, mode, out);
+    }
+    const spacingScale = recipe.spacing?.scale;
+    // Porównanie z `null`, nie test prawdziwości: `0` jest poprawną skalą (choć osobliwą),
+    // a `if (spacingScale && …)` cicho by ją pominął. Promienie i typografia już tak nie robią.
+    if (spacingScale != null && spacingScale !== 1)
+        scaleFamily('--kpt-space-', spacingScale, mode, out);
+    return out;
+}
+/**
+ * Warstwa nadpisań dla jednego motywu: przepis, potem nadpisania ręczne, potem tokeny własne.
+ * Zwraca wartości **surowe** — referencje `{--kpt-...}` są tu nadal dozwolone, bo nadpisanie
+ * w rodzaju „primary ma być tym, czym info" jest sensowne i ma przeżyć do eksportu.
+ */
+export function themeLayer(doc, mode) {
+    const layer = { ...recipeLayer(doc, mode) };
+    Object.assign(layer, doc.overrides?.primitive ?? {});
+    Object.assign(layer, doc.overrides?.component ?? {});
+    Object.assign(layer, doc.overrides?.semantic?.[mode] ?? {});
+    for (const [name, token] of Object.entries(doc.custom ?? {})) {
+        layer[name] = (mode === 'dark' ? token.dark : token.light) ?? token.light;
+    }
+    return layer;
+}
+const resolveMap = (raw) => {
+    const done = {};
+    const resolveOne = (name, seen) => {
+        if (done[name] !== undefined)
+            return done[name];
+        if (seen.includes(name))
+            throw new Error(`Cykl referencji tokenów: ${[...seen, name].join(' → ')}`);
+        const value = raw[name];
+        // Referencja do tokenu, którego nie ma, zostaje w wyniku dosłownie — jest wtedy widoczna
+        // w podglądzie i w eksporcie, zamiast zamienić się w pustkę, której nikt nie umie wyjaśnić.
+        if (value === undefined)
+            return `{${name}}`;
+        const resolved = value.replace(REFERENCE, (_, ref) => resolveOne(ref, [...seen, name]));
+        done[name] = resolved;
+        return resolved;
+    };
+    for (const name of Object.keys(raw))
+        resolveOne(name, []);
+    return done;
+};
+/** Motyw rozwiązany do wartości dosłownych — to, co widać w podglądzie i mierzy audyt. */
+export function resolveTheme(doc) {
+    const out = {};
+    for (const mode of MODES) {
+        const raw = {};
+        for (const [name, value] of Object.entries(KPT_RAW))
+            raw[name] = value[mode];
+        if (doc)
+            Object.assign(raw, themeLayer(doc, mode));
+        out[mode] = resolveMap(raw);
+    }
+    return out;
+}
+/** Stock rozwiązany — punkt odniesienia dla różnicy. Liczony raz, bo się nie zmienia. */
+let stockCache;
+export const stockTheme = () => (stockCache ??= resolveTheme());
+/**
+ * Tokeny, których wartość różni się od stockowej — czyli to, co realnie trzeba wyemitować.
+ * Liczone po **rozwiązaniu**, więc nadpisanie prymitywu pokazuje się tu jako komplet ról, które
+ * za nim poszły, a nie jako jeden wpis, którego skutków nie widać.
+ */
+export function themeDiff(doc, mode) {
+    const resolved = resolveTheme(doc)[mode];
+    const stock = stockTheme()[mode];
+    const diff = {};
+    for (const [name, value] of Object.entries(resolved)) {
+        if (stock[name] !== value)
+            diff[name] = value;
+    }
+    return diff;
+}
+const SEMANTIC = new Set(KPT_SEMANTIC_TOKENS);
+export const isSemanticToken = (name) => SEMANTIC.has(name);
+export const isKnownToken = (name) => KPT_RAW[name] !== undefined;
+/**
+ * Prymityw poznajemy po prefiksie nazwy — to jedyna informacja o warstwie, jaką niesie sama nazwa.
+ * Trzyma to `resolve.ts`, a nie emiter, bo pytają o to trzy różne rzeczy: eksport (co wypisać),
+ * import (gdzie to włożyć) i edytor (który panel).
+ */
+const PRIMITIVE_PREFIXES = [
+    '--kpt-color-neutral-',
+    '--kpt-color-red-',
+    '--kpt-color-green-',
+    '--kpt-color-amber-',
+    '--kpt-color-blue-',
+    '--kpt-space-',
+    '--kpt-radius-',
+    '--kpt-border-width-',
+    '--kpt-z-',
+    '--kpt-motion-',
+    '--kpt-font-',
+    '--kpt-breakpoint-',
+];
+export const isPrimitiveToken = (name) => PRIMITIVE_PREFIXES.some((p) => name.startsWith(p));
+/** Wszystkie nazwy tokenów biblioteki — importer dopasowuje do nich dokładnie, bez synonimów. */
+export const KPT_ALL_TOKENS = Object.keys(KPT_RAW);
+/**
+ * Nazwy z dokumentu, których biblioteka nie zna. Motyw zapisany pod starszą wersją ma prawo się
+ * otworzyć i dopiero wtedy powiedzieć, co zniknęło — dlatego to jest osobne pytanie, a nie błąd
+ * parsowania.
+ */
+export function unknownTokens(doc) {
+    const names = new Set([
+        ...Object.keys(doc.overrides?.primitive ?? {}),
+        ...Object.keys(doc.overrides?.component ?? {}),
+        ...Object.keys(doc.overrides?.semantic?.light ?? {}),
+        ...Object.keys(doc.overrides?.semantic?.dark ?? {}),
+    ]);
+    return [...names].filter((name) => !isKnownToken(name)).sort();
+}

package/dist/roles.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Derywacja ról semantycznych z rampy.
+ *
+ * Który stopień rampy trafia na którą rolę, nie jest tu wymyślone: biblioteka ma cztery rodziny
+ * chromatyczne (danger/success/warning/info) o identycznym układzie stopni i to on jest wzorcem.
+ * Generator odczytuje go z tokenów i pilnuje, żeby te cztery rodziny się nie rozjechały — więc
+ * kolor wiodący wyprowadzony z ziarna zachowuje się dokładnie tak, jak zachowują się kolory
+ * statusowe, które biblioteka już wydaje.
+ *
+ * Rola `-active` jest jedynym wyjątkiem, bo rodziny statusowe jej nie mają: wzorzec jest tam
+ * przedłużony o jeden krok w tę samą stronę, w którą idzie `-hover`.
+ */
+import type { KptRamp } from './ramp.ts';
+import type { KptThemeMode } from './schema.ts';
+/**
+ * Treść czytelniejsza na danym wypełnieniu, wybrana przez APCA — nie przez próg luminancji.
+ * Próg jest jedną liczbą dla wszystkich barw i myli się na nasyconych średnich jasnościach,
+ * czyli dokładnie tam, gdzie lądują kolory marki.
+ */
+export declare function contentOn(fill: string, mode: KptThemeMode): string;
+/**
+ * Rodzina koloru wiodącego dla jednego motywu: sześć ról z rampy plus `--kpt-color-on-primary`
+ * policzone kontrastem. `--kpt-color-primary-contrast` i `--kpt-color-text-inverse` nie są tu
+ * wymienione, bo w stocku są referencjami do `on-primary` — pójdą za nim same, przez graf.
+ */
+export declare function derivePrimary(ramp: KptRamp, mode: KptThemeMode): Record<string, string>;
+/** Nazwy ról, które przestawia ziarno koloru wiodącego. Edytor oznacza je jako „z przepisu". */
+export declare const KPT_PRIMARY_ROLES: readonly string[];

package/dist/roles.js

@@ -0,0 +1,77 @@
+/**
+ * Derywacja ról semantycznych z rampy.
+ *
+ * Który stopień rampy trafia na którą rolę, nie jest tu wymyślone: biblioteka ma cztery rodziny
+ * chromatyczne (danger/success/warning/info) o identycznym układzie stopni i to on jest wzorcem.
+ * Generator odczytuje go z tokenów i pilnuje, żeby te cztery rodziny się nie rozjechały — więc
+ * kolor wiodący wyprowadzony z ziarna zachowuje się dokładnie tak, jak zachowują się kolory
+ * statusowe, które biblioteka już wydaje.
+ *
+ * Rola `-active` jest jedynym wyjątkiem, bo rodziny statusowe jej nie mają: wzorzec jest tam
+ * przedłużony o jeden krok w tę samą stronę, w którą idzie `-hover`.
+ */
+import { apcaLc, formatOklch, oklchToSrgb, parseOklch } from '@konce-pt/color';
+import { KPT_ACCENT_PATTERN, KPT_RAW } from "./generated/tokens.js";
+/** Rodzina koloru wiodącego: rola → slot wzorca akcentu. */
+const PRIMARY_FAMILY = {
+    '--kpt-color-primary': 'base',
+    '--kpt-color-primary-hover': 'hover',
+    '--kpt-color-primary-active': 'active',
+    '--kpt-color-primary-subtle': 'subtle',
+    '--kpt-color-primary-border': 'border',
+    // Pierścień focus chodzi za kolorem wiodącym — w stocku jest dokładnie tym samym tokenem.
+    '--kpt-color-focus-ring': 'base',
+};
+/**
+ * Kandydaci na treść leżącą na wypełnieniu akcentowym. Bierzemy je ze stocku, a nie z czerni
+ * i bieli wprost: `--kpt-color-neutral-0` i `-950` to te same wartości, których biblioteka używa
+ * w rolach `*-contrast`, więc wybór zostaje w palecie zamiast wprowadzać barwy spoza niej.
+ */
+const CONTENT_CANDIDATES = ['--kpt-color-neutral-0', '--kpt-color-neutral-950'];
+const toRgb = (value) => {
+    const oklch = parseOklch(value);
+    return oklch ? oklchToSrgb(oklch) : null;
+};
+/**
+ * Treść czytelniejsza na danym wypełnieniu, wybrana przez APCA — nie przez próg luminancji.
+ * Próg jest jedną liczbą dla wszystkich barw i myli się na nasyconych średnich jasnościach,
+ * czyli dokładnie tam, gdzie lądują kolory marki.
+ */
+export function contentOn(fill, mode) {
+    const background = toRgb(fill);
+    if (!background)
+        return KPT_RAW[CONTENT_CANDIDATES[0]][mode];
+    let best = CONTENT_CANDIDATES[0];
+    let score = -Infinity;
+    for (const candidate of CONTENT_CANDIDATES) {
+        const value = KPT_RAW[candidate][mode];
+        const rgb = toRgb(value);
+        if (!rgb)
+            continue;
+        const lc = Math.abs(apcaLc(rgb, background));
+        if (lc > score) {
+            score = lc;
+            best = candidate;
+        }
+    }
+    return KPT_RAW[best][mode];
+}
+/**
+ * Rodzina koloru wiodącego dla jednego motywu: sześć ról z rampy plus `--kpt-color-on-primary`
+ * policzone kontrastem. `--kpt-color-primary-contrast` i `--kpt-color-text-inverse` nie są tu
+ * wymienione, bo w stocku są referencjami do `on-primary` — pójdą za nim same, przez graf.
+ */
+export function derivePrimary(ramp, mode) {
+    const out = {};
+    for (const [token, slot] of Object.entries(PRIMARY_FAMILY)) {
+        const step = KPT_ACCENT_PATTERN[slot][mode];
+        const color = ramp[step];
+        if (!color)
+            throw new Error(`Rampa nie ma stopnia ${step} wymaganego przez rolę ${token}`);
+        out[token] = formatOklch(color);
+    }
+    out['--kpt-color-on-primary'] = contentOn(out['--kpt-color-primary'], mode);
+    return out;
+}
+/** Nazwy ról, które przestawia ziarno koloru wiodącego. Edytor oznacza je jako „z przepisu". */
+export const KPT_PRIMARY_ROLES = [...Object.keys(PRIMARY_FAMILY), '--kpt-color-on-primary'];

package/dist/runtime.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Nakładanie motywu w przeglądarce.
+ *
+ * To jest ten sam kod, którym podgląd edytora wstrzykuje style — i to nie jest zbieg okoliczności,
+ * tylko warunek: podgląd ma pokazywać dokładnie ten tekst CSS, który wychodzi z eksportu.
+ *
+ * Wstrzykujemy **blok `<style>`**, nie style inline na `<html>`. Inline wystarcza do kilku
+ * zmiennych i tak robi to dziś playground, ale nie umie wyrazić różnych wartości dla motywu
+ * jasnego i ciemnego w jednym dokumencie — a przede wszystkim nie jest tym, co konsument wklei
+ * u siebie. Blok `<style>` jest dosłownie artefaktem eksportu.
+ */
+import type { KptEmitOptions } from './emit.ts';
+import type { KptThemeDoc } from './schema.ts';
+/** Identyfikator bloku stylu. Stały, żeby kolejne nałożenia podmieniały, a nie dokładały. */
+export declare const KPT_THEME_STYLE_ID = "kpt-theme";
+export interface KptApplyOptions extends KptEmitOptions {
+    /** Dokument docelowy — podgląd w iframe podaje tu `frame.contentDocument`. */
+    document?: Document;
+    /** Identyfikator bloku stylu, gdy w jednym dokumencie ma żyć więcej niż jeden motyw. */
+    id?: string;
+}
+/**
+ * Nakłada motyw i zwraca funkcję, która go zdejmuje.
+ *
+ * Aktualizacja idzie przez podmianę `textContent` jednego węzła — dla dwustu zmiennych to jedno
+ * przeliczenie stylów, rząd milisekundy. Przy ciągnięciu suwaka warto to zdławić przez
+ * `requestAnimationFrame` po stronie wywołującego; tutaj nie dławimy, bo funkcja ma być
+ * przewidywalna, a nie sprytna.
+ */
+export declare function applyKptTheme(theme: KptThemeDoc, options?: KptApplyOptions): () => void;
+/** Zdejmuje motyw nałożony przez `applyKptTheme`. Brak bloku nie jest błędem. */
+export declare function clearKptTheme(options?: Pick<KptApplyOptions, 'document' | 'id'>): void;

package/dist/runtime.js

@@ -0,0 +1,41 @@
+/**
+ * Nakładanie motywu w przeglądarce.
+ *
+ * To jest ten sam kod, którym podgląd edytora wstrzykuje style — i to nie jest zbieg okoliczności,
+ * tylko warunek: podgląd ma pokazywać dokładnie ten tekst CSS, który wychodzi z eksportu.
+ *
+ * Wstrzykujemy **blok `<style>`**, nie style inline na `<html>`. Inline wystarcza do kilku
+ * zmiennych i tak robi to dziś playground, ale nie umie wyrazić różnych wartości dla motywu
+ * jasnego i ciemnego w jednym dokumencie — a przede wszystkim nie jest tym, co konsument wklei
+ * u siebie. Blok `<style>` jest dosłownie artefaktem eksportu.
+ */
+import { emitCss } from "./emit.js";
+/** Identyfikator bloku stylu. Stały, żeby kolejne nałożenia podmieniały, a nie dokładały. */
+export const KPT_THEME_STYLE_ID = 'kpt-theme';
+/**
+ * Nakłada motyw i zwraca funkcję, która go zdejmuje.
+ *
+ * Aktualizacja idzie przez podmianę `textContent` jednego węzła — dla dwustu zmiennych to jedno
+ * przeliczenie stylów, rząd milisekundy. Przy ciągnięciu suwaka warto to zdławić przez
+ * `requestAnimationFrame` po stronie wywołującego; tutaj nie dławimy, bo funkcja ma być
+ * przewidywalna, a nie sprytna.
+ */
+export function applyKptTheme(theme, options = {}) {
+    const target = options.document ?? (typeof document !== 'undefined' ? document : undefined);
+    if (!target)
+        throw new Error('applyKptTheme: brak dokumentu — w Node podaj `document` albo użyj emitCss');
+    const id = options.id ?? KPT_THEME_STYLE_ID;
+    let style = target.getElementById(id);
+    if (!style) {
+        style = target.createElement('style');
+        style.id = id;
+        target.head.append(style);
+    }
+    style.textContent = emitCss(theme, options);
+    return () => style?.remove();
+}
+/** Zdejmuje motyw nałożony przez `applyKptTheme`. Brak bloku nie jest błędem. */
+export function clearKptTheme(options = {}) {
+    const target = options.document ?? (typeof document !== 'undefined' ? document : undefined);
+    target?.getElementById(options.id ?? KPT_THEME_STYLE_ID)?.remove();
+}

package/dist/schema.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Kontrakt dokumentu motywu. To jest format, który edytor zapisuje, eksport czyta, a kiedyś
+ * odczyta go chmura — więc ma być mały, płaski i czytelny w code review.
+ *
+ * Dwie decyzje niosą resztę:
+ *
+ * 1. **Zapisujemy różnicę, nie zrzut.** Token niezmieniony nie występuje w dokumencie. Motyw waży
+ *    kilka kilobajtów zamiast kilkudziesięciu, a nowe tokeny w kolejnej wersji biblioteki
+ *    dziedziczą się same, zamiast zamarzać na wartościach sprzed aktualizacji.
+ * 2. **`recipe` (wejścia generatora) jest oddzielone od `overrides` (ręczne odklejenia).** Sam
+ *    zrzut wartości uniemożliwiłby ponowne otwarcie suwaków; same parametry generatora zgubiłyby
+ *    ręczne poprawki. Kolejność rozwiązywania to stock → recipe → overrides, a wartości
+ *    wyprodukowane przez przepis **nie trafiają** do `overrides` — dzięki temu „przelicz paletę
+ *    od nowa" nie kasuje ręcznej pracy.
+ *
+ * Kluczem jest nazwa custom property (`--kpt-color-primary`), nie ścieżka Style Dictionary:
+ * to jest realny kontrakt publiczny biblioteki i dokładnie to, co konsument wpisuje u siebie.
+ */
+export type KptThemeMode = 'light' | 'dark';
+/** Bieżąca wersja formatu. Liczba całkowita — patrz `migrateTheme`. */
+export declare const KPT_THEME_VERSION = 1;
+export interface KptThemeMeta {
+    id?: string;
+    name?: string;
+    author?: string;
+    createdAt?: string;
+    updatedAt?: string;
+    /** Monotoniczny licznik zapisów — podstawa rozstrzygania konfliktów w przyszłej chmurze. */
+    revision?: number;
+    basedOn?: {
+        package: string;
+        version: string;
+    };
+    /**
+     * Utrwalone mapowanie ze ścieżki DTCG na nazwę tokenu, zapisane przy imporcie.
+     *
+     * To ono zamienia jednorazowy import w element procesu pracy: po zmianie brandbooka kolejne
+     * wczytanie tego samego pliku nie wymaga ponownego przechodzenia przez ekran mapowania.
+     * Jednorazowy importer jest zabawką — powtarzalny jest narzędziem.
+     */
+    importMap?: Record<string, string>;
+}
+/**
+ * Wejścia generatora. Pola nieustawione (albo `null`) znaczą „zostaw stock" — to nie to samo co
+ * brak pola, ale jedno i drugie daje ten sam wynik, więc zapis pozostaje odporny na `null`
+ * przychodzący z formularza.
+ */
+export interface KptThemeRecipe {
+    color?: {
+        /** Kolor wiodący jako `#rrggbb` albo zapis `oklch()`. Z niego liczona jest cała rodzina. */
+        seed?: {
+            primary?: string | null;
+        } | null;
+    } | null;
+    radius?: {
+        base?: string | null;
+        scale?: number | null;
+    } | null;
+    typography?: {
+        sans?: string | null;
+        mono?: string | null;
+        baseSize?: string | null;
+        sizeScale?: number | null;
+    } | null;
+    spacing?: {
+        scale?: number | null;
+    } | null;
+}
+export interface KptThemeOverrides {
+    /** Nadpisania prymitywów — działają w obu motywach, bo prymitywy są zdefiniowane raz. */
+    primitive?: Record<string, string>;
+    semantic?: {
+        light?: Record<string, string>;
+        dark?: Record<string, string>;
+    };
+    component?: Record<string, string>;
+}
+export interface KptCustomToken {
+    light: string;
+    /** Brak wartości ciemnej znaczy „ta sama w obu motywach". */
+    dark?: string;
+    description?: string;
+}
+export interface KptThemeExport {
+    /** Selektor motywu ciemnego. Biblioteka używa `[data-theme="dark"]`. */
+    darkSelector?: string;
+    /** Dołóż blok `@media (prefers-color-scheme: dark)` — biblioteka sama go nie ma. */
+    prefersColorScheme?: boolean;
+    /**
+     * `resolved` emituje całą różnicę wartościami dosłownymi, w obu blokach — działa na każdej wersji
+     * biblioteki. `layered` zostawia nadpisania na warstwie prymitywów i pomija to, co z nich wynika —
+     * krócej, ale wymaga wersji z poprawką ciemnego arkusza. Domyślnie `resolved`; patrz `emitPlan`.
+     */
+    compat?: 'resolved' | 'layered';
+}
+export interface KptThemeDoc {
+    $schema?: string;
+    kptTheme: typeof KPT_THEME_VERSION;
+    meta?: KptThemeMeta;
+    recipe?: KptThemeRecipe;
+    overrides?: KptThemeOverrides;
+    custom?: Record<string, KptCustomToken>;
+    export?: KptThemeExport;
+}
+/** Pusty motyw — czyli stock. Przydaje się jako punkt startu i jako wartość domyślna. */
+export declare const emptyTheme: () => KptThemeDoc;
+/**
+ * Czyta dokument z nieznanego wejścia. Strażniki pisane ręcznie, bez walidatora schematów —
+ * tak jak w reszcie repozytorium, i z tego samego powodu: zależność runtime na jednym `parse`
+ * kosztuje więcej, niż jest tu warta.
+ *
+ * Rzuca z komunikatem wskazującym pole. Nie sprawdza, czy nazwy tokenów **istnieją** — od tego
+ * jest `unknownTokens`, bo motyw zapisany pod starszą wersją biblioteki ma prawo się otworzyć
+ * i dopiero wtedy powiedzieć, co się rozjechało.
+ */
+export declare function parseTheme(input: unknown): KptThemeDoc;
+/**
+ * Podnosi dokument do bieżącej wersji formatu. Dziś łańcuch jest pusty, bo wersja jest pierwsza —
+ * ale wejście jest tu po to, żeby przy wersji 2 nie trzeba było szukać, gdzie wstawić migrację.
+ * Czytanie starych plików nie ma prawa się zepsuć: bez tego „zapis projektów" nie jest funkcją,
+ * tylko obietnicą.
+ */
+export declare function migrateTheme(input: unknown): KptThemeDoc;
+/**
+ * Zapis o stabilnej kolejności kluczy. Dokument trafia do repozytorium konsumenta, więc dwa
+ * zapisy tego samego motywu muszą dawać ten sam plik — inaczej każdy zapis to szum w diffie.
+ */
+export declare function serializeTheme(doc: KptThemeDoc): string;

package/dist/schema.js

@@ -0,0 +1,129 @@
+/**
+ * Kontrakt dokumentu motywu. To jest format, który edytor zapisuje, eksport czyta, a kiedyś
+ * odczyta go chmura — więc ma być mały, płaski i czytelny w code review.
+ *
+ * Dwie decyzje niosą resztę:
+ *
+ * 1. **Zapisujemy różnicę, nie zrzut.** Token niezmieniony nie występuje w dokumencie. Motyw waży
+ *    kilka kilobajtów zamiast kilkudziesięciu, a nowe tokeny w kolejnej wersji biblioteki
+ *    dziedziczą się same, zamiast zamarzać na wartościach sprzed aktualizacji.
+ * 2. **`recipe` (wejścia generatora) jest oddzielone od `overrides` (ręczne odklejenia).** Sam
+ *    zrzut wartości uniemożliwiłby ponowne otwarcie suwaków; same parametry generatora zgubiłyby
+ *    ręczne poprawki. Kolejność rozwiązywania to stock → recipe → overrides, a wartości
+ *    wyprodukowane przez przepis **nie trafiają** do `overrides` — dzięki temu „przelicz paletę
+ *    od nowa" nie kasuje ręcznej pracy.
+ *
+ * Kluczem jest nazwa custom property (`--kpt-color-primary`), nie ścieżka Style Dictionary:
+ * to jest realny kontrakt publiczny biblioteki i dokładnie to, co konsument wpisuje u siebie.
+ */
+/** Bieżąca wersja formatu. Liczba całkowita — patrz `migrateTheme`. */
+export const KPT_THEME_VERSION = 1;
+/** Pusty motyw — czyli stock. Przydaje się jako punkt startu i jako wartość domyślna. */
+export const emptyTheme = () => ({ kptTheme: KPT_THEME_VERSION });
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const TOKEN_NAME = /^--[a-z][a-z0-9-]*$/;
+/** Mapa nazwa-tokenu → wartość. Nazwy sprawdzamy, wartości nie — CSS przyjmuje zbyt wiele. */
+const readTokenMap = (value, where) => {
+    if (!isRecord(value))
+        throw new TypeError(`${where}: oczekiwano obiektu, jest ${typeof value}`);
+    const out = {};
+    for (const [name, raw] of Object.entries(value)) {
+        if (!TOKEN_NAME.test(name))
+            throw new TypeError(`${where}: "${name}" nie jest nazwą custom property`);
+        if (typeof raw !== 'string')
+            throw new TypeError(`${where}.${name}: wartość musi być tekstem`);
+        out[name] = raw;
+    }
+    return out;
+};
+/**
+ * Czyta dokument z nieznanego wejścia. Strażniki pisane ręcznie, bez walidatora schematów —
+ * tak jak w reszcie repozytorium, i z tego samego powodu: zależność runtime na jednym `parse`
+ * kosztuje więcej, niż jest tu warta.
+ *
+ * Rzuca z komunikatem wskazującym pole. Nie sprawdza, czy nazwy tokenów **istnieją** — od tego
+ * jest `unknownTokens`, bo motyw zapisany pod starszą wersją biblioteki ma prawo się otworzyć
+ * i dopiero wtedy powiedzieć, co się rozjechało.
+ */
+export function parseTheme(input) {
+    if (!isRecord(input))
+        throw new TypeError('Motyw: oczekiwano obiektu JSON');
+    if (input['kptTheme'] !== KPT_THEME_VERSION) {
+        throw new TypeError(`Motyw: nieobsługiwana wersja formatu ${String(input['kptTheme'])} (obsługiwana: ${KPT_THEME_VERSION})`);
+    }
+    const doc = { kptTheme: KPT_THEME_VERSION };
+    if (typeof input['$schema'] === 'string')
+        doc.$schema = input['$schema'];
+    if (isRecord(input['meta']))
+        doc.meta = input['meta'];
+    if (isRecord(input['recipe']))
+        doc.recipe = input['recipe'];
+    if (isRecord(input['export']))
+        doc.export = input['export'];
+    if (input['overrides'] !== undefined) {
+        const raw = input['overrides'];
+        if (!isRecord(raw))
+            throw new TypeError('overrides: oczekiwano obiektu');
+        const overrides = {};
+        if (raw['primitive'] !== undefined)
+            overrides.primitive = readTokenMap(raw['primitive'], 'overrides.primitive');
+        if (raw['component'] !== undefined)
+            overrides.component = readTokenMap(raw['component'], 'overrides.component');
+        if (raw['semantic'] !== undefined) {
+            const semantic = raw['semantic'];
+            if (!isRecord(semantic))
+                throw new TypeError('overrides.semantic: oczekiwano obiektu');
+            overrides.semantic = {};
+            for (const mode of ['light', 'dark']) {
+                if (semantic[mode] !== undefined) {
+                    overrides.semantic[mode] = readTokenMap(semantic[mode], `overrides.semantic.${mode}`);
+                }
+            }
+        }
+        doc.overrides = overrides;
+    }
+    if (input['custom'] !== undefined) {
+        const raw = input['custom'];
+        if (!isRecord(raw))
+            throw new TypeError('custom: oczekiwano obiektu');
+        const custom = {};
+        for (const [name, value] of Object.entries(raw)) {
+            if (!TOKEN_NAME.test(name))
+                throw new TypeError(`custom: "${name}" nie jest nazwą custom property`);
+            if (!isRecord(value) || typeof value['light'] !== 'string') {
+                throw new TypeError(`custom.${name}: wymagane pole "light" typu tekstowego`);
+            }
+            const token = { light: value['light'] };
+            if (typeof value['dark'] === 'string')
+                token.dark = value['dark'];
+            if (typeof value['description'] === 'string')
+                token.description = value['description'];
+            custom[name] = token;
+        }
+        doc.custom = custom;
+    }
+    return doc;
+}
+/**
+ * Podnosi dokument do bieżącej wersji formatu. Dziś łańcuch jest pusty, bo wersja jest pierwsza —
+ * ale wejście jest tu po to, żeby przy wersji 2 nie trzeba było szukać, gdzie wstawić migrację.
+ * Czytanie starych plików nie ma prawa się zepsuć: bez tego „zapis projektów" nie jest funkcją,
+ * tylko obietnicą.
+ */
+export function migrateTheme(input) {
+    return parseTheme(input);
+}
+const KEY_ORDER = ['$schema', 'kptTheme', 'meta', 'recipe', 'overrides', 'custom', 'export'];
+/**
+ * Zapis o stabilnej kolejności kluczy. Dokument trafia do repozytorium konsumenta, więc dwa
+ * zapisy tego samego motywu muszą dawać ten sam plik — inaczej każdy zapis to szum w diffie.
+ */
+export function serializeTheme(doc) {
+    const ordered = {};
+    for (const key of KEY_ORDER) {
+        const value = doc[key];
+        if (value !== undefined)
+            ordered[key] = value;
+    }
+    return `${JSON.stringify(ordered, null, 2)}\n`;
+}