@appaflytech/zeyrek-ai-mcp 0.0.8 → 0.0.9

package/dist/knowledge/themeRules.js

@@ -0,0 +1,221 @@
+import { GOOGLE_FONTS, MAX_PRESET_VERSIONS, SCALE_RATIO_MAX, isValidPresetName } from './themeResolve.js';
+/**
+ * ÖZET — Tema yazmasının lint'i (THEME-001…011).
+ *
+ * İki küme, iki farklı gövdeye bakar ve bu ayrım bilinçlidir:
+ *
+ * - **block** kuralları BİRLEŞMİŞ kayda bakar (`themePolicyRules`): yazılacak kayıt geçerli
+ *   olmalı, geçersizliği base'ten gelse bile. Bunlar runtime'ı sessizce bozan şeylerdir.
+ * - **warn** kuralları yalnız ÇAĞIRANIN YAZDIĞINA bakar (`themeInputWarnings`): base'te duran
+ *   eski bir kusur yüzünden her `theme_update` çağrısında aynı uyarıyı basmak gürültüdür ve
+ *   gürültü okunmaz.
+ *
+ * Kaynak: `docs/08-kural-envanteri.md` §Tema araçları.
+ */
+const guide = 'ngapps://guides/theme';
+const isPlainObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const HEX = /^#([0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
+const FULL_HEX = /^#[0-9a-f]{6}$/i;
+const CSS_LENGTH = /^-?\d+(\.\d+)?(px|rem|em|%|vh|vw|vmin|vmax|ch|ex|pt|pc|cm|mm|in)$/i;
+function block(ruleId, message) {
+    return { ruleId, severity: 'block', message, guide };
+}
+function warn(ruleId, message) {
+    return { ruleId, severity: 'warn', message, guide };
+}
+/** Ad → gövde kayıtlarındaki adlar (preset'ler ve versiyonlar aynı kurala uyar). */
+function presetNameFindings(theme) {
+    const findings = [];
+    const invalid = (label, name) => block('THEME-001', `${label} adı geçersiz: '${name}'. Ad boş olamaz, başında/sonunda boşluk taşıyamaz, '$' ile başlayamaz (çözümleyicinin sihirli anahtarlarıyla — $preset / $componentPreset — karışır) ve 40 karakteri aşamaz. Ad bir nesne ANAHTARIDIR ve düğümün stiline ham metin olarak yazılır.`);
+    for (const name of Object.keys(theme.presets ?? {})) {
+        if (!isValidPresetName(name))
+            findings.push(invalid('Preset', name));
+    }
+    for (const [type, preset] of Object.entries(theme.componentPresets ?? {})) {
+        if (!isPlainObject(preset) || !isPlainObject(preset.versions))
+            continue;
+        for (const name of Object.keys(preset.versions)) {
+            if (!isValidPresetName(name))
+                findings.push(invalid(`'${type}' versiyon`, name));
+        }
+    }
+    return findings;
+}
+function componentPresetShapeFindings(theme) {
+    const findings = [];
+    for (const [type, preset] of Object.entries(theme.componentPresets ?? {})) {
+        if (!isPlainObject(preset))
+            continue;
+        const versions = isPlainObject(preset.versions) ? Object.keys(preset.versions) : [];
+        const defaultVersion = String(preset.defaultVersion ?? '');
+        if (versions.length === 0) {
+            findings.push(block('THEME-002', `componentPresets.${type}: 'versions' boş — bir bileşen preset'i en az bir versiyon taşır. Tipin varsayılanını kaldırmak istiyorsanız kaydın tamamını silin: unset: ['componentPresets.${type}'].`));
+            continue;
+        }
+        if (!versions.includes(defaultVersion)) {
+            findings.push(block('THEME-002', `componentPresets.${type}: defaultVersion '${defaultVersion}' versiyonlar arasında yok (${versions.join(', ')}). Panel bozuk kaydı ilk versiyona onarır ama YAZARKEN doğrusunu vermek gerekir — yeni düğümler varsayılan versiyonun prop'larıyla kurulur.`));
+        }
+        if (versions.length > MAX_PRESET_VERSIONS) {
+            findings.push(block('THEME-002', `componentPresets.${type}: ${versions.length} versiyon — sınır ${MAX_PRESET_VERSIONS}. Panelin versiyon şeridi tek satırda okunur kalsın diye sınırlıdır ve dolduğunda 'Yeni versiyon' düğmesini hiç çizmez.`));
+        }
+    }
+    return findings;
+}
+function shadowFindings(theme) {
+    const color = theme.shadow?.color;
+    if (color === undefined || FULL_HEX.test(color))
+        return [];
+    return [block('THEME-004', `shadow.color '${color}' altı haneli hex DEĞİL. Runtime rengi karakter karakter ayrıştırıyor (shadowTokens); tanımadığı değerde --ng-shadow-sm/md/lg ÜÇÜ BİRDEN '0px 0px 0px 0px rgba(0, 0, 0, 0)' olur, yani gölge sessizce kapanır. '#000000' gibi yazın.`)];
+}
+function lengthFindings(theme) {
+    const findings = [];
+    const check = (path, value) => {
+        if (value === undefined)
+            return;
+        if (typeof value === 'string' && CSS_LENGTH.test(value.trim()))
+            return;
+        findings.push(block('THEME-006', `${path}: ${JSON.stringify(value)} bir CSS uzunluğu değil. Değer değişkene HAM basılır (--ng-font-size: ${String(value)}), tarayıcı bildirimi atar ve tek işaret konsoldur. '16px' gibi birimli yazın — çıplak sayıyı gateway kendisi px'e çevirir.`));
+    };
+    check('fontSize', theme.fontSize);
+    check('spacing', theme.spacing);
+    check('borderRadius', theme.borderRadius);
+    if (theme.radiusScale?.pill !== undefined)
+        check('radiusScale.pill', theme.radiusScale.pill);
+    return findings;
+}
+function ratioFindings(theme) {
+    const findings = [];
+    const scales = [
+        ['typeScale', theme.typeScale],
+        ['spacingScale', theme.spacingScale],
+        ['radiusScale', theme.radiusScale ? { sm: theme.radiusScale.sm, lg: theme.radiusScale.lg } : undefined]
+    ];
+    for (const [name, scale] of scales) {
+        for (const [level, value] of Object.entries(scale ?? {})) {
+            if (value === undefined)
+                continue;
+            if (typeof value === 'number' && value > 0 && value <= SCALE_RATIO_MAX)
+                continue;
+            findings.push(block('THEME-007', `${name}.${level}: ${JSON.stringify(value)} geçersiz oran — 0 < oran ≤ ${SCALE_RATIO_MAX} olmalı. Runtime aralık dışını SESSİZCE yok sayar (mergeRatioScale), yani kademe varsayılanda kalır ve "yazdım ama değişmedi" görürsünüz. Sıfır/negatif oran kademeyi görünmez yapacağı için yasak.`));
+        }
+    }
+    const opacity = theme.shadow?.opacity;
+    if (opacity !== undefined && (typeof opacity !== 'number' || opacity < 0 || opacity > 100)) {
+        findings.push(block('THEME-007', `shadow.opacity: ${JSON.stringify(opacity)} — 0-100 arası YÜZDE bekleniyor (runtime bunu 100'e bölüp alfa yapar).`));
+    }
+    return findings;
+}
+/** Kayıt geçerli olmalı: bu kurallar BİRLEŞMİŞ gövdeye bakar ve isteği durdurur. */
+export const themePolicyRules = [
+    {
+        id: 'THEME-001',
+        module: 'theme',
+        appliesTo: ['update'],
+        sourceRef: "preset-name.functions.ts isValidPresetName; style-presets.ts STYLE_PRESET_KEY ('$preset' ham anahtar olarak düğüm stiline yazılır)",
+        check: definition => presetNameFindings(definition)
+    },
+    {
+        id: 'THEME-002',
+        module: 'theme',
+        appliesTo: ['update'],
+        sourceRef: 'component-presets.functions.ts MAX_PRESET_VERSIONS / normalizeComponentPreset (bozuk defaultVersion ilk versiyona onarılır)',
+        check: definition => componentPresetShapeFindings(definition)
+    },
+    {
+        id: 'THEME-004',
+        module: 'theme',
+        appliesTo: ['update'],
+        sourceRef: 'theme/utils.ts shadowTokens — color.length < 7 ⇒ üç gölge de görünmez',
+        check: definition => shadowFindings(definition)
+    },
+    {
+        id: 'THEME-006',
+        module: 'theme',
+        appliesTo: ['update'],
+        sourceRef: 'theme/utils.ts mergeTokens + buildThemeStyle — değer CSS değişkenine ham basılır',
+        check: definition => lengthFindings(definition)
+    },
+    {
+        id: 'THEME-007',
+        module: 'theme',
+        appliesTo: ['update'],
+        sourceRef: 'theme/utils.ts mergeRatioScale (>0 değilse sessizce yok sayılır); theme-logic.ts readScaleRatio (0 < r ≤ 20)',
+        check: definition => ratioFindings(definition)
+    }
+];
+/** Hex olmayan renk değerlerini toplar (`palette` · `paletteDark` · `actions` · `colors`). */
+function colorWarnings(theme) {
+    const offenders = [];
+    const visit = (path, value) => {
+        if (typeof value === 'string' && !HEX.test(value.trim()))
+            offenders.push(`${path}: '${value}'`);
+    };
+    for (const group of ['palette', 'paletteDark']) {
+        for (const [name, values] of Object.entries(theme[group] ?? {})) {
+            if (!isPlainObject(values))
+                continue;
+            for (const [key, value] of Object.entries(values))
+                visit(`${group}.${name}.${key}`, value);
+        }
+    }
+    for (const [name, value] of Object.entries(theme.actions ?? {}))
+        visit(`actions.${name}`, value);
+    for (const [family, tones] of Object.entries(theme.colors ?? {})) {
+        if (!isPlainObject(tones))
+            continue;
+        for (const [tone, value] of Object.entries(tones))
+            visit(`colors.${family}.${tone}`, value);
+    }
+    if (offenders.length === 0)
+        return [];
+    return [warn('THEME-005', `Hex olmayan renk değeri (${offenders.slice(0, 5).join(' · ')}${offenders.length > 5 ? ` · +${offenders.length - 5}` : ''}). CSS bunları çizer ama iki yer bozulur: studio'nun renk chip'leri hex bekler ve --ng-text-on-accent accent'i karakter karakter okuyup kontrast hesapladığı için (getContrastColor) tanımadığı değerde '#ffffff'e düşer — koyu bir accent üstüne beyaz metin yazılır sanılır. '#RRGGBB' yazın.`)];
+}
+/**
+ * Yalnız ÇAĞIRANIN yazdığına bakan uyarılar. `merged` bağlam içindir (THEME-009 karşı modun
+ * kayıtta olup olmadığını bilmek zorunda).
+ */
+export function themeInputWarnings(input, merged) {
+    const findings = [...colorWarnings(input)];
+    if (input.componentStyles !== undefined) {
+        findings.push(warn('THEME-003', `componentStyles EMEKLİ (${Object.keys(input.componentStyles).join(', ')}). Runtime onu hâlâ uyguluyor ama Studio tema paneli açıldığı ilk kayıtta içeriği componentPresets'in varsayılan versiyonuna TAŞIYIP anahtarı siliyor — yani "tipin her örneğine canlı uygulanan stil" sessizce "yalnız YENİ düğümlere varsayılan"a döner ve sayfadaki mevcut düğümler o an görünüşlerini kaybeder. Kalıcı ortak görünüm için adlı preset + style.$preset; yeni düğümlerin başlangıç değeri için componentPresets.`));
+    }
+    for (const font of [input.fontFamily, input.headingFontFamily]) {
+        if (font === undefined || font === '' || GOOGLE_FONTS.includes(font))
+            continue;
+        findings.push(warn('THEME-008', `'${font}' panelin Google Fonts listesinde yok. Runtime yazı tipini ADIYLA Google'a bağlıyor (fonts.googleapis.com/css2?family=${font.replace(/ /g, '+')}); ad yanlışsa istek boş döner ve metin sessizce sans-serif çizilir. Sistem fontu kullanacaksanız bu uyarı beklenendir.`));
+    }
+    if (input.palette !== undefined && merged.paletteDark === undefined) {
+        const dark = merged.mode === 'dark';
+        findings.push(warn('THEME-009', dark
+            ? "Tema mode:'dark' ama yalnız 'palette' yazıldı: palet override'ları MOD BAŞINA tutulur (palette aydınlıkta, paletteDark karanlıkta) ve runtime karanlık modda paletteDark'a bakar — yazdığınız renkler ekranda HİÇ görünmez. Karanlık için paletteDark yazın ya da mode:'light' yapın."
+            : "'palette' yazıldı ama 'paletteDark' yok. Proje mode:'light' olsa bile ziyaretçi koyu moda GEÇEBİLİR (theme-toggle komponenti, tarayıcıda kalıcı; page_screenshot colorScheme:'dark' aynı yolu kullanır) ve o an runtime paletteDark'a bakar — markanız kaybolur, platformun kendi koyu paleti çizilir (ölçüldü 2026-09-15). Uygulama koyu modda hiç açılmayacaksa bu uyarı yok sayılabilir."));
+    }
+    return findings;
+}
+/** THEME-010 — silinen preset'i işaret eden düğümler sessizce kendi stiline düşer. */
+export function unsetWarnings(base, paths) {
+    const removed = paths
+        .map(path => /^presets\.(.+)$/.exec(path)?.[1])
+        .filter((name) => name !== undefined && Object.hasOwn(base.presets ?? {}, name));
+    if (removed.length === 0)
+        return [];
+    return [warn('THEME-010', `Silinen preset (${removed.join(', ')}) sayfalardaki düğümlerde SESSİZCE kaybolur: çözümleyici eşleşmeyen bir $preset adını hata vermeden atlar (pages must not blank out), yani düğüm kendi stiline düşer ve kimse bir şey söylemez. Silmeden önce style.$preset ile bağlı düğümleri arayın (page_schema_get) — gateway bu taramayı henüz yapmıyor.`)];
+}
+/** THEME-011 — bileşen preset'i yalnız YERLEŞTİRİLEBİLİR bir tipe verilebilir. */
+export function componentPresetTypeWarnings(theme, components) {
+    const known = new Map(components
+        .filter(component => typeof component.slug === 'string')
+        .map(component => [component.slug, component]));
+    const findings = [];
+    for (const type of Object.keys(theme.componentPresets ?? {})) {
+        const component = known.get(type);
+        if (component === undefined) {
+            findings.push(warn('THEME-011', `componentPresets.${type}: bu uygulamanın kataloğunda '${type}' diye bir komponent YOK — kayıt yazılır ama hiçbir düğüme uygulanmaz. Slug'ları component_list verir.`));
+            continue;
+        }
+        if (component.kind === 'widget' || component.isHide === true) {
+            findings.push(warn('THEME-011', `componentPresets.${type}: bu tipe preset verilemez (${component.kind === 'widget' ? 'widget kendi şemasını yönetir' : 'araç kutusunun gizlediği iç tip'}) — tasarımcının yerleştiremediği bir tipin varsayılanı da olmaz.`));
+        }
+    }
+    return findings;
+}

package/dist/knowledge/themeSchema.js

@@ -0,0 +1,335 @@
+import { PALETTE_GROUPS, SPACING_KEYS, THEME_TOP_LEVEL_KEYS } from './themeResolve.js';
+import { normalizeStyleKeys } from './normalize.js';
+import { z } from 'zod';
+/**
+ * ÖZET — Tema kaydının OKUNABİLİR özeti: `theme_get(view:'summary')`'nin gövdesi ve
+ * `project_overview` / `page_runtime_get`'in kısa tema bloğu buradan çıkar.
+ *
+ * Özet "ne yazılmış" sorusunu yanıtlar, "ekranda ne çizilir" sorusunu değil — ikincisi
+ * `themeResolve.ts`'in işi. Ayrım bilinçli: bir projenin temasında NEYE dokunulduğunu görmek
+ * (marka rengi mi, yalnız preset mi) 190 değişkenlik çözümü okumaktan başka bir sorudur ve
+ * ajanın ilk sorduğu odur.
+ */
+const isPlainObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/** `{ accent: { primary } }` → `['accent.primary']`; palet override'ı bu kadarla anlatılır. */
+function paletteEntries(palette) {
+    if (!isPlainObject(palette))
+        return [];
+    return Object.entries(palette).flatMap(([group, values]) => isPlainObject(values) ? Object.keys(values).map(key => `${group}.${key}`) : [group]);
+}
+/**
+ * Kayıtta BULUNAN üst anahtarların dökümü. Yokluk `null` ile anlatılmaz: `prune`
+ * (platform/responses.ts) null alanları yanıttan siliyor, yani "yazılmamış" ile "yok" aynı
+ * görünürdü. Yazılmayan alan `overrides`'a HİÇ girmez; giren her alan gerçekten kayıtta vardır.
+ */
+export function summarizeTheme(theme) {
+    const overrides = {};
+    const record = theme;
+    for (const key of ['palette', 'paletteDark']) {
+        const entries = paletteEntries(record[key]);
+        if (entries.length > 0)
+            overrides[key] = entries;
+    }
+    for (const key of ['fontFamily', 'headingFontFamily', 'fontSize', 'fontWeight', 'spacing', 'borderRadius', 'defaultInputSize']) {
+        if (record[key] !== undefined)
+            overrides[key] = record[key];
+    }
+    // Ölçekler ve gölge olduğu gibi taşınır: yalnız SAPAN kademeler kayda giriyor, yani kaydın
+    // kendisi zaten özet (`theme-logic.ts` scaleToOverrides).
+    for (const key of ['typeScale', 'radiusScale', 'spacingScale', 'shadow']) {
+        if (isPlainObject(record[key]))
+            overrides[key] = record[key];
+    }
+    if (isPlainObject(record.colors))
+        overrides.colors = Object.keys(record.colors);
+    if (isPlainObject(record.actions))
+        overrides.actions = Object.keys(record.actions);
+    const presetNames = isPlainObject(theme.presets) ? Object.keys(theme.presets) : [];
+    const componentPresets = {};
+    for (const [type, preset] of Object.entries(theme.componentPresets ?? {})) {
+        if (!isPlainObject(preset))
+            continue;
+        const versions = isPlainObject(preset.versions) ? preset.versions : {};
+        componentPresets[type] = {
+            defaultVersion: String(preset.defaultVersion ?? ''),
+            versions: Object.keys(versions),
+            hasAppearance: Object.values(versions).some(version => isPlainObject(version) && isPlainObject(version.appearance))
+        };
+    }
+    const retiredTypes = isPlainObject(theme.componentStyles) ? Object.keys(theme.componentStyles) : [];
+    return {
+        mode: theme.mode === 'dark' ? 'dark' : 'light',
+        overrides,
+        presets: { count: presetNames.length, names: presetNames },
+        componentPresets,
+        ...(retiredTypes.length > 0 ? { retired: { componentStyles: retiredTypes } } : {}),
+        unknownKeys: Object.keys(record).filter(key => !THEME_TOP_LEVEL_KEYS.includes(key))
+    };
+}
+/** Projenin tema kaydı — nesne olmayan (null, metin, dizi) her değer "tema yok" demektir. */
+export function readProjectTheme(payload) {
+    const data = isPlainObject(payload) ? payload.data : undefined;
+    const theme = isPlainObject(data) ? data.theme : undefined;
+    return isPlainObject(theme) ? theme : undefined;
+}
+/* ---- Yazma yolu: şema · birleştirme · silme · normalizasyon · fark ---- */
+const length = z.union([z.number(), z.string()]);
+/**
+ * Palet şeması paletin KENDİSİNDEN üretilir (`PALETTE_GROUPS`): grup ve anahtar listesini ikinci
+ * kez yazmak, frontend'e yeni bir rol eklendiğinde sessizce eskiyen bir kopya olurdu.
+ */
+const paletteSchema = z.object(Object.fromEntries(Object.entries(PALETTE_GROUPS).map(([group, keys]) => [
+    group,
+    z.object(Object.fromEntries(keys.map(key => [key, z.string()]))).partial().strict().optional()
+]))).strict();
+const ratioScale = (levels) => z.object(Object.fromEntries(levels.map(level => [level, z.number()]))).partial().strict();
+/**
+ * `.strict()` her seviyede: tanınmayan anahtar İSTEK GİTMEDEN düşer. Gerekçe platformun kendi
+ * davranışı — `projects.theme` doğrulanmayan bir jsonb blob'u, yani `pallete` yazan istek 200
+ * döner, kayıt sessizce yanlış anahtarı taşır ve panel onu körce geri yazar. Şema bu sessizliğin
+ * tek kapısıdır (GW-002 sınıfı: tanınmayan anahtar kanalı yoktur, muhafız vardır).
+ */
+export const themeInput = z.object({
+    mode: z.enum(['light', 'dark']),
+    palette: paletteSchema,
+    paletteDark: paletteSchema,
+    fontFamily: z.string().min(1),
+    headingFontFamily: z.string(),
+    typeScale: ratioScale(['h1', 'h2', 'h3', 'h4', 'label', 'p', 'small']),
+    fontSize: length,
+    fontWeight: z.union([z.string(), z.number()]),
+    borderRadius: length,
+    radiusScale: z.object({ sm: z.number(), lg: z.number(), pill: length }).partial().strict(),
+    spacing: length,
+    spacingScale: ratioScale(['xs', 'sm', 'md', 'lg', 'xl']),
+    shadow: z.object({
+        offsetX: z.number(),
+        offsetY: z.number(),
+        blur: z.number(),
+        spread: z.number(),
+        color: z.string(),
+        opacity: z.number()
+    }).partial().strict(),
+    defaultInputSize: z.enum(['sm', 'md', 'lg']),
+    colors: z.record(z.record(z.string())),
+    actions: z.object(Object.fromEntries(['gray', 'red', 'green', 'blue', 'teal', 'pink', 'purple', 'cyan', 'orange', 'yellow', 'white', 'black']
+        .map(name => [name, z.string()]))).partial().strict(),
+    presets: z.record(z.record(z.unknown())),
+    componentStyles: z.record(z.record(z.unknown())),
+    // Versiyon gövdesi TOLERANSLI: eski kayıtlar düz CSS nesnesiydi ve normalizasyon onu `props`
+    // zarfına alır (`normalizeVersion` ile aynı kural). Şemayı sıkmak eski gövdeyi reddederdi.
+    componentPresets: z.record(z.object({
+        defaultVersion: z.string(),
+        versions: z.record(z.record(z.unknown()))
+    }).strict())
+}).partial().strict();
+/**
+ * Panelin `themeDataToProjectTheme(data, base)` semantiği: nesneler ÖZYİNELEMELİ birleşir,
+ * dizi ve ilkel değer yerine geçer, base'in tanınmayan anahtarları korunur. Böylece bir rengi
+ * değiştirmek preset'leri ve bileşen preset'lerini düşürmez.
+ */
+export function mergeTheme(base, patch) {
+    const result = { ...base };
+    for (const [key, value] of Object.entries(patch)) {
+        const current = result[key];
+        result[key] = isPlainObject(current) && isPlainObject(value)
+            ? mergeTheme(current, value)
+            : value;
+    }
+    return result;
+}
+/**
+ * Nokta yoluyla silme: `presets.kart`, `componentPresets.button.versions.V2`, `headingFontFamily`.
+ *
+ * `null` yazmak SİLME değildir — `prune` null'ı yanıttan düşürür ve platform onu kayda yazardı;
+ * silmenin açık bir kanalı olması bu yüzden şart. Bulunmayan yol hata değil, `missing`.
+ */
+export function unsetThemePaths(theme, paths) {
+    const result = structuredClone(theme);
+    const missing = [];
+    for (const path of paths) {
+        const segments = path.split('.').filter(segment => segment !== '');
+        let cursor = result;
+        let found = true;
+        for (const segment of segments.slice(0, -1)) {
+            const next = cursor[segment];
+            if (!isPlainObject(next)) {
+                found = false;
+                break;
+            }
+            cursor = next;
+        }
+        const last = segments[segments.length - 1];
+        if (!found || last === undefined || !Object.hasOwn(cursor, last)) {
+            missing.push(path);
+            continue;
+        }
+        delete cursor[last];
+    }
+    // Son girdisi silinen ADLI KAYIT boş bir kabuk bırakmaz: panel de son preset kaldırılınca
+    // anahtarı tamamen siliyor (`themeDataToProjectTheme`), ve `presets: {}` taşıyan bir kayıt
+    // "preset'leri var ama boş" gibi okunuyordu (ölçüldü 2026-09-15 canlı koşu).
+    for (const key of ['presets', 'componentPresets', 'componentStyles']) {
+        const value = result[key];
+        if (isPlainObject(value) && Object.keys(value).length === 0)
+            delete result[key];
+    }
+    return { theme: result, missing };
+}
+const LENGTH_FIELDS = ['fontSize', 'spacing', 'borderRadius'];
+/** Çıplak sayı ya da sayısal metin bir CSS uzunluğu DEĞİLDİR; panelin `appendPx`'i ile aynı kural. */
+function withPx(value) {
+    if (typeof value === 'number')
+        return `${value}px`;
+    if (typeof value !== 'string')
+        return undefined;
+    const text = value.trim();
+    return text !== '' && /^-?\d+(\.\d+)?$/.test(text) ? `${text}px` : undefined;
+}
+/**
+ * Kural yerine normalizasyon (08 §Kural yerine normalizasyon): türetilebilir olan düzeltilir,
+ * yalnız karar gerektiren şey lint'e kalır. Hepsi `gatewayNormalized` ile bildirilir.
+ */
+export function normalizeTheme(theme) {
+    const result = structuredClone(theme);
+    const fixes = [];
+    // N-1 — uzunluk alanları
+    for (const field of LENGTH_FIELDS) {
+        const fixed = withPx(result[field]);
+        if (fixed !== undefined) {
+            fixes.push(`${field}: ${JSON.stringify(result[field])} → '${fixed}' (CSS uzunluğu birimsiz yazılamaz)`);
+            result[field] = fixed;
+        }
+    }
+    if (isPlainObject(result.radiusScale)) {
+        const fixed = withPx(result.radiusScale.pill);
+        if (fixed !== undefined) {
+            fixes.push(`radiusScale.pill: ${JSON.stringify(result.radiusScale.pill)} → '${fixed}'`);
+            result.radiusScale.pill = fixed;
+        }
+    }
+    // N-2/N-3 — versiyon zarfı ve boşluk süzgeci
+    if (isPlainObject(result.componentPresets)) {
+        for (const [type, preset] of Object.entries(result.componentPresets)) {
+            if (!isPlainObject(preset) || !isPlainObject(preset.versions))
+                continue;
+            for (const [name, version] of Object.entries(preset.versions)) {
+                if (!isPlainObject(version))
+                    continue;
+                if (!isPlainObject(version.props)) {
+                    const { appearance, ...body } = version;
+                    preset.versions[name] = {
+                        props: Object.keys(body).length > 0 ? { style: body } : {},
+                        ...(appearance === undefined ? {} : { appearance })
+                    };
+                    if (Object.keys(body).length > 0) {
+                        fixes.push(`componentPresets.${type}.versions.${name}: düz CSS gövdesi { props: { style } } zarfına alındı — versiyon PROP varsayılanı taşır, stil onlardan biridir`);
+                    }
+                }
+                const wrapped = preset.versions[name];
+                if (isPlainObject(wrapped.appearance)) {
+                    const kept = Object.fromEntries(Object.entries(wrapped.appearance).filter(([key]) => SPACING_KEYS.includes(key)));
+                    const dropped = Object.keys(wrapped.appearance).filter(key => !SPACING_KEYS.includes(key));
+                    if (dropped.length > 0) {
+                        fixes.push(`componentPresets.${type}.versions.${name}.appearance: ${dropped.join(', ')} düşürüldü — zarf yalnız BOŞLUK taşır, ölçü/hizalama o örneğin ızgaradaki geometrisidir`);
+                    }
+                    if (Object.keys(kept).length > 0)
+                        wrapped.appearance = kept;
+                    else
+                        delete wrapped.appearance;
+                }
+            }
+        }
+    }
+    // N-4/N-5 — stil gövdelerinde kebab-case ve sızmış preset işaretleri
+    const styleBodies = [];
+    for (const key of ['presets', 'componentStyles']) {
+        if (!isPlainObject(result[key]))
+            continue;
+        for (const [name, body] of Object.entries(result[key])) {
+            if (isPlainObject(body))
+                styleBodies.push([`${key}.${name}`, body]);
+        }
+    }
+    if (isPlainObject(result.componentPresets)) {
+        for (const [type, preset] of Object.entries(result.componentPresets)) {
+            if (!isPlainObject(preset) || !isPlainObject(preset.versions))
+                continue;
+            for (const [name, version] of Object.entries(preset.versions)) {
+                const props = isPlainObject(version) ? version.props : undefined;
+                const style = isPlainObject(props) ? props.style : undefined;
+                if (isPlainObject(style))
+                    styleBodies.push([`componentPresets.${type}.versions.${name}.props.style`, style]);
+            }
+        }
+    }
+    for (const [label, body] of styleBodies) {
+        normalizeStyleKeys(body, label, fixes);
+        for (const marker of ['$preset', '$componentPreset']) {
+            if (!Object.hasOwn(body, marker))
+                continue;
+            delete body[marker];
+            fixes.push(`${label}: '${marker}' düşürüldü — DÜĞÜMÜN kaydıdır, tema stilinin parçası değil (çözümleyici zaten ayıklar)`);
+        }
+    }
+    return { theme: result, fixes };
+}
+/** Yazmanın DOKUNDUĞU yollar; `presets` ve `componentPresets` ad düzeyinde açılır. */
+export function diffThemePaths(base, next) {
+    const set = [];
+    const unset = [];
+    const baseRecord = base;
+    const nextRecord = next;
+    for (const key of new Set([...Object.keys(baseRecord), ...Object.keys(nextRecord)])) {
+        const before = baseRecord[key];
+        const after = nextRecord[key];
+        if (JSON.stringify(before) === JSON.stringify(after))
+            continue;
+        // Adlı kayıtlarda hangi PRESET'in değiştiği, "presets değişti"den çok daha bilgilendirici.
+        if ((key === 'presets' || key === 'componentPresets') && (isPlainObject(before) || isPlainObject(after))) {
+            const beforeEntries = isPlainObject(before) ? before : {};
+            const afterEntries = isPlainObject(after) ? after : {};
+            for (const name of new Set([...Object.keys(beforeEntries), ...Object.keys(afterEntries)])) {
+                if (JSON.stringify(beforeEntries[name]) === JSON.stringify(afterEntries[name]))
+                    continue;
+                if (Object.hasOwn(afterEntries, name))
+                    set.push(`${key}.${name}`);
+                else
+                    unset.push(`${key}.${name}`);
+            }
+            continue;
+        }
+        if (Object.hasOwn(nextRecord, key))
+            set.push(key);
+        else
+            unset.push(key);
+    }
+    return { set, unset };
+}
+/**
+ * Bir TİPİN tema tarafından verilen başlangıç değerleri (S-3).
+ *
+ * Studio'da bırakılan düğüm ham katalogdan değil, temanın varsayılan versiyonu KAPLANMIŞ
+ * katalogdan kurulur (`withThemeComponentDefaults`, `component.functions.ts`): prop'lar
+ * `definition.defaults`'un üstüne biner, boşluk ayrı bir `definition.appearance` alanına yazılır
+ * ve düğüm `style.$componentPreset` işaretini alır. `component_get`'in `defaults` alanı bunu
+ * GÖSTERMİYORDU, yani "yeni bir button ne ile başlar" sorusunun cevabı yanlıştı.
+ */
+export function componentPresetDefaults(theme, type) {
+    const preset = theme?.componentPresets?.[type];
+    if (!isPlainObject(preset))
+        return undefined;
+    const versions = isPlainObject(preset.versions) ? preset.versions : {};
+    const version = String(preset.defaultVersion ?? '');
+    const body = versions[version];
+    if (!isPlainObject(body))
+        return undefined;
+    const props = isPlainObject(body.props) ? body.props : {};
+    const appearance = isPlainObject(body.appearance) ? body.appearance : undefined;
+    return {
+        version,
+        props,
+        ...(appearance ? { appearance } : {}),
+        note: `Studio'da bu tipten bırakılan düğüm 'defaults' + BU değerlerle kurulur ve style.$componentPreset: '${version}' işaretini taşır. MCP'nin add_component'i ne katalog varsayılanını ne de bunu yazar — istediğiniz değeri düğüme açıkça verin. Tipin başlangıç değerini değiştirmek: theme_update(componentPresets.${type}).`
+    };
+}