jskelet 0.5.4 → 0.6.0

package/types/server/prewarm.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Isıtmanın canlı durumu. Dev araçları bunu okuyup ilerlemeyi gösterir;
+ * üretimde kimse okumazsa da maliyeti bir nesnedir.
+ */
+export declare const prewarmProgress: {
+    active: boolean;
+    done: number;
+    total: number;
+    ok: number;
+    failed: number;
+    /** @type {number | null} */
+    startedAt: number | null;
+    /** @type {number | null} */
+    finishedAt: number | null;
+    /**
+     * Denenen her yolun sonucu; dev panelindeki Prewarming sekmesi bunu listeler.
+     * @type {{ path: string, status: number, ms: number, bytes: number,
+     *   cache: string | null, error: string | null }[]}
+     */
+    entries: {
+        path: string;
+        status: number;
+        ms: number;
+        bytes: number;
+        cache: string | null;
+        error: string | null;
+    }[];
+};
+/**
+ * İstek ısıtma turunun kendi isteği mi? Yalnızca tur çalışırken ve istek
+ * ısıtmanın user-agent'ıyla geldiğinde doğru; gerçek trafiğin hataları her
+ * zaman loglanmaya devam eder.
+ *
+ * @param {{ get?: (name: string) => string | undefined } | null | undefined} req
+ * @returns {boolean}
+ */
+export declare function isPrewarmRequest(req: {
+    get?: (name: string) => string | undefined;
+} | null | undefined): boolean;
+/**
+ * Isıtma turuna ait bir uyarıyı loglamak yerine sayar.
+ *
+ * @param {string} message Gruplama anahtarı; yol adı içermemeli.
+ * @returns {boolean} `true` ise sayıldı, çağıran taraf loglamamalı.
+ */
+export declare function suppressForPrewarm(message: string): boolean;
+/**
+ * Bastırılan bir istek hatasını sayaca ekler. Yığın izi saklanmaz: özet
+ * satırının amacı "neyin bozulduğunu" göstermek, hatayı ayıklamak değil.
+ *
+ * @param {number} status
+ * @param {unknown} error
+ * @returns {void}
+ */
+export declare function notePrewarmError(status: number, error: unknown): void;
+/**
+ * Bir turda ısıtılacak dilimi seçer: önce `priority` eşleşenler, sonra
+ * kuyruğun sırası gelen parçası. Dışa açık olması bilinçli — sıralama ve
+ * rotasyon, tur çalışmadan doğrulanabilen tek davranış.
+ *
+ * @param {string[]} all
+ * @param {number} limit
+ * @param {boolean} rotate
+ * @returns {string[]}
+ */
+export declare function selectPrewarmPaths(all: string[], limit: number, rotate?: boolean): string[];
+/**
+ * @param {{ origin: string, quiet?: boolean, paths?: string[] }} options
+ *   `paths` verilirse hook çağrılmaz, yalnızca o yollar ısıtılır (dev
+ *   panelindeki "tekrar dene" bunu kullanır).
+ * @returns {Promise<{ ok: number, failed: number, total: number, elapsed: number }>}
+ */
+export declare function prewarm({ origin, quiet, paths: only }: {
+    origin: string;
+    quiet?: boolean;
+    paths?: string[];
+}): Promise<{
+    ok: number;
+    failed: number;
+    total: number;
+    elapsed: number;
+}>;
+/**
+ * HTML içindeki aynı-origin `<a href>` yollarını DOM sırasıyla (üstten alta)
+ * toplar. Speculation Rules ile aynı muafiyetler: `nofollow`, `_blank`,
+ * `data-no-prefetch`, `prewarmSkip`, `navigation.exclude`.
+ *
+ * @param {string} html
+ * @param {{ limit?: number, basePath?: string }} [options]
+ * @returns {string[]}
+ */
+export declare function extractSameOriginLinks(html: string, options?: {
+    limit?: number;
+    basePath?: string;
+}): string[];
+/**
+ * Ziyaret ısıtması açık mı? `PREWARM=0` her iki modu da keser.
+ *
+ * @returns {boolean}
+ */
+export declare function isOnVisitPrewarm(): boolean;
+/**
+ * Yanıt gövdesindeki linkleri soğuksa kuyruğa alır. İstek yolunu bloklamamak
+ * için `route()` bunu `queueMicrotask` ile çağırır.
+ *
+ * @param {string} html
+ * @param {{ path: string, req?: { get?: (name: string) => string | undefined,
+ *   headers?: Record<string, unknown> } }} context
+ * @returns {void}
+ */
+export declare function noteVisitWarm(html: string, context: {
+    path: string;
+    req?: {
+        get?: (name: string) => string | undefined;
+        headers?: Record<string, unknown>;
+    };
+}): void;
+/**
+ * Açılışta ısıtmayı tetikler. `listen` geri çağrısından çağrılır.
+ * `onVisit` modunda klasik zamanlayıcı yok; yine de erken-TTL invalidation
+ * drain'i çalışır — soft-bayatlayan sweeper'ın kuyruğu boşalmasın.
+ *
+ * @param {{ port: number }} options
+ * @returns {void}
+ */
+export declare function startPrewarm({ port }: {
+    port: number;
+}): void;

package/types/server/redis.d.ts

@@ -0,0 +1,163 @@
+export type RedisConfig = import('../config/index.js').RedisConfig;
+export type CacheEvent = {
+    type: string;
+    [key: string]: unknown;
+};
+/**
+ * Bağlantıyı kurar. `createApp()` config yüklendikten sonra bir kez çağırır.
+ *
+ * `ioredis` opsiyonel peer bağımlılık ve **uygulamanın** node_modules'ünden
+ * çözülür: framework `file:`/workspace bağlantısıyla kuruluysa düz bir
+ * `import "ioredis"` framework'ün kendi ağacına bakar.
+ *
+ * @param {import('../config/index.js').ResolvedConfig} config
+ * @returns {Promise<boolean>} Bağlantı kuruldu mu.
+ */
+export declare function connectRedis(config: import('../config/index.js').ResolvedConfig): Promise<boolean>;
+/**
+ * Önbellek olaylarına abone olur. Önbellek modülleri yükleme anında çağırır;
+ * bağlantı sonradan kurulsa da kayıt geçerli kalır.
+ *
+ * Dinleyici **yalnızca yerel** işi yapmalı: yeniden yayın yapan bir dinleyici
+ * iki node arasında sonsuz mesaj döngüsü üretir.
+ *
+ * @param {(event: CacheEvent) => void} listener
+ */
+export declare function onCacheEvent(listener: (event: CacheEvent) => void): void;
+/**
+ * Olayı diğer node'lara duyurur. Ateşle-unut: yayın hatası çağıranı
+ * etkilemez, yerel invalidation zaten yapıldı.
+ *
+ * @param {CacheEvent} event
+ */
+export declare function publishCacheEvent(event: CacheEvent): void;
+/**
+ * Bu tür için paylaşım açık mı. `html`/`data` ayrı ayrı kapatılabiliyor:
+ * veri önbelleğini paylaşmak neredeyse her zaman kazançlı, HTML gövdelerini
+ * paylaşmak girdi başına yüz kilobayt trafik demek.
+ *
+ * @param {"html" | "data"} kind
+ * @returns {boolean}
+ */
+export declare function redisShares(kind: "html" | "data"): boolean;
+/** @returns {boolean} */
+export declare function redisSharesEncoded(): boolean;
+/**
+ * @param {"html" | "data"} kind
+ * @param {string} key
+ * @returns {string}
+ */
+export declare function cacheKey(kind: "html" | "data", key: string): string;
+/**
+ * @param {string} key
+ * @returns {Promise<any | null>} Girdi yoksa, ayrıştırılamıyorsa ya da Redis
+ *   hata verirse `null` — hepsi "miss" sayılır.
+ */
+export declare function redisGetJson(key: string): Promise<any | null>;
+/**
+ * Ateşle-unut yazma. İsteğin yanıt yolunda beklenmez: HTML zaten L1'e
+ * yazıldı, Redis kopyası yalnızca diğer node'lar için.
+ *
+ * @param {string} key
+ * @param {unknown} value
+ * @param {number} ttlMs
+ */
+export declare function redisSetJson(key: string, value: unknown, ttlMs: number): void;
+/**
+ * @param {string[]} keys
+ */
+export declare function redisDrop(keys: string[]): void;
+/**
+ * Bir isim alanını tarar ve eşleşen anahtarları düşürür.
+ *
+ * `KEYS` **kullanılmaz**: tek komutta tüm keyspace'i tarayıp sunucuyu bloklar.
+ * `SCAN` kursoru parça parça döner; bu yüzden işlem atomik değil, ama
+ * invalidation'ın atomik olması gerekmiyor.
+ *
+ * @param {"html" | "data"} kind
+ * @param {(key: string) => boolean} [match] Anahtarın **önek sonrası** kısmına
+ *   uygulanır; verilmezse tür altındaki her şey düşer.
+ * @returns {Promise<number>} Düşürülen anahtar sayısı.
+ */
+export declare function redisDropMatching(kind: "html" | "data", match?: (key: string) => boolean): Promise<number>;
+/**
+ * Dev raporu için durum özeti. Bağlantı yoksa da güvenle çağrılabilir.
+ *
+ * @returns {{ enabled: boolean, connected: boolean, keyPrefix: string,
+ *   buildId: string, errors: number, bypassed: boolean }}
+ */
+export declare function getRedisStatus(): {
+    enabled: boolean;
+    connected: boolean;
+    keyPrefix: string;
+    buildId: string;
+    errors: number;
+    bypassed: boolean;
+};
+/**
+ * Bağlantının **nereye** kurulduğu ve hangi ayarlarla çalıştığı.
+ *
+ * Şifre asla dönmez: bağlantı URL'i `redis://user:pass@host` biçiminde
+ * olabiliyor ve panelin işi adresi göstermek, sırrı değil. Ayrıştırılamayan
+ * bir URL için adres `"custom"` olur — bozuk bir değer teşhis ucunu
+ * düşürmemeli.
+ *
+ * @returns {{ address: string, secure: boolean, db: string | null,
+ *   namespace: string, keyPrefix: string, html: boolean, data: boolean,
+ *   storeEncoded: boolean, events: boolean, commandTimeoutMs: number,
+ *   subscribed: boolean }}
+ */
+export declare function getRedisDetails(): {
+    address: string;
+    secure: boolean;
+    db: string | null;
+    namespace: string;
+    keyPrefix: string;
+    html: boolean;
+    data: boolean;
+    storeEncoded: boolean;
+    events: boolean;
+    commandTimeoutMs: number;
+    subscribed: boolean;
+};
+/**
+ * Paylaşımlı kademede gerçekten **ne durduğunu** sayar: tür başına anahtar
+ * sayısı ve sunucunun bildirdiği bellek kullanımı.
+ *
+ * Ayrı bir çağrı olması gerekiyor. Sayım `SCAN` turu demek ve panelin döküm
+ * ucu birkaç saniyede bir yenileniyor; her turda tüm keyspace'i taramak
+ * Redis'i teşhis uğruna yormak olurdu. Panel bunu düğmeye basınca çağırır.
+ *
+ * @returns {Promise<{ ok: boolean, html: number, data: number,
+ *   usedMemory: string | null, totalKeys: number | null }>}
+ */
+export declare function inspectRedis(): Promise<{
+    ok: boolean;
+    html: number;
+    data: number;
+    usedMemory: string | null;
+    totalKeys: number | null;
+}>;
+/**
+ * Bağlantıları kapatır. `SIGTERM` sonrası uçuştaki komutların bitmesi
+ * beklenir (`quit`), zorla kesilmez.
+ *
+ * @returns {Promise<void>}
+ */
+export declare function disconnectRedis(): Promise<void>;
+/**
+ * Testler için: sahte bir istemci enjekte eder. Gerçek bir Redis'e bağlanmadan
+ * serileştirme ve olay yollarının doğrulanabilmesi gerekiyor.
+ *
+ * @param {any} fake `null` → katman kapatılır.
+ * @param {Partial<RedisConfig>} [overrides]
+ */
+export declare function setRedisClientForTests(fake: any, overrides?: Partial<RedisConfig>): void;
+/**
+ * Testler için: abone kanalından gelmiş gibi olay besler. `originId`
+ * verilmezse uzak bir node varsayılır; kendi kimliğini taşıyan bir yayını
+ * olduğu gibi geri vermek de mümkün olmalı — eleme testi buna dayanıyor.
+ *
+ * @param {CacheEvent} event
+ */
+export declare function emitRemoteCacheEventForTests(event: CacheEvent): void;

package/types/server/render.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Uygulama geliştirirken bileşen dosyaları değişince kayıt yenilenmeli.
+ * Dev sunucusu süreci yeniden başlattığı için normalde gerekmez; gömülü
+ * kullanımlar (test, script) için dışa açık.
+ *
+ * @returns {void}
+ */
+export declare function resetRenderEngine(): void;
+/**
+ * Layout kullanmadan tek bir şablon render eder. Fragment/partial uçları
+ * ve e-posta şablonları bunu kullanır.
+ *
+ * Öncelik: derlenmiş `.jsk` → `.ejs`. İstek anında şablon derlenmez.
+ *
+ * @param {string} view `views/` altındaki yol, uzantısız (örn. "pages/home")
+ * @param {object} [data]
+ * @returns {Promise<string>}
+ */
+export declare function renderView(view: string, data?: object): Promise<string>;
+/**
+ * Sayfayı layout içinde render eder.
+ *
+ * @param {{ view: string, data?: object, metadata?: object, head?: string,
+ *   bodyClass?: string, entries?: string[], styles?: string[],
+ *   pathname?: string }} page
+ * @returns {Promise<string>}
+ */
+export declare function renderPage(page: {
+    view: string;
+    data?: object;
+    metadata?: object;
+    head?: string;
+    bodyClass?: string;
+    entries?: string[];
+    styles?: string[];
+    pathname?: string;
+}): Promise<string>;
+/**
+ * Controller'ı çalıştırıp yanıtı yazar; notFound/redirect kontrol akışını,
+ * HTML cache'ini ve hata yönetimini üstlenir.
+ *
+ * `private: true` kişiye özel sayfaları public cache yolundan tamamen ayırır:
+ * HTML cache devre dışı kalır, config'in `cache.html` deseni bu kararı
+ * ezemez, yanıt `no-store` ile ve ETag'siz gider. Dashboard tipi sayfalarda
+ * bu bayrak olmadan çalışmak, bir kullanıcının HTML'inin bir başkasına
+ * servis edilmesi anlamına gelir.
+ *
+ * @param {(ctx: { params: object, query: object, pathname: string,
+ *   req: import('express').Request }) => Promise<object>} controller
+ * @param {{ revalidate?: number, private?: boolean }} [options]
+ * @returns {import('express').RequestHandler}
+ */
+export declare function route(controller: (ctx: {
+    params: object;
+    query: object;
+    pathname: string;
+    req: import('express').Request;
+}) => Promise<object>, options?: {
+    revalidate?: number;
+    private?: boolean;
+}): import('express').RequestHandler;
+/**
+ * Layout'suz, asla cache'lenmeyen parça yanıtı.
+ *
+ * Fragment uçları (tablo sayfası, sekme paneli, canlı tazelenen kart) her
+ * projede elle yazılıyor ve `no-store` yazmayı unutmak sessiz bir sızıntıya
+ * dönüşüyor. Burada politika sabit: HTML cache'e hiç uğramaz, `no-store` ile
+ * ve ETag'siz gider.
+ *
+ * Hata durumunda tüm sayfa yerine küçük bir hata parçası döner: takas edilen
+ * bölge bir hata sayfasının tamamını içine almasın.
+ *
+ * @param {(ctx: { params: object, query: object, pathname: string,
+ *   req: import('express').Request }) => Promise<{ view: string, data?: object,
+ *   status?: number } | string>} controller
+ * @returns {import('express').RequestHandler}
+ */
+export declare function fragment(controller: (ctx: {
+    params: object;
+    query: object;
+    pathname: string;
+    req: import('express').Request;
+}) => Promise<{
+    view: string;
+    data?: object;
+    status?: number;
+} | string>): import('express').RequestHandler;
+export type Produced = {
+    html: string;
+    status: number;
+    degraded?: boolean;
+    storable?: boolean;
+    retryAfter?: number;
+};
+/**
+ * 404 sayfası. `renderStatusPage(404)` için kısayol; route dosyalarında en sık
+ * ihtiyaç duyulan durum bu olduğu için ayrı bir ad taşımaya devam ediyor.
+ *
+ * @returns {Promise<string>}
+ */
+export declare function renderNotFound(): Promise<string>;

package/types/server/router.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @param {import('express').Express} app
+ * @returns {Promise<number>} Bağlanan modül sayısı.
+ */
+export declare function registerRoutes(app: import('express').Express): Promise<number>;

package/types/server/status-page.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Durum koduna karşılık gelen sayfayı üretir. Hiçbir koşulda fırlatmaz:
+ * hata sayfasının kendisi patlarsa ziyaretçi boş yanıt görür, bu yüzden her
+ * başarısızlık gömülü HTML'e düşer.
+ *
+ * Development'ta 5xx yanıtları `hooks.error` ve gömülü 500 sayfasını atlar;
+ * yığın izini içeren bir teşhis sayfası döner. Production'da ayrıntı
+ * gösterilmez — sunucu içi ziyaretçiye açılmaz.
+ *
+ * @param {number} status
+ * @param {{ error?: unknown }} [options]
+ * @returns {Promise<string>}
+ */
+export declare function renderStatusPage(status: number, options?: {
+    error?: unknown;
+}): Promise<string>;
+/**
+ * Bir hatadan HTTP durum kodu çıkarır. Uygulama kodu `error.statusCode` ya da
+ * `error.status` ile kendi kodunu bildirebilir; tanınmayan her şey 500'dür.
+ *
+ * @param {unknown} error
+ * @returns {number}
+ */
+export declare function statusFromError(error: unknown): number;

package/types/server/upstream-limiter.d.ts

@@ -0,0 +1,123 @@
+export type HostState = {
+    host: string;
+    /**
+     * Config'te verilen tavan; AIMD bunun üstüne çıkmaz.
+     */
+    maxRate: number;
+    /**
+     * Azalmanın dibi; 0'a inip tamamen kilitlenmesin.
+     */
+    minRate: number;
+    /**
+     * Saniyedeki izin — AIMD bunu oynatır.
+     */
+    rate: number;
+    /**
+     * Kovanın boyu: kısa patlamalara verilen tolerans.
+     */
+    burst: number;
+    /**
+     * Aynı anda uçabilecek çağrı sayısı.
+     */
+    concurrency: number;
+    tokens: number;
+    refilledAt: number;
+    /**
+     * Uçuştaki çağrı.
+     */
+    active: number;
+    /**
+     * Boş yuva bekleyenler.
+     */
+    waiters: (() => void)[];
+    /**
+     * Admission sırası (FIFO).
+     */
+    chain: Promise<void>;
+    /**
+     * `Retry-After` boyunca kova tamamen durur.
+     */
+    blockedUntil: number;
+    consecutiveFailures: number;
+    /**
+     * Devre kesicinin açık kaldığı an.
+     */
+    bypassUntil: number;
+    /**
+     * Son AIMD kararının zamanı.
+     */
+    adjustedAt: number;
+    /**
+     * Kaç kez 429/503 görüldü (teşhis için).
+     */
+    throttled: number;
+    /**
+     * Devre kesici kaç çağrıyı hiç göndermedi.
+     */
+    rejected: number;
+};
+/**
+ * `createApp()` config yüklendikten sonra bir kez çağırır. Ayar değiştiğinde
+ * host durumları sıfırlanır: eski `maxRate`'e göre ayarlanmış bir `rate`
+ * yeni tavanın üstünde kalabilir.
+ *
+ * @param {Record<string, unknown> | undefined} config `cache().upstream`
+ * @returns {void}
+ */
+export declare function configureUpstreamLimiter(config: Record<string, unknown> | undefined): void;
+/**
+ * Çağrı için izin alır. `null` dönerse fren kapalı ya da host çözülemedi;
+ * `blocked` dönerse devre kesici açık ve çağrı hiç yapılmamalı.
+ *
+ * @param {string} url
+ * @returns {Promise<{ blocked: boolean, host: string, release: () => void } | null>}
+ */
+export declare function limitUpstream(url: string): Promise<{
+    blocked: boolean;
+    host: string;
+    release: () => void;
+} | null>;
+/**
+ * Yanıtın hıza etkisini işler. 429/503 hızı yarıya indirir ve `Retry-After`
+ * varsa kovayı o süre boyunca tamamen durdurur; başarı sayaçları sıfırlar.
+ *
+ * @param {string} host
+ * @param {number} status `0` → ağ hatası (yanıt gelmedi).
+ * @param {string | null} [retryAfter] `Retry-After` başlığı.
+ * @returns {void}
+ */
+export declare function noteUpstreamResponse(host: string, status: number, retryAfter?: string | null): void;
+/**
+ * Dev paneli ve teşhis için host başına durum. Fren kapalıysa boş dizi.
+ *
+ * @returns {{ host: string, rate: number, maxRate: number, concurrency: number,
+ *   active: number, throttled: number, rejected: number, bypassed: boolean,
+ *   blockedMs: number, bypassedMs: number }[]}
+ */
+export declare function getUpstreamLimiterStatus(): {
+    host: string;
+    rate: number;
+    maxRate: number;
+    concurrency: number;
+    active: number;
+    throttled: number;
+    rejected: number;
+    bypassed: boolean;
+    blockedMs: number;
+    bypassedMs: number;
+}[];
+/**
+ * Freni bekleten en uzun süre. Isıtma turunun tekrar denemesi bunu kullanıyor:
+ * sabit bir bekleme, kesici 10 saniye açıkken 2 saniye sonra tekrar denemek
+ * demekti — yani aynı 429'u peşin peşin almak.
+ *
+ * @returns {number} ms; fren kapalıysa ya da bekleyen bir şey yoksa 0.
+ */
+export declare function upstreamCooldownMs(): number;
+/**
+ * Testler için: ayarları verip tüm host durumlarını sıfırlar.
+ *
+ * @param {Record<string, unknown>} [config]
+ * @returns {void}
+ */
+export declare function resetUpstreamLimiterForTests(config?: Record<string, unknown>): void;

package/types/server/upstream-tracking.d.ts

@@ -0,0 +1,42 @@
+export type UpstreamFailure = {
+    status: number;
+    path: string;
+};
+/**
+ * @param {UpstreamFailure} failure
+ * @returns {void}
+ */
+export declare function reportUpstreamFailure(failure: UpstreamFailure): void;
+/**
+ * @param {number} status
+ * @returns {boolean}
+ */
+export declare function isTransientStatus(status: number): boolean;
+/**
+ * `globalThis.fetch`i sarıp **geçici** upstream hatalarını kendiliğinden
+ * bildirir.
+ *
+ * Gerekçesi pratik: `reportUpstreamFailure()` sözleşmesi uygulamanın HTTP
+ * istemcisine bir satır eklemeyi gerektiriyor ve o satır yazılmadığında
+ * framework rate limit'i hiç göremiyor — veri gelmediği için `notFound()`
+ * çağıran sayfa 404 olarak servis ediliyordu. Otomatik izleme bu bilgiyi
+ * varsayılan hâle getirir; elle çağrı hâlâ geçerli ve tekilleştirilir.
+ *
+ * Yalnızca geçici durumlar bildirilir. `404`/`403` gibi deterministik
+ * cevaplar birçok API'de "böyle bir kayıt yok" anlamına geliyor ve onları
+ * otomatik olarak "eksik veri" saymak her sayfada yanlış uyarı üretirdi.
+ *
+ * Kendi sunucumuza yapılan istekler atlanır: ısıtma turu ve sağlık kontrolü
+ * upstream değil.
+ *
+ * @returns {void}
+ */
+export declare function trackUpstreamFetch(): void;
+/**
+ * @param {() => T} run
+ * @returns {T}
+ * @template T
+ */
+export declare function withUpstreamTracking<T>(run: () => T): T;
+/** @returns {UpstreamFailure[]} */
+export declare function getUpstreamFailures(): UpstreamFailure[];

package/types/shared/cookie-domain.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Paylaşımlı cookie Domain seçimi — sunucu ve istemci aynı kuralları kullanır.
+ *
+ * `brand.sharedCookieRoots` örn. `[".investvio.com", ".localhost"]`.
+ * Host bu köklerden birine uyuyorsa Domain olarak o kök yazılır.
+ */
+/**
+ * @param {string} host Host veya Host:port.
+ * @returns {string} Lowercase, portsuz.
+ */
+export declare function stripHostPort(host: string): string;
+/**
+ * Kökü `Domain=` biçimine getirir (başında nokta).
+ *
+ * @param {unknown} root
+ * @returns {string | null}
+ */
+export declare function normalizeCookieRoot(root: unknown): string | null;
+/**
+ * @param {string} hostname Portsuz hostname.
+ * @param {Iterable<string>} roots `brand.sharedCookieRoots`.
+ * @returns {string | null} `Domain` değeri (başında nokta) ya da eşleşme yoksa null.
+ */
+export declare function resolveSharedCookieDomain(hostname: string, roots: Iterable<string>): string | null;
+/**
+ * Paylaşımlı cookie için önerilen üst sınır. JWT / büyük token buraya
+ * sığmaz — kısa session id koyun; aksi halde handoff veya host-only cookie.
+ */
+export declare const SHARED_COOKIE_WARN_BYTES = 512;

package/types/templates/layout.render.d.ts

@@ -0,0 +1,7 @@
+/** @generated by scripts/compile-framework-layout.mjs — do not edit */
+/**
+ * @param {Record<string, unknown>} data
+ * @param {Record<string, any>} helpers
+ * @returns {string}
+ */
+export declare function render(data: Record<string, unknown>, helpers: Record<string, any>): string;

package/types/version.d.mts

@@ -0,0 +1,10 @@
+/** @type {string} */
+export declare const FRAMEWORK_VERSION: string;
+/** Paket adı: sürüm kontrolü hangi kayıt defteri girdisine bakacağını buradan bilir. */
+export declare const FRAMEWORK_PACKAGE: any;
+/** Künye alanları: yönetim panelinin footer'ı bunları basıyor. */
+export declare const FRAMEWORK_LICENSE: any;
+/** @type {string} */
+export declare const FRAMEWORK_NODE_RANGE: string;
+/** @type {string} */
+export declare const FRAMEWORK_HOMEPAGE: string;

package/types/views/components/loader.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @param {string | string[]} dirs Tek dizin veya çoklu kök (feature/shared).
+ * @returns {Promise<Record<string, unknown>>}
+ */
+export declare function loadComponents(dirs: string | string[]): Promise<Record<string, unknown>>;

package/types/views/helpers/html.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Metin içeriği ve attribute değerleri için kaçış.
+ * @param {unknown} value
+ * @returns {string}
+ */
+export declare function esc(value: unknown): string;
+/**
+ * `<script type="application/ld+json">` gövdesi için güvenli JSON.
+ * `</script`, `<!--` ve U+2028/2029 kaçırılır.
+ * @param {unknown} value
+ * @returns {string}
+ */
+export declare function jsonScript(value: unknown): string;
+/**
+ * Attribute nesnesini string'e çevirir. `false`/`null`/`undefined` atlanır,
+ * `true` boolean attribute olarak yazılır.
+ * @param {Record<string, unknown>} attrs
+ * @returns {string}
+ */
+export declare function attrs(attrs: Record<string, unknown>): string;
+/**
+ * `clsx` karşılığı — koşullu sınıf birleştirme, çakışma çözümü yok.
+ * @param {...unknown} inputs
+ * @returns {string}
+ */
+export declare function cx(...inputs: unknown[]): string;
+/**
+ * `lib/ui/cn.js` ile aynı davranış: birleştir, sonra Tailwind çakışmalarını çöz.
+ *
+ * `tailwind-merge` çalışma zamanı bağımlılığı olarak korunur çünkü sınıf
+ * hesabı **yalnızca sunucuda** yapılır — client bundle'a hiç girmez, dolayısıyla
+ * sayfa ağırlığına etkisi yoktur. Elle yazılmış bir grup tablosu ise
+ * `border-2` + `border-transparent` gibi genişlik/renk çiftlerini birbirine
+ * karıştırıp sınıf düşürdüğü için görsel regresyon üretiyordu.
+ *
+ * @param {...unknown} inputs
+ * @returns {string}
+ */
+export declare function cn(...inputs: unknown[]): string;