@konce-pt/theme 0.9.0

package/dist/dtcg.js

@@ -0,0 +1,624 @@
+/**
+ * Import z formatu W3C Design Tokens (DTCG) — jednokierunkowy, plikowy.
+ *
+ * To jest import, nie synchronizacja, i tak trzeba go nazywać. Odczyt zmiennych z narzędzia
+ * projektowego przez API bywa zarezerwowany dla planów firmowych, więc realną drogą jest plik
+ * wyeksportowany wtyczką. Nie ma tu OAuth, nie ma odpytywania, nie ma śledzenia zmian.
+ *
+ * Najtrudniejsze nie jest samo czytanie tokenów, tylko **tryby**: DTCG ich nie standaryzuje.
+ * Eksportery kodują je na trzy sposoby i każdy trzeba obsłużyć osobno — patrz `splitModes`.
+ *
+ * Zasada, od której nie ma odstępstwa: **importer nigdy niczego nie gubi po cichu.** Token, którego
+ * nie umiemy przypisać, trafia do raportu z powodem. Lepiej pokazać listę stu niedopasowań niż
+ * wczytać trzydzieści i nie powiedzieć o siedemdziesięciu.
+ */
+import { formatOklch, parseHexColor, parseOklch, srgbToOklch } from '@konce-pt/color';
+import { KPT_SEMANTIC_TOKENS } from "./generated/tokens.js";
+import { isPrimitiveToken, isSemanticToken, KPT_ALL_TOKENS, scaleLength, stockTheme } from "./resolve.js";
+// ── Czytanie drzewa ──────────────────────────────────────────────────────────────────────────
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/** Węzeł jest tokenem, gdy niesie wartość — w zapisie nowym (`$value`) albo starym (`value`). */
+const tokenValue = (node) => node['$value'] !== undefined ? node['$value'] : node['value'];
+const hasValue = (node) => node['$value'] !== undefined || node['value'] !== undefined;
+const tokenType = (node, inherited) => (typeof node['$type'] === 'string' && node['$type']) ||
+    (typeof node['type'] === 'string' && node['type']) ||
+    inherited;
+/**
+ * Drzewo DTCG na płaską listę. Typ dziedziczy się z grupy — tak mówi specyfikacja i tak robią
+ * eksportery, więc token bez własnego `$type` nie jest tokenem bez typu, tylko tokenem, którego
+ * typ trzeba wziąć z rodzica.
+ */
+function flatten(node, prefix, inherited, out) {
+    if (!isRecord(node))
+        return;
+    const groupType = tokenType(node, inherited);
+    if (hasValue(node)) {
+        out.push({ path: prefix.join('.'), type: groupType, value: tokenValue(node) });
+        return;
+    }
+    for (const [key, child] of Object.entries(node)) {
+        // `$`-owe pola to metadane grupy ($type, $description, $extensions), nie tokeny.
+        if (key.startsWith('$'))
+            continue;
+        flatten(child, [...prefix, key], groupType, out);
+    }
+}
+const ALIAS = /^\{([^}]+)\}$/;
+/**
+ * Rozwiązuje aliasy `{grupa.token}`. Alias wskazujący na nieistniejącą ścieżkę **nie znika** —
+ * wraca jako `null` i ląduje w ostrzeżeniach, bo zepsuty alias w pliku źródłowym to informacja
+ * o stanie tego pliku, a nie nasz problem do zamiecenia.
+ */
+function resolveAlias(value, byPath, seen) {
+    if (typeof value !== 'string')
+        return value;
+    const match = ALIAS.exec(value.trim());
+    if (!match)
+        return value;
+    const path = match[1];
+    if (seen.has(path))
+        return null;
+    const target = byPath.get(path);
+    return target ? resolveAlias(target.value, byPath, new Set([...seen, path])) : null;
+}
+// ── Odtwarzanie przepisu ─────────────────────────────────────────────────────────────────────
+const NUMBER = /^(-?(?:\d*\.\d+|\d+))[a-z%]*$/i;
+const magnitude = (value) => {
+    const match = NUMBER.exec(String(value ?? '').trim());
+    return match ? Math.abs(Number(match[1])) : null;
+};
+/**
+ * Próbuje odczytać z zaimportowanych prymitywów **współczynnik skali** całej rodziny.
+ *
+ * Po co: eksport niesie wartości już przeliczone, więc import bez tego kroku daje motyw
+ * *wyglądający* tak samo, ale **nieedytowalny** — zamiast jednego suwaka „gęstość interfejsu"
+ * użytkownik dostaje jedenaście zamrożonych odstępów, a ruszenie suwaka nie robi nic, bo nadpisania
+ * wchodzą po przepisie i go przykrywają. Motyw, który wraca z narzędzia projektowego, ma być dalej
+ * motywem, a nie zrzutem.
+ *
+ * Sprawdzenie jest **dosłowne, nie przybliżone**: bierzemy kandydata ze stopnia o największej
+ * wartości stockowej (tam zaokrąglenie waży najmniej) i pytamy, czy nasz własny `scaleLength`
+ * odtworzyłby z niego każdy stopień rodziny co do znaku. To jedyny test, który naprawdę znaczy
+ * „nasz generator mógł to wyprodukować"; dobieranie epsilona byłoby zgadywaniem.
+ *
+ * Stopnie nieobecne w imporcie też muszą się zgadzać — ze swoją wartością stockową. Inaczej
+ * przypisanie skali po cichu ruszyłoby tokeny, których w pliku w ogóle nie było.
+ */
+function recoverScale(prefix, primitive) {
+    const stock = stockTheme().light;
+    const family = KPT_ALL_TOKENS.filter((name) => name.startsWith(prefix));
+    const given = family.filter((name) => primitive[name] !== undefined);
+    // Dwa stopnie to za mało, żeby mówić o skali — równie dobrze mogą być ręcznym nadpisaniem.
+    if (given.length < 3)
+        return null;
+    const pick = given.reduce((a, b) => ((magnitude(stock[b]) ?? 0) > (magnitude(stock[a]) ?? 0) ? b : a));
+    const base = magnitude(stock[pick]);
+    const got = magnitude(primitive[pick]);
+    if (!base || got === null)
+        return null;
+    const fits = (ratio) => family.every((name) => scaleLength(stock[name], ratio) === (primitive[name] ?? stock[name]));
+    /*
+     * Od zaokrąglenia najgrubszego do najdrobniejszego. Wartości w pliku są już przycięte do trzech
+     * miejsc, więc iloraz wychodzi z szumem: `2.344 / 1.875` to `1.25013`, a nie `1.25`. Obie liczby
+     * odtwarzają plik co do znaku, ale tylko jedna wygląda jak coś, co człowiek ustawił suwakiem.
+     */
+    const raw = got / base;
+    for (const places of [1, 2, 3, 4]) {
+        const ratio = Number(raw.toFixed(places));
+        if (ratio !== 1 && fits(ratio))
+            return ratio;
+    }
+    return null;
+}
+// ── Tryby ────────────────────────────────────────────────────────────────────────────────────
+const DARK_HINT = /(^|[^a-z])(dark|ciemn|night|nocn)/i;
+const LIGHT_HINT = /(^|[^a-z])(light|jasn|day|dzien)/i;
+/**
+ * Rozbicie treści jednego pliku na tryby po grupach najwyższego poziomu (`Light/`, `Dark/`).
+ * `null` znaczy „ten plik nie niesie obu trybów" — wtedy decyduje nazwa pliku.
+ */
+function groupSplit(content, named) {
+    if (!isRecord(content))
+        return null;
+    const groups = Object.keys(content).filter((key) => !key.startsWith('$'));
+    const light = named?.light ?? groups.find((key) => LIGHT_HINT.test(key));
+    const dark = named?.dark ?? groups.find((key) => DARK_HINT.test(key));
+    if (!light || !dark || light === dark)
+        return null;
+    if (content[light] === undefined || content[dark] === undefined)
+        return null;
+    return { light: content[light], dark: content[dark] };
+}
+/**
+ * Rozbija wejście na tryb jasny i ciemny.
+ *
+ * DTCG **nie standaryzuje trybów**, więc nie ma tu jednej poprawnej odpowiedzi — są trzy kodowania,
+ * których używają eksportery, i każde trzeba rozpoznać osobno:
+ *
+ * 1. **osobne pliki** — `light.json` / `dark.json`;
+ * 2. **grupa najwyższego poziomu** — `{ "Light": {…}, "Dark": {…} }`;
+ * 3. **rozszerzenie** — tryby schowane w `$extensions` (tu tylko wykrywamy i ostrzegamy,
+ *    bo kształt rozszerzenia jest własnością konkretnego narzędzia, nie formatu).
+ *
+ * Gdy żadne nie zadziała, plik idzie jako **jednotrybowy**: wszystko ląduje w jasnym, a ciemny
+ * zostaje stockowy. To jest uczciwsze niż wygenerowanie ciemnego z niczego i nazwanie go importem.
+ */
+function splitModes(sources, options, warnings) {
+    const out = { light: [], dark: [] };
+    const named = options.modes;
+    /*
+     * 1. Kilka plików.
+     *
+     * Nazwa pliku jest tu **ostatnią** przesłanką, nie pierwszą. Plik potrafi nieść oba tryby sam,
+     * jako grupy najwyższego poziomu, i wtedy nazwa nie znaczy nic — a wczytanie takiego pliku
+     * w całości jako „jasny" wsypuje do ścieżek przedrostek `light.`/`dark.` i psuje każde
+     * dopasowanie. Złapane na dwóch prawdziwych plikach z edytora: osobno działały, razem dawały
+     * zero trafień.
+     *
+     * Przy kilku plikach `options.modes` znaczy nazwy plików, więc do rozbicia po grupach idzie
+     * samo rozpoznanie automatyczne.
+     */
+    if (sources.length > 1) {
+        for (const source of sources) {
+            const before = out.light.length + out.dark.length;
+            const split = groupSplit(source.content, undefined);
+            if (split) {
+                flatten(split.light, [], '', out.light);
+                flatten(split.dark, [], '', out.dark);
+            }
+            else {
+                const mode = pickMode(source.name, named);
+                if (!mode) {
+                    warnings.push({ code: 'mode-guess', detail: `Nie wiadomo, którym trybem jest „${source.name}" — wczytano jako jasny.` });
+                }
+                flatten(source.content, [], '', out[mode ?? 'light']);
+            }
+            /*
+             * Plik, z którego nie wyszedł ani jeden token, ma się o tym dowiedzieć. W zestawie kilku
+             * plików reszta zasłania taki przypadek: raport pokazuje osiemdziesiąt trafień i wygląda
+             * dobrze, a jeden z plików przeszedł bez śladu. Zasada „nic nie ginie po cichu" dotyczy
+             * także całego pliku, nie tylko pojedynczego tokenu.
+             */
+            if (out.light.length + out.dark.length === before) {
+                warnings.push({
+                    code: 'empty',
+                    detail: `Z pliku „${source.name}" nie wyszedł ani jeden token — żaden węzeł nie ma pola \`$value\` ani \`value\`.`,
+                });
+            }
+        }
+        return out;
+    }
+    const only = sources[0];
+    if (!only || !isRecord(only.content))
+        return out;
+    // 2. Grupy najwyższego poziomu.
+    const split = groupSplit(only.content, named);
+    if (split) {
+        flatten(split.light, [], '', out.light);
+        flatten(split.dark, [], '', out.dark);
+        return out;
+    }
+    // 3. Rozszerzenie z trybami — rozpoznajemy, ale nie zgadujemy jego kształtu.
+    if (JSON.stringify(only.content).includes('$extensions')) {
+        warnings.push({
+            code: 'mode-guess',
+            detail: 'Plik ma pole `$extensions` — część eksporterów trzyma w nim tryby. Kształt tego pola ' +
+                'należy do narzędzia, nie do formatu, więc wczytano tylko warstwę podstawową. ' +
+                'Jeśli w pliku są dwa tryby, wskaż je ręcznie.',
+        });
+    }
+    flatten(only.content, [], '', out.light);
+    warnings.push({
+        code: 'no-modes',
+        detail: 'Plik jest jednotrybowy — motyw ciemny zostaje biblioteczny. Możesz go policzyć z ziarna.',
+    });
+    return out;
+}
+const pickMode = (name, named) => {
+    if (named?.dark && name.includes(named.dark))
+        return 'dark';
+    if (named?.light && name.includes(named.light))
+        return 'light';
+    if (DARK_HINT.test(name))
+        return 'dark';
+    if (LIGHT_HINT.test(name))
+        return 'light';
+    return null;
+};
+// ── Dopasowanie nazw ─────────────────────────────────────────────────────────────────────────
+/**
+ * Tablica synonimów — ręczna i celowo ręczna.
+ *
+ * Nazwy ról w systemach projektowych są skończonym, powtarzalnym słownikiem: `accent`, `error`,
+ * `bg`, `fg`, `stroke`. Czterdzieści wpisów wpisanych raz trafia lepiej niż dowolna miara
+ * podobieństwa napisów, która na dodatek myli się w sposób nieprzewidywalny — a niedopasowanie
+ * trafia tu do raportu, więc koszt pomyłki jest widoczny, nie cichy.
+ */
+const SYNONYMS = {
+    accent: 'primary',
+    brand: 'primary',
+    main: 'primary',
+    error: 'danger',
+    negative: 'danger',
+    destructive: 'danger',
+    critical: 'danger',
+    positive: 'success',
+    ok: 'success',
+    confirm: 'success',
+    caution: 'warning',
+    warn: 'warning',
+    informational: 'info',
+    note: 'info',
+    bg: 'surface',
+    background: 'surface',
+    canvas: 'surface',
+    paper: 'surface',
+    fg: 'on-surface',
+    foreground: 'on-surface',
+    content: 'on-surface',
+    ink: 'on-surface',
+    stroke: 'border',
+    outline: 'border',
+    divider: 'border',
+    separator: 'border',
+    line: 'border',
+    hovered: 'hover',
+    pressed: 'active',
+    focus: 'focus-ring',
+    ring: 'focus-ring',
+    disabled: 'text-subtle',
+    placeholder: 'text-subtle',
+    subdued: 'muted',
+    faint: 'subtle',
+    weak: 'subtle',
+    raised: 'surface-raised',
+    elevated: 'surface-raised',
+    sunken: 'surface-sunken',
+};
+/** Nazwa ze ścieżki DTCG w kształcie, w którym da się ją porównać z nazwą roli. */
+export function normalizeDtcgPath(path) {
+    return path
+        .replace(/[./\s_]+/g, '-')
+        .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+        .toLowerCase()
+        .replace(/^(colou?r|kpt|token|global|semantic|theme)-/, '')
+        .replace(/-(default|base|value)$/, '')
+        .replace(/-{2,}/g, '-')
+        .replace(/^-|-$/g, '');
+}
+const applySynonyms = (name) => name
+    .split('-')
+    .map((word) => SYNONYMS[word] ?? word)
+    .join('-')
+    .replace(/-{2,}/g, '-');
+/**
+ * Dwa indeksy celu, bo dopasowanie idzie dwoma różnymi drogami.
+ *
+ * `BY_NAME` to **wszystkie** tokeny biblioteki po nazwie bez prefiksu. Trafia w niego plik, który
+ * naszych nazw używa wprost — przede wszystkim nasz własny eksport DTCG, ale też każdy plik
+ * zbudowany na naszych tokenach. Dopasowanie dokładne nie zgaduje, więc objęcie nim całej
+ * biblioteki nic nie ryzykuje: obca nazwa po prostu w niego nie trafi.
+ *
+ * `BY_ROLE` to same role semantyczne koloru i tylko na nim wolno puścić synonimy — bo tylko tam
+ * zgadywanie ma sens. Nikt nie nazwie w swoim pliku tokenu `button-filled-bg` przypadkiem.
+ */
+const BY_NAME = new Map(KPT_ALL_TOKENS.map((name) => [name.replace('--kpt-', ''), name]));
+const BY_ROLE = new Map(KPT_SEMANTIC_TOKENS.filter((name) => name.startsWith('--kpt-color-')).map((name) => [
+    name.replace('--kpt-color-', ''),
+    name,
+]));
+/** Ścieżka sprowadzona do jednego separatora i małych liter, bez obcinania członów. */
+const flatName = (path) => path
+    .replace(/[./\s_]+/g, '-')
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .toLowerCase()
+    .replace(/-{2,}/g, '-')
+    .replace(/^-|-$/g, '');
+/**
+ * Zwija powtórzone sąsiadujące człony: `surface-surface-raised` → `surface-raised`.
+ *
+ * Powtórzenie bierze się z podstawienia synonimu, którego cel sam jest wielowyrazowy. `elevated`
+ * znaczy `surface-raised`, więc `surface-elevated` rozwijało się do `surface-surface-raised`
+ * i nie trafiało w nic — tak samo `text-disabled` → `text-text-subtle`. To defekt mechanizmu,
+ * nie brak wpisu w tablicy: dotyczy każdego synonimu o wielowyrazowym celu.
+ *
+ * Bezpieczne, bo **żadna rola biblioteki nie powtarza sąsiadującego członu** — sprawdzane testem.
+ */
+const dedupe = (name) => name.split('-').filter((word, i, all) => word !== all[i - 1]).join('-');
+/**
+ * Konwencje przyrostków `-bg` / `-fg` na rodzinie statusu.
+ *
+ * To nie jest synonim pojedynczego słowa, tylko **kształt nazwy**: `error-bg` znaczy „wypełnienie
+ * rodziny błędu", a `error-fg` „treść na tym wypełnieniu". Po podstawieniu synonimów wyglądają jak
+ * `danger-surface` i `danger-on-surface`, więc rozpoznajemy je tutaj, a nie w tablicy słów.
+ *
+ * Partner dla treści nie jest u nas jednolity: `primary`/`danger`/`muted` mają `on-*`, a pozostałe
+ * rodziny `*-contrast`. Próbujemy obu, zamiast zakładać jeden kształt.
+ */
+function conventionRole(name) {
+    const fill = /^(.+)-surface$/.exec(name);
+    if (fill && BY_ROLE.has(fill[1]))
+        return fill[1];
+    const on = /^(.+)-on-surface$/.exec(name);
+    if (on) {
+        for (const candidate of [`on-${on[1]}`, `${on[1]}-contrast`]) {
+            if (BY_ROLE.has(candidate))
+                return candidate;
+        }
+    }
+    return null;
+}
+function matchTarget(path, map) {
+    const manual = map?.[path];
+    if (manual)
+        return { to: manual, confidence: 'manual' };
+    const byName = BY_NAME.get(flatName(path));
+    if (byName)
+        return { to: byName, confidence: 'exact' };
+    const role = normalizeDtcgPath(path);
+    const exact = BY_ROLE.get(role);
+    if (exact)
+        return { to: exact, confidence: 'exact' };
+    const swapped = applySynonyms(role);
+    const collapsed = dedupe(swapped);
+    const synonym = BY_ROLE.get(swapped) ?? BY_ROLE.get(collapsed) ?? BY_ROLE.get(conventionRole(collapsed) ?? '');
+    return synonym ? { to: synonym, confidence: 'synonym' } : null;
+}
+// ── Wartości ─────────────────────────────────────────────────────────────────────────────────
+/**
+ * Kolor DTCG na zapis OKLCH.
+ *
+ * Zapisujemy w OKLCH, a nie w tym, co przyszło, bo paleta biblioteki jest w OKLCH i plik motywu
+ * ma się czytać razem z `tokens.css`, a nie obok niego. Hex jest ośmiobitowy, więc konwersja
+ * niczego nie gubi; zapis, którego nie umiemy sprowadzić do składowych, zostaje **bez zmiany** —
+ * lepiej przepuścić `rgb(…)` dalej niż zgubić token, bo nie mieliśmy na niego parsera.
+ */
+function colorValue(raw) {
+    if (typeof raw !== 'string')
+        return null;
+    const value = raw.trim();
+    if (!value)
+        return null;
+    /*
+     * Zapis `oklch()` przepuszczamy **verbatim**, tak jak robi to cały łańcuch tokenów.
+     *
+     * Przepuszczenie go przez `formatOklch` niczego nie poprawia, a psuje jedną rzecz: wyrównuje
+     * zapis do trzech miejsc po przecinku, więc `oklch(0.985 0 0)` wraca jako `oklch(0.985 0.000 0)`.
+     * Ten sam kolor, inny napis — a `themeDiff` porównuje napisy. Po obiegu przez DTCG kilkanaście
+     * tokenów udawałoby zmienione, licznik „zmienionych ról" kłamałby, a eksport niósłby linie,
+     * które niczego nie zmieniają. Normalizujemy wyłącznie to, co naprawdę trzeba przeliczyć.
+     */
+    if (parseOklch(value))
+        return value;
+    const rgb = parseHexColor(value);
+    return rgb ? formatOklch(srgbToOklch(rgb)) : value;
+}
+/** Wymiar: nowszy zapis `{ value, unit }` i starszy `"16px"` — oba występują w realnych plikach. */
+function dimensionValue(raw) {
+    if (typeof raw === 'number')
+        return `${raw}px`;
+    if (typeof raw === 'string')
+        return raw.trim() || null;
+    if (isRecord(raw) && typeof raw['value'] === 'number' && typeof raw['unit'] === 'string') {
+        return `${raw['value']}${raw['unit']}`;
+    }
+    return null;
+}
+const COMPOSITE = new Set(['typography', 'border', 'shadow', 'transition', 'gradient', 'strokeStyle']);
+// ── Rampy ────────────────────────────────────────────────────────────────────────────────────
+/** Stopień rampy poznajemy po tym, że ostatni człon ścieżki jest liczbą. */
+const STEP = /^(\d{1,4})$/;
+/**
+ * Grupy, które wyglądają na rampy barw: co najmniej pięć numerycznych stopni.
+ *
+ * Rampa jest w pliku najcenniejszą rzeczą, bo z niej bierze się **ziarno** — jedna liczba, z której
+ * generator odtwarza całą rodzinę ról. Dlatego szukamy jej osobno, zamiast zostawiać jej stopnie
+ * jako pięćdziesiąt niedopasowanych tokenów w raporcie.
+ */
+function findRamps(tokens) {
+    const groups = new Map();
+    for (const token of tokens) {
+        if (token.type !== 'color')
+            continue;
+        const parts = token.path.split('.');
+        const step = STEP.exec(parts[parts.length - 1] ?? '');
+        if (!step)
+            continue;
+        const value = colorValue(token.value);
+        if (!value)
+            continue;
+        const group = parts.slice(0, -1).join('.');
+        const steps = groups.get(group) ?? new Map();
+        steps.set(Number(step[1]), value);
+        groups.set(group, steps);
+    }
+    for (const [group, steps] of groups)
+        if (steps.size < 5)
+            groups.delete(group);
+    return groups;
+}
+const BRAND_RAMP = /(brand|primary|accent|main)/i;
+/** Stopień najbliższy temu, na którym biblioteka trzyma bazę akcentu w motywie jasnym. */
+const SEED_STEP = 600;
+const seedFrom = (steps) => {
+    const keys = [...steps.keys()].sort((a, b) => Math.abs(a - SEED_STEP) - Math.abs(b - SEED_STEP));
+    return keys.length > 0 ? steps.get(keys[0]) : undefined;
+};
+// ── Wejście główne ───────────────────────────────────────────────────────────────────────────
+/**
+ * Czyta pliki DTCG i buduje z nich dokument motywu.
+ *
+ * Zwraca **parę**: motyw i raport. Raport nie jest dodatkiem — to on decyduje, czy import da się
+ * przyjąć, i to on pokazuje, czego plik nie pokrył. Interfejs ma go wyświetlić, a nie schować.
+ */
+export function fromDtcg(sources, options = {}) {
+    const report = { matched: [], unmapped: [], missing: [], warnings: [], ramps: [] };
+    /*
+     * Wyjście bez wyniku też musi być uczciwe. Import, który niczego nie pokrył, zostawia **wszystkie**
+     * role na wartościach bibliotecznych — a pusta lista `missing` mówiła coś wprost przeciwnego:
+     * „ról bez pokrycia: 0". Raport jest tu całym produktem, więc nie ma prawa kłamać także wtedy,
+     * gdy nie ma o czym mówić.
+     */
+    const nothing = () => {
+        report.missing = [...KPT_SEMANTIC_TOKENS];
+        return { theme: { kptTheme: 1 }, report };
+    };
+    if (sources.length === 0) {
+        report.warnings.push({ code: 'empty', detail: 'Nie podano żadnego pliku.' });
+        return nothing();
+    }
+    const byMode = splitModes(sources, options, report.warnings);
+    if (byMode.light.length === 0 && byMode.dark.length === 0) {
+        report.warnings.push({
+            code: 'empty',
+            // „Nie znaleziono tokenu" samo w sobie nie mówi, gdzie szukać winy. Najczęstszy powód jest
+            // banalny: to po prostu nie jest plik DTCG.
+            detail: 'W plikach nie znaleziono żadnego tokenu — żaden węzeł nie ma pola `$value` ani `value`. ' +
+                'Najpewniej to nie jest eksport DTCG.',
+        });
+        return nothing();
+    }
+    if (sources.some((s) => JSON.stringify(s.content).includes('"value"') && !JSON.stringify(s.content).includes('"$value"'))) {
+        report.warnings.push({
+            code: 'legacy-format',
+            detail: 'Plik używa starszego zapisu `value`/`type` zamiast `$value`/`$type`. Wczytany, ale warto odświeżyć eksport.',
+        });
+    }
+    const semantic = { light: {}, dark: {} };
+    const primitive = {};
+    const importMap = { ...(options.map ?? {}) };
+    let seed;
+    for (const mode of ['light', 'dark']) {
+        const tokens = byMode[mode];
+        if (tokens.length === 0)
+            continue;
+        const byPath = new Map(tokens.map((token) => [token.path, token]));
+        const ramps = findRamps(tokens);
+        const rampPaths = new Set([...ramps.keys()]);
+        if (mode === 'light') {
+            for (const [path, steps] of ramps) {
+                const entry = { path, steps: steps.size, seed: BRAND_RAMP.test(path) ? seedFrom(steps) : undefined };
+                report.ramps.push(entry);
+                if (entry.seed && !seed)
+                    seed = entry.seed;
+            }
+        }
+        for (const token of tokens) {
+            // Stopnie rozpoznanej rampy nie są niedopasowaniem — obsłużyliśmy je jako rampę.
+            if (rampPaths.has(token.path.split('.').slice(0, -1).join('.')))
+                continue;
+            if (COMPOSITE.has(token.type)) {
+                report.unmapped.push({ path: token.path, type: token.type, value: '—', reason: 'composite' });
+                continue;
+            }
+            const resolved = resolveAlias(token.value, byPath, new Set());
+            if (resolved === null) {
+                report.warnings.push({ code: 'alias-broken', detail: `„${token.path}" wskazuje na token, którego w pliku nie ma.` });
+                report.unmapped.push({ path: token.path, type: token.type, value: String(token.value), reason: 'unreadable-value' });
+                continue;
+            }
+            const target = matchTarget(token.path, options.map);
+            if (!target) {
+                report.unmapped.push({
+                    path: token.path,
+                    type: token.type,
+                    value: String(dimensionValue(resolved) ?? colorValue(resolved) ?? resolved),
+                    reason: token.type === 'color' || token.type === 'dimension' ? 'no-target' : 'unsupported-type',
+                });
+                continue;
+            }
+            const value = token.type === 'color' ? colorValue(resolved) : dimensionValue(resolved);
+            if (!value) {
+                report.unmapped.push({ path: token.path, type: token.type, value: String(resolved), reason: 'unreadable-value' });
+                continue;
+            }
+            /*
+             * Warstwa decyduje, gdzie wartość ląduje — i czy w ogóle.
+             *
+             * Semantyka idzie osobno w każdym motywie. Prymitywy są wspólne dla obu, bo tak są
+             * zdefiniowane w bibliotece; różne wartości w dwóch trybach to konflikt, o którym trzeba
+             * powiedzieć, a nie po cichu wziąć drugiej. Tokeny komponentowe **odrzucamy świadomie**:
+             * podążają za semantyką przez `var()`, więc zaimportowanie ich jako nadpisań zamroziłoby je
+             * na dzisiejszej wartości i późniejsza zmiana koloru wiodącego przestałaby ruszać przycisk.
+             */
+            if (isSemanticToken(target.to)) {
+                semantic[mode][target.to] = value;
+            }
+            else if (isPrimitiveToken(target.to)) {
+                const clash = primitive[target.to];
+                if (clash !== undefined && clash !== value) {
+                    report.warnings.push({
+                        code: 'mode-guess',
+                        detail: `Prymityw „${target.to}" ma inną wartość w każdym trybie; prymitywy są wspólne, więc została pierwsza.`,
+                    });
+                }
+                else {
+                    primitive[target.to] = value;
+                }
+            }
+            else {
+                report.unmapped.push({ path: token.path, type: token.type, value, reason: 'derived' });
+                continue;
+            }
+            importMap[token.path] = target.to;
+            report.matched.push({ from: token.path, to: target.to, mode, confidence: target.confidence });
+        }
+    }
+    const covered = new Set(report.matched.map((m) => m.to));
+    report.missing = KPT_SEMANTIC_TOKENS.filter((name) => !covered.has(name));
+    const theme = { kptTheme: 1, meta: { name: 'Import DTCG', importMap } };
+    const recipe = {};
+    if (seed)
+        recipe.color = { seed: { primary: seed } };
+    /*
+     * Skale wracają do przepisu, a prymitywy, z których je odczytaliśmy, wypadają z nadpisań.
+     * Zostawienie obu naraz byłoby gorsze niż każde z osobna: nadpisania wchodzą **po** przepisie,
+     * więc przykryłyby go i suwak dalej byłby martwy — tyle że teraz wyglądałby na ustawiony.
+     */
+    const radiusScale = recoverScale('--kpt-radius-', primitive);
+    if (radiusScale !== null)
+        recipe.radius = { scale: radiusScale };
+    const spacingScale = recoverScale('--kpt-space-', primitive);
+    if (spacingScale !== null)
+        recipe.spacing = { scale: spacingScale };
+    const sizeScale = recoverScale('--kpt-font-size-', primitive);
+    const sans = primitive['--kpt-font-family-sans'];
+    const mono = primitive['--kpt-font-family-mono'];
+    if (sizeScale !== null || sans || mono) {
+        recipe.typography = {};
+        if (sizeScale !== null)
+            recipe.typography.sizeScale = sizeScale;
+        if (sans)
+            recipe.typography.sans = sans;
+        if (mono)
+            recipe.typography.mono = mono;
+    }
+    const recovered = [
+        ...(radiusScale !== null ? ['--kpt-radius-'] : []),
+        ...(spacingScale !== null ? ['--kpt-space-'] : []),
+        ...(sizeScale !== null ? ['--kpt-font-size-'] : []),
+    ];
+    for (const name of Object.keys(primitive)) {
+        if (recovered.some((prefix) => name.startsWith(prefix)))
+            delete primitive[name];
+    }
+    if (sans)
+        delete primitive['--kpt-font-family-sans'];
+    if (mono)
+        delete primitive['--kpt-font-family-mono'];
+    if (Object.keys(recipe).length > 0)
+        theme.recipe = recipe;
+    const overrides = {};
+    if (Object.keys(primitive).length > 0)
+        overrides.primitive = primitive;
+    if (Object.keys(semantic.light).length > 0 || Object.keys(semantic.dark).length > 0) {
+        overrides.semantic = {};
+        if (Object.keys(semantic.light).length > 0)
+            overrides.semantic.light = semantic.light;
+        if (Object.keys(semantic.dark).length > 0)
+            overrides.semantic.dark = semantic.dark;
+    }
+    if (Object.keys(overrides).length > 0)
+        theme.overrides = overrides;
+    return { theme, report };
+}