jskelet 0.5.2 → 0.5.4

package/CHANGELOG.md

@@ -10,6 +10,29 @@ one is listed under a **Breaking** heading.
 
 ### Added
 
+- Shared cross-subdomain cookies: `brand.sharedCookieRoots` plus
+  `writeSharedCookie` / `clearSharedCookie` on server (`jskelet/cookies`) and
+  client (`jskelet/client`). `Secure` follows https / `x-forwarded-proto` (not
+  `NODE_ENV`); the client read-back fails into handoff when the browser rejects
+  `Domain`. Optional `auth.crossSubdomainHandoff` mounts
+  `POST /_jskelet/auth/handoff` (one-time ticket → `?handoff=`) and documents a
+  `window.name` bridge. Large tokens are refused — put a short session id in the
+  cookie, not a JWT.
+- HTML cache key vary (`cache().vary`): `host: true` adds the public Host
+  (`x-forwarded-host` or `Host`, lowercase, no port) as `h=…|` before the path;
+  optional `headers` and `fn(req)` add further segments. Required on host-based
+  locale sites so one locale's HTML is not served on another. Classic prewarm
+  accepts `prewarm.origins` for multi-host warming when vary is on.
+
+### Changed
+
+- Marketing example visual language: darker ink canvas, solid cyan primary
+  CTAs, cyan-only glow/grid (indigo accents removed), and a measured trust
+  bar on the homepage (payload gzip, Node, license, zero web fonts) instead
+  of the marquee.
+
+### Added
+
 - Dynamic Open Graph images (Next.js `ImageResponse` / `opengraph-image`):
   `ogImage`, `sendOgImage`, `ogHandler`, and `ImageResponse` turn card fields or
   raw SVG into PNG when `sharp` is installed (SVG fallback otherwise). Wired in

package/docs/06-cache.md

@@ -43,8 +43,9 @@ sayfa da ilk ziyaretçide milisaniyeler içinde üretilir ve kota harcamaz.
 ## Public ve kişiye özel ayrımı
 
 Bu belgedeki her şey **herkese aynı gidebilen** HTML için geçerli. Cache
-anahtarında kimlik yok (yalnızca yol + query), yani önbellekteki bir sayfa onu
-ilk isteyen kişinin değil, o yolun cevabıdır.
+anahtarında kimlik yok (yalnızca yol + query + isteğe bağlı `vary`); yani
+önbellekteki bir sayfa onu ilk isteyen kişinin değil, o yolun (ve vary
+parçalarının) cevabıdır.
 
 Kullanıcıya bağlı bir sayfa bu yüzden ayrı bir yoldan geçer:
 
@@ -110,13 +111,14 @@ saklayabiliyordu.
 ## Cache anahtarı
 
 ```
-`${yol}?${izin verilen query parametreleri, sıralı}`
+`${varyPrefix}${yol}?${izin verilen query parametreleri, sıralı}`
 ```
 
-Query'siz bir istek için anahtar yalnızca yoldur. **Query parametresi taşıyan
-istek varsayılan olarak dinamiktir**: önbelleğe hiç girmez ve `private,
-no-store` ile gider. Bir yolun bütün varyantlarını cache'lemek `?utm_source=…`
-gibi sonsuz sayıda anahtar üretiyor ve 500 girdilik store'da LRU, gerçek
+`varyPrefix` varsayılan olarak boştur. Query'siz bir istek için anahtar
+`${varyPrefix}${yol}?` biçimindedir. **Query parametresi taşıyan istek
+varsayılan olarak dinamiktir**: önbelleğe hiç girmez ve `private, no-store`
+ile gider. Bir yolun bütün varyantlarını cache'lemek `?utm_source=…` gibi
+sonsuz sayıda anahtar üretiyor ve 500 girdilik store'da LRU, gerçek
 sayfaları kampanya varyantları için dışarı atıyor.
 
 Hangi parametrenin çıktıyı gerçekten değiştirdiğini uygulama bildirir —
@@ -135,6 +137,48 @@ Bir desen `true` ile eşlenirse bütün parametreler anahtara girer (dikkat: gir
 sayısını sınırlayan tek şey `maxEntries` olur), `[]` ile eşlenirse query tamamen
 yok sayılır. Ayrıntı: [07-yapilandirma.md](./07-yapilandirma.md).
 
+### Host / locale: `cache().vary`
+
+CDN zaten tam URL ile ayırır; asıl risk **origin L1** ve Redis HTML anahtarıdır.
+Host'tan locale üreten sitelerde (`tr.example.com` / `en.example.com`) vary
+olmadan ilk locale'in HTML'i diğer host'a servis edilir — Express 5'te istek
+nesnesine locale yazmak kırılgan bir kaçış yoludur.
+
+```js
+cache: () => ({
+  html: { "/": 300, "/instruments/:slug": 300 },
+  vary: {
+    // true → public Host (x-forwarded-host || host), lowercase, portsuz
+    host: true,
+    // veya özel:
+    // headers: ["x-locale"],
+    // fn: (req) => req.hostname.startsWith("tr.") ? "l=tr" : "l=en",
+  },
+}),
+```
+
+Örnek anahtarlar: `h=tr.investvio.com|/instruments/aapl?`,
+`h=tr.example.com&l=tr|/…?`.
+
+| Alan | Tip | Anlamı |
+| --- | --- | --- |
+| `host` | `boolean` | Public Host'u `h=…` olarak anahtara ekler |
+| `headers` | `string[]` | Verilen istek başlıklarını (`ad=değer`) ekler |
+| `fn` | `(req) => string \| null` | Dönüş değeri bir segment olarak eklenir (tam kontrol) |
+
+**Prewarm:** varsayılan ısıtma `http://127.0.0.1:<port>` üzerinden gider. 
+`vary.host` açıksa bu yalnızca loopback anahtarını ısıtır; locale sitelerinde
+çoklu origin gerekir:
+
+```js
+prewarm: {
+  origins: ["http://localhost", "http://tr.localhost"],
+},
+```
+
+Port yazılmazsa dinleme portu eklenir. `onVisit` modunda ısıtma, vary açıkken
+ziyaretçinin `Host` başlığını kullanır.
+
 ## Stale-while-revalidate
 
 Girdi yapısı:
@@ -771,7 +815,7 @@ her istek ağ zaman aşımı beklemez.
 ### Anahtar düzeni
 
 ```
-_jskelet:{namespace}:{buildId}:html:{yol}?{query}
+_jskelet:{namespace}:{buildId}:html:{vary|}{yol}?{query}
 _jskelet:{namespace}:{buildId}:data:{anahtar}
 _jskelet:{namespace}:events
 ```
@@ -1074,9 +1118,12 @@ da trafik geldikçe (`onVisit`) yapılır. Kazanç aynı — tıklanan / komşu
 soğuk render'ı beklemez — fakat veri dondurulmaz; her girdi route'un
 `revalidate` süresiyle yaşlanır ve stale-while-revalidate ile arkada tazelenir.
 
-Isıtma **gerçek HTTP istekleriyle** yapılır (`http://127.0.0.1:<port>`), çünkü
-cache anahtarı, sıkıştırma ve middleware zinciri normal trafikle bire bir aynı
-olsun.
+Isıtma **gerçek HTTP istekleriyle** yapılır (`http://127.0.0.1:<port>` ya da
+`cache().prewarm.origins`), çünkü cache anahtarı, sıkıştırma ve middleware
+zinciri normal trafikle bire bir aynı olsun. `vary.host` açıksa varsayılan
+loopback yalnızca o host'un anahtarını ısıtır — locale sitelerinde
+`origins: ["http://localhost", "http://tr.localhost"]` gibi çoklu origin
+gerekir.
 
 İki mod **karşılıklı dışlayıcıdır**. `cache().prewarm.onVisit` açıksa klasik
 alanlar (`max`, `priority`, `rotate`, `intervalSeconds`, …) ve
@@ -1336,6 +1383,10 @@ turunun gerçekten `MISS` → önbellek doldurup doldurmadığını buradan gör
   fazla `revalidate` + bir tazeleme turudur.
 - **Önbellek şişiyor.** Query parametreleri anahtara girdiği için kampanya
   parametreleri girdi çoğaltıyor olabilir.
+- **Yanlış dil / host HTML'i geliyor.** Host'tan locale üreten bir sitede
+  `cache().vary.host: true` yoksa ilk locale'in HTML'i diğer host'a servis
+  edilir. Prewarm yalnızca `127.0.0.1` ile ısınıyorsa `prewarm.origins` ile
+  locale host'larını ekleyin.
 - **Isıtma hiç çalışmıyor.** Klasik modda `hooks.prewarmPaths` tanımlı değil,
   `PREWARM=0` ayarlı ya da `cache().prewarm.enabled === false`. `onVisit`
   modunda `listen` sonrası logda `onVisit mode` satırını ve public cache'li

package/docs/07-yapilandirma.md

@@ -186,14 +186,38 @@ birleştirilir.
 | `prewarmUserAgent` | `string` | `"jskelet-prewarm"` | Isıtma isteklerinin UA'sı; dev paneli bunu filtreler |
 | `devTokenCookie` | `string` | `"dev_token"` | Dev gate'in çerez ve query parametresi adı |
 | `lang` | `string` | — | `<html lang>` varsayılanı. Verilmezse layout `"en"` kullanır. |
+| `sharedCookieRoots` | `string[]` | `[]` | Paylaşımlı cookie Domain kökleri (örn. `.investvio.com`, `.localhost`). [12](./12-panel-ve-oturum.md) |
 
 `lang` için öncelik sırası: `hooks.layoutContext()` → `lang` **>** `brand.lang`
 **>** `"en"`.
 
 ```js
-brand: { lang: "tr", poweredBy: "Örnek", cacheHeader: "X-Ornek-Cache" }
+brand: {
+  lang: "tr",
+  poweredBy: "Örnek",
+  sharedCookieRoots: [".investvio.com", ".localhost"],
+}
 ```
 
+## `auth`
+
+**Tip:** `object` — **Varsayılan:** `{ crossSubdomainHandoff: false }`
+
+Kimlik framework'te yok; bu bölüm yalnızca alt alan adları arasında kısa
+session id taşımak için handoff köprüsünü açar.
+
+| Alan | Tip | Varsayılan | Anlamı |
+| --- | --- | --- | --- |
+| `crossSubdomainHandoff` | `boolean \| object` | `false` | `true` veya `{ ttlSeconds?, path?, maxValueBytes? }` → `POST /_jskelet/auth/handoff` + `?handoff=` redeem |
+
+```js
+auth: {
+  crossSubdomainHandoff: { ttlSeconds: 60 },
+},
+```
+
+Ayrıntı ve `window.name` yedeği: [12-panel-ve-oturum.md](./12-panel-ve-oturum.md).
+
 ## `layout`
 
 **Tip:** `string` — **Varsayılan:** yok (otomatik çözüm)
@@ -614,9 +638,9 @@ Ayrıntı: [03-routing.md](./03-routing.md).
 ## `cache()`
 
 **Tip:**
-`() => { html?: Record<string, number>, query?: Record<string, string[] | true>, maxEntries?: number, data?: object, trackUpstream?: boolean, trackDependencies?: boolean, transientRetry?: object | false, upstream?: object, redis?: object, prewarm?: object }` —
+`() => { html?: Record<string, number>, query?: Record<string, string[] | true>, vary?: { host?: boolean, headers?: string[], fn?: (req) => string | null }, maxEntries?: number, data?: object, trackUpstream?: boolean, trackDependencies?: boolean, transientRetry?: object | false, upstream?: object, redis?: object, prewarm?: object }` —
 **Varsayılan:**
-`{ html: {}, query: {}, maxEntries: 500, data: { maxEntries: 10000, staleFactor: 10 }, trackUpstream: true, trackDependencies: true, transientRetry: { attempts: 1, delayMs: 300 }, upstream: { rate: 0 }, redis: { enabled: false }, prewarm: { enabled: true, max: 400, intervalSeconds: 0 } }`
+`{ html: {}, query: {}, vary: { host: false }, maxEntries: 500, data: { maxEntries: 10000, staleFactor: 10 }, trackUpstream: true, trackDependencies: true, transientRetry: { attempts: 1, delayMs: 300 }, upstream: { rate: 0 }, redis: { enabled: false }, prewarm: { enabled: true, max: 400, intervalSeconds: 0, origins: [] } }`
 
 ### `cache().html`
 
@@ -671,6 +695,30 @@ Parametreler anahtara **sıralı** yazılır: `?a=1&b=2` ile `?b=2&a=1` aynı gi
 paylaşır. `route(fn, { private: true })` bu bölümden etkilenmez; private route
 hiçbir koşulda cache'lenmez.
 
+### `cache().vary`
+
+HTML cache anahtarına query allowlist'ten **bağımsız** sabit parçalar ekler.
+Host'tan locale üreten sitelerde `host: true` **zorunlu**; aksi halde ilk
+locale'in HTML'i diğer host'a servis edilir. CDN zaten tam URL ile ayırır —
+bu ayar origin L1 ve Redis HTML anahtarı içindir.
+
+```js
+vary: {
+  host: true, // h=tr.example.com|…
+  // headers: ["x-locale"],
+  // fn: (req) => req.hostname.startsWith("tr.") ? "l=tr" : "l=en",
+}
+```
+
+| Alan | Tip | Varsayılan | Anlamı |
+| --- | --- | --- | --- |
+| `host` | `boolean` | `false` | Public Host (`x-forwarded-host` yoksa `Host`), lowercase, portsuz → `h=…` |
+| `headers` | `string[]` | `[]` | İstek başlıkları `ad=değer` olarak eklenir |
+| `fn` | `(req) => string \| null` | — | Dönüş bir segment olarak eklenir |
+
+Anahtar biçimi: `${vary}|${yol}?${query}` (vary yoksa önek yok). Ayrıntı:
+[06-cache.md](./06-cache.md).
+
 ### `cache().maxEntries`
 
 **Tip:** `number` — **Varsayılan:** `500`
@@ -900,6 +948,7 @@ sayfadaki linkler). Birlikte verilemez — config yüklenirken hata.
 | `intervalSeconds` | `number` | `0` | 0'dan büyükse tur periyodik tekrarlanır |
 | `rotate` | `boolean` | `true` | Liste `max`'tan uzunsa periyodik turlar kaldığı yerden devam eder |
 | `priority` | `(string \| RegExp)[]` | `[]` | Isıtma sırası; eşleşen yollar her turda başa alınır |
+| `origins` | `string[]` | `[]` | Klasik turda ısıtılacak origin'ler. Boşsa `http://127.0.0.1:<port>`. `vary.host` açıksa locale host'ları buraya yazın |
 
 `priority` iki biçim kabul eder: config'in her yerinde geçerli olan desen
 sözdizimi ve doğrudan `RegExp`. Önce yazılan önce ısınır.
@@ -909,6 +958,8 @@ prewarm: {
   max: 500,
   rps: 4,
   intervalSeconds: 300,
+  // vary.host açıksa loopback tek başına yetmez:
+  origins: ["http://localhost", "http://tr.localhost"],
   priority: [
     "/",                     // ana sayfa
     "/piyasalar/:path*",      // tüm piyasa bölümü

package/docs/12-panel-ve-oturum.md

@@ -129,6 +129,94 @@ kapatıyor — cookie çapraz site POST'larında hiç gönderilmiyor.
 Cookie **şifrelenmiyor**, imzalanıyor. Değer okunabilir; gizli kalması gereken
 veriyi değil, onun kimliğini koyun.
 
+## Alt alan adları: paylaşımlı cookie
+
+Host tabanlı i18n (`tr.example.com` / `en.example.com`) oturumu alt alanlar
+arasında paylaşmak ister. Çözüm **kısa session id** + isteğe bağlı
+`Domain=.example.com` — JWT veya büyük access token paylaşımlı cookie'ye
+konmaz (`large token ≠ shared cookie`).
+
+```js
+// jskelet.config.mjs
+export default {
+  brand: {
+    sharedCookieRoots: [".investvio.com", ".localhost"],
+  },
+  auth: {
+    crossSubdomainHandoff: true, // POST /_jskelet/auth/handoff
+  },
+};
+```
+
+### Sunucu
+
+```js
+import { writeSharedCookie } from "jskelet/cookies";
+
+export function startSession(res, req, sessionId) {
+  const result = writeSharedCookie(res, "sid", sessionId, {
+    req,
+    maxAge: 60 * 60 * 8,
+  });
+  // result.ok === false → result.handoff; istemci handoff denemeli
+  return result;
+}
+```
+
+`Secure` **protokole** bakılır (`https` / `x-forwarded-proto`), `NODE_ENV`'e
+değil. Domain, isteğin Host'u `sharedCookieRoots` ile eşleşince yazılır.
+Değer ~512 baytı aşarsa yazım reddedilir ve `handoff: true` döner.
+
+### İstemci
+
+```js
+import {
+  writeSharedCookie,
+  createHandoffUrl,
+  handoffViaWindowName,
+  consumeWindowNameHandoff,
+} from "jskelet/client";
+
+const result = writeSharedCookie("sid", sessionId, {
+  roots: [".investvio.com", ".localhost"],
+  maxAge: 60 * 60 * 8,
+});
+
+if (!result.ok && result.handoff) {
+  const url = await createHandoffUrl({
+    name: "sid",
+    value: sessionId,
+    next: "https://tr.investvio.com/panel",
+  });
+  if (url) location.assign(url);
+  else handoffViaWindowName("https://tr.investvio.com/panel", {
+    name: "sid",
+    value: sessionId,
+  });
+}
+
+// Hedef host'ta (layout / island bootstrap):
+consumeWindowNameHandoff();
+```
+
+`roots` verilmezse `<html data-jskelet-cookie-roots=".investvio.com,.localhost">`
+okunur. Yazımdan sonra **read-back** yapılır; tarayıcı Domain'i reddettiyse
+`handoff: true`.
+
+### Handoff bileti
+
+`auth.crossSubdomainHandoff` açıkken:
+
+1. `POST /_jskelet/auth/handoff` `{ name, value, next }` → `{ url }` (`?handoff=` ekli)
+2. Hedef host'ta GET middleware bileti tek kullanımlık tüketir, cookie yazar
+   (önce shared Domain, olmazsa host-only), `handoff` query'siz 303
+
+`next` yalnızca aynı `sharedCookieRoots` altındaki host'lara izinli. Bilet
+~60 sn, süreç belleğinde. JWT URL'ye konmaz.
+
+`window.name` köprüsü cookie'siz yedek: kaynakta `handoffViaWindowName`,
+hedeefte `consumeWindowNameHandoff`.
+
 ## CSRF
 
 Gövdeyi framework ayrıştırıyor (`express.urlencoded` + `express.json`), yani

package/docs/en/06-caching.md

@@ -46,9 +46,9 @@ milliseconds on the first visit, and spends no quota.
 ## Public versus per-visitor
 
 Everything in this document applies to HTML that **can go to everyone
-unchanged**. There is no identity in the cache key (only path + query), so a
-page in the cache is the answer for that path, not the answer for whoever asked
-for it first.
+unchanged**. There is no identity in the cache key (only path + query + optional
+`vary`), so a page in the cache is the answer for that path (and vary parts),
+not the answer for whoever asked for it first.
 
 A page that depends on the user therefore takes a separate path:
 
@@ -117,14 +117,15 @@ The cache also only kicks in for `GET` requests.
 ## The cache key
 
 ```
-`${path}?${the allowed query parameters, sorted}`
+`${varyPrefix}${path}?${the allowed query parameters, sorted}`
 ```
 
-For a request without a query the key is just the path. **A request that carries
-a query parameter is dynamic by default**: it never enters the cache and is sent
-with `private, no-store`. Caching every variant of a path mints an unbounded
-number of keys (`?utm_source=…` and friends), and in a 500-entry store LRU then
-evicts the real pages in favour of campaign variants.
+`varyPrefix` is empty by default. For a request without a query the key is
+`${varyPrefix}${path}?`. **A request that carries a query parameter is dynamic
+by default**: it never enters the cache and is sent with `private, no-store`.
+Caching every variant of a path mints an unbounded number of keys
+(`?utm_source=…` and friends), and in a 500-entry store LRU then evicts the
+real pages in favour of campaign variants.
 
 Which parameter actually changes the output is declared by the application, in
 `jskelet.config.mjs` → `cache().query`:
@@ -143,6 +144,49 @@ the key (careful: nothing but `maxEntries` then bounds the entry count), and one
 mapped to `[]` ignores the query entirely. Details:
 [07-configuration.md](./07-configuration.md).
 
+### Host / locale: `cache().vary`
+
+A CDN already separates by full URL; the real risk is the **origin L1** and the
+Redis HTML key. On sites that derive locale from the host
+(`tr.example.com` / `en.example.com`), without vary the first locale's HTML is
+served to the other host — mutating the request object for locale is a fragile
+workaround under Express 5.
+
+```js
+cache: () => ({
+  html: { "/": 300, "/instruments/:slug": 300 },
+  vary: {
+    // true → public Host (x-forwarded-host || host), lowercase, no port
+    host: true,
+    // or custom:
+    // headers: ["x-locale"],
+    // fn: (req) => req.hostname.startsWith("tr.") ? "l=tr" : "l=en",
+  },
+}),
+```
+
+Example keys: `h=tr.investvio.com|/instruments/aapl?`,
+`h=tr.example.com&l=tr|/…?`.
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `host` | `boolean` | Adds the public Host as `h=…` |
+| `headers` | `string[]` | Adds the given request headers as `name=value` |
+| `fn` | `(req) => string \| null` | Appends the return value as a segment (full control) |
+
+**Prewarm:** the default warm-up goes through `http://127.0.0.1:<port>`. With
+`vary.host` that only warms the loopback key; locale sites need multiple
+origins:
+
+```js
+prewarm: {
+  origins: ["http://localhost", "http://tr.localhost"],
+},
+```
+
+If no port is written, the listen port is added. In `onVisit` mode, when vary
+is on, warming uses the visitor's `Host` header.
+
 ## Stale-while-revalidate
 
 The entry structure:
@@ -788,7 +832,7 @@ five consecutive failures, so requests do not each wait for a network timeout.
 ### Key layout
 
 ```
-_jskelet:{namespace}:{buildId}:html:{path}?{query}
+_jskelet:{namespace}:{buildId}:html:{vary|}{path}?{query}
 _jskelet:{namespace}:{buildId}:data:{key}
 _jskelet:{namespace}:events
 ```
@@ -1075,8 +1119,11 @@ but the data is not frozen; every entry ages with the route's `revalidate` and
 is refreshed in the background with stale-while-revalidate.
 
 The warm-up is done with **real HTTP requests**
-(`http://127.0.0.1:<port>`), so that the cache key, the compression and the
-middleware chain are exactly the same as with normal traffic.
+(`http://127.0.0.1:<port>` or `cache().prewarm.origins`), so that the cache key,
+the compression and the middleware chain are exactly the same as with normal
+traffic. With `vary.host`, the default loopback only warms that host's key —
+locale sites need multiple origins such as
+`origins: ["http://localhost", "http://tr.localhost"]`.
 
 The two modes are **mutually exclusive**. If `cache().prewarm.onVisit` is on,
 classic fields (`max`, `priority`, `rotate`, `intervalSeconds`, …) and
@@ -1339,6 +1386,10 @@ filled the cache.
   lag is at most `revalidate` + one refresh round.
 - **The cache is bloating.** Because query parameters go into the key, campaign
   parameters may be multiplying entries.
+- **Wrong language / host HTML.** On a site that derives locale from the host,
+  without `cache().vary.host: true` the first locale's HTML is served to the
+  other host. If prewarm only hits `127.0.0.1`, add the locale hosts via
+  `prewarm.origins`.
 - **The warm-up never runs.** In classic mode `hooks.prewarmPaths` is not
   defined, `PREWARM=0` is set, or `cache().prewarm.enabled === false`. In
   `onVisit` mode check the `onVisit mode` log line after `listen` and that a

package/docs/en/07-configuration.md

@@ -191,14 +191,39 @@ shallow-merged with the defaults.
 | `prewarmUserAgent` | `string` | `"jskelet-prewarm"` | UA of prewarm requests; the dev panel filters on it |
 | `devTokenCookie` | `string` | `"dev_token"` | Name of the dev gate's cookie and query parameter |
 | `lang` | `string` | — | Default for `<html lang>`. If not given, the layout uses `"en"`. |
+| `sharedCookieRoots` | `string[]` | `[]` | Shared cookie Domain roots (e.g. `.investvio.com`, `.localhost`). [12](./12-dashboards-and-sessions.md) |
 
 Precedence for `lang`: `hooks.layoutContext()` → `lang` **>** `brand.lang`
 **>** `"en"`.
 
 ```js
-brand: { lang: "tr", poweredBy: "Example", cacheHeader: "X-Example-Cache" }
+brand: {
+  lang: "tr",
+  poweredBy: "Example",
+  sharedCookieRoots: [".investvio.com", ".localhost"],
+}
 ```
 
+## `auth`
+
+**Type:** `object` — **Default:** `{ crossSubdomainHandoff: false }`
+
+The framework does not provide identity; this section only opens the
+cross-subdomain handoff bridge for a short session id.
+
+| Field | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `crossSubdomainHandoff` | `boolean \| object` | `false` | `true` or `{ ttlSeconds?, path?, maxValueBytes? }` → `POST /_jskelet/auth/handoff` + `?handoff=` redeem |
+
+```js
+auth: {
+  crossSubdomainHandoff: { ttlSeconds: 60 },
+},
+```
+
+Details and the `window.name` fallback:
+[12-dashboards-and-sessions.md](./12-dashboards-and-sessions.md).
+
 ## `layout`
 
 **Type:** `string` — **Default:** none (automatic resolution)
@@ -627,9 +652,9 @@ Details: [03-routing.md](./03-routing.md).
 ## `cache()`
 
 **Type:**
-`() => { html?: Record<string, number>, query?: Record<string, string[] | true>, maxEntries?: number, data?: object, trackUpstream?: boolean, trackDependencies?: boolean, transientRetry?: object | false, upstream?: object, redis?: object, prewarm?: object }` —
+`() => { html?: Record<string, number>, query?: Record<string, string[] | true>, vary?: { host?: boolean, headers?: string[], fn?: (req) => string | null }, maxEntries?: number, data?: object, trackUpstream?: boolean, trackDependencies?: boolean, transientRetry?: object | false, upstream?: object, redis?: object, prewarm?: object }` —
 **Default:**
-`{ html: {}, query: {}, maxEntries: 500, data: { maxEntries: 10000, staleFactor: 10 }, trackUpstream: true, trackDependencies: true, transientRetry: { attempts: 1, delayMs: 300 }, upstream: { rate: 0 }, redis: { enabled: false }, prewarm: { enabled: true, max: 400, intervalSeconds: 0 } }`
+`{ html: {}, query: {}, vary: { host: false }, maxEntries: 500, data: { maxEntries: 10000, staleFactor: 10 }, trackUpstream: true, trackDependencies: true, transientRetry: { attempts: 1, delayMs: 300 }, upstream: { rate: 0 }, redis: { enabled: false }, prewarm: { enabled: true, max: 400, intervalSeconds: 0, origins: [] } }`
 
 ### `cache().html`
 
@@ -684,6 +709,31 @@ Parameters are written into the key **sorted**, so `?a=1&b=2` and `?b=2&a=1`
 share one entry. `route(fn, { private: true })` is unaffected by this section; a
 private route is never cached under any condition.
 
+### `cache().vary`
+
+Adds fixed segments to the HTML cache key **independently** of the query
+allowlist. On sites that derive locale from the host, `host: true` is
+**required**; otherwise the first locale's HTML is served to the other host. A
+CDN already separates by full URL — this setting is for the origin L1 and the
+Redis HTML key.
+
+```js
+vary: {
+  host: true, // h=tr.example.com|…
+  // headers: ["x-locale"],
+  // fn: (req) => req.hostname.startsWith("tr.") ? "l=tr" : "l=en",
+}
+```
+
+| Field | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `host` | `boolean` | `false` | Public Host (`x-forwarded-host` else `Host`), lowercase, no port → `h=…` |
+| `headers` | `string[]` | `[]` | Request headers added as `name=value` |
+| `fn` | `(req) => string \| null` | — | Return value appended as a segment |
+
+Key shape: `${vary}|${path}?${query}` (no prefix when vary is empty). Details:
+[06-caching.md](./06-caching.md).
+
 ### `cache().maxEntries`
 
 **Type:** `number` — **Default:** `500`
@@ -920,6 +970,7 @@ page just visited). They cannot be combined — config load throws.
 | `intervalSeconds` | `number` | `0` | If greater than 0, the pass repeats periodically |
 | `rotate` | `boolean` | `true` | If the list is longer than `max`, periodic passes continue where they left off |
 | `priority` | `(string \| RegExp)[]` | `[]` | Warm-up order; matching paths are taken first on every pass |
+| `origins` | `string[]` | `[]` | Origins for the classic pass. Empty → `http://127.0.0.1:<port>`. With `vary.host`, list the locale hosts here |
 
 `priority` accepts two forms: the pattern syntax used everywhere in the config,
 and a plain `RegExp`. Whatever is written first is warmed first.
@@ -929,6 +980,8 @@ prewarm: {
   max: 500,
   rps: 4,
   intervalSeconds: 300,
+  // with vary.host, loopback alone is not enough:
+  origins: ["http://localhost", "http://tr.localhost"],
   priority: [
     "/",                     // the home page
     "/markets/:path*",        // the whole markets section

package/docs/en/12-dashboards-and-sessions.md

@@ -131,6 +131,97 @@ cookie is simply not sent on cross-site POSTs.
 Cookies are **signed, not encrypted**. The value is readable, so store the
 identifier of a secret rather than the secret itself.
 
+## Cross-subdomain: shared cookies
+
+Host-based i18n (`tr.example.com` / `en.example.com`) often needs a session on
+every locale host. The supported pattern is a **short session id** plus an
+optional `Domain=.example.com` — do not put a JWT or a large access token in a
+shared cookie (`large token ≠ shared cookie`).
+
+```js
+// jskelet.config.mjs
+export default {
+  brand: {
+    sharedCookieRoots: [".investvio.com", ".localhost"],
+  },
+  auth: {
+    crossSubdomainHandoff: true, // POST /_jskelet/auth/handoff
+  },
+};
+```
+
+### Server
+
+```js
+import { writeSharedCookie } from "jskelet/cookies";
+
+export function startSession(res, req, sessionId) {
+  const result = writeSharedCookie(res, "sid", sessionId, {
+    req,
+    maxAge: 60 * 60 * 8,
+  });
+  // result.ok === false → result.handoff; the client should use handoff
+  return result;
+}
+```
+
+`Secure` follows the **protocol** (`https` / `x-forwarded-proto`), not
+`NODE_ENV`. The Domain is set when the request Host matches
+`sharedCookieRoots`. Values larger than ~512 bytes are refused with
+`handoff: true`.
+
+### Client
+
+```js
+import {
+  writeSharedCookie,
+  createHandoffUrl,
+  handoffViaWindowName,
+  consumeWindowNameHandoff,
+} from "jskelet/client";
+
+const result = writeSharedCookie("sid", sessionId, {
+  roots: [".investvio.com", ".localhost"],
+  maxAge: 60 * 60 * 8,
+});
+
+if (!result.ok && result.handoff) {
+  const url = await createHandoffUrl({
+    name: "sid",
+    value: sessionId,
+    next: "https://tr.investvio.com/panel",
+  });
+  if (url) location.assign(url);
+  else handoffViaWindowName("https://tr.investvio.com/panel", {
+    name: "sid",
+    value: sessionId,
+  });
+}
+
+// On the target host (layout / island bootstrap):
+consumeWindowNameHandoff();
+```
+
+If `roots` is omitted, the client reads
+`<html data-jskelet-cookie-roots=".investvio.com,.localhost">`. After writing,
+a **read-back** runs; if the browser rejected the Domain, `handoff: true`.
+
+### Handoff ticket
+
+With `auth.crossSubdomainHandoff` on:
+
+1. `POST /_jskelet/auth/handoff` `{ name, value, next }` → `{ url }` (with `?handoff=`)
+2. On the target host a GET middleware redeems the one-time ticket, sets the
+   cookie (shared Domain first, else host-only), and 303-redirects without
+   `handoff`
+
+`next` must be under the same `sharedCookieRoots`. Tickets live ~60s in process
+memory. Do not put a JWT in the URL.
+
+The `window.name` bridge is the cookie-less fallback:
+`handoffViaWindowName` on the source page, `consumeWindowNameHandoff` on the
+target.
+
 ## CSRF
 
 The framework parses the request body (`express.urlencoded` + `express.json`),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jskelet",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "description": "A framework that feels like no framework: Express 5 + build-time .jsk (or EJS) SSR, vanilla JS islands, Tailwind v4 and an in-process HTML TTL cache.",
   "type": "module",
   "license": "MIT",
@@ -33,7 +33,7 @@
     "./client": "./src/client/index.js",
     "./html": "./src/views/helpers/html.js",
     "./tags": "./src/views/helpers/tags.js",
-    "./cookies": "./src/http/cookies.js",
+    "./cookies": "./src/http/cookies-entry.js",
     "./log": "./src/log.mjs",
     "./register": "./src/runtime/register.mjs",
     "./layout": "./src/templates/layout.ejs"