jskelet 0.5.4 → 0.5.5

package/CHANGELOG.md

@@ -10,416 +10,291 @@ 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.
+- Local flat `icons/` directory as the exclusive SVG sprite source when present
+  (`icons.dir`, default `"icons"`): `house.svg` / `house-bold.svg` file names,
+  XOR with `@phosphor-icons/core` (Phosphor only when the directory is absent).
+  The hashed sprite still lands under `public/assets/` and is precompressed.
+
+### Fixed
+
+- Open Graph routes with a `.png` suffix (`/og/…/:slug.png`) now escape the
+  dot for Express 5 / path-to-regexp, so the handler matches again instead of
+  falling through to the HTML 404.
 
 ### 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.
+- Marketing example copy (EN/TR) reflects 0.5.x cache surfaces: host `vary`,
+  early refresh, classic vs `onVisit` prewarm, local `icons/`, shared cookies,
+  and `opengraph-image` → `ogHandler` on the migrate table. Pages now serve
+  per-locale dynamic OG cards at `/og/:locale/:page.png`.
+- Marketing changelog page restyled like a release-notes browser: measured
+  summary cards, search and newest/oldest sort, paginated open release cards
+  with Latest / Released badges and GitHub links (still driven by `CHANGELOG.md`).
+
+## [0.5.4] - 2026-09-18
 
 ### 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
-  `examples/blog` as `/og/blog/:slug.png` and `metadata.openGraph.image`.
-- Early HTML cache refresh before TTL expiry: the last successful produce time
-  (`produceMs`) sets a lead window (`min(max(produceMs×2, 250ms), ttl/2)`). A
-  still-fresh `HIT` in that window revalidates in the background; idle entries
-  are soft-staled by a sweeper and drained over HTTP even without classic
-  `prewarmPaths` (`PREWARM=0` disables both). In-flight refreshes no longer drop
-  the entry when `staleUntil` elapses.
-- Route-level stylesheets: put files in `styles/pages/*.css` and load them from
-  the controller with `styles: ["home.css"]` (same contract as island
-  `entries`). The layout emits them after global `app.css`; dev hot-swaps any
-  changed `.css` manifest key without a full reload.
-- Dev overlay Errors tab now lists failed SSR and browser `fetch` calls with
-  page path, API URL, optional island name, and expandable response-body
-  details (JSON instead of `[object Object]`). Server `console.error` /
-  `console.warn` records also carry the current page when they fire during
-  render.
-- Visit-driven HTML prewarm (`cache().prewarm.onVisit`): after each public
-  cacheable page response, same-origin links in the HTML are warmed in the
-  background (document order, `perPage` cap). Mutually exclusive with classic
-  prewarm (`max` / `priority` / `rotate` / `hooks.prewarmPaths`, etc.) — mixing
-  them fails at config load.
-- Runtime remote image optimizer: set `images.remote.allowHosts` to proxy
-  allowlisted http(s) images through `/_jskelet/image?url=&w=&q=` as resized
-  webp (disk cache under `.jskelet/image-cache/`). `image()` rewrites matching
-  remote `src` values automatically; `remoteImageUrl()` builds URLs by hand.
-  Requires `sharp` at runtime; without it the endpoint 302-redirects to the
-  source.
+- 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.
 
-### Breaking
+## [0.5.3] - 2026-09-18
+
+### Added
+
+- 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.
+
+## [0.5.2] - 2026-09-18
+
+### 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 `examples/blog` as `/og/blog/:slug.png` and `metadata.openGraph.image`.
+
+## [0.5.1] - 2026-09-07
+
+### Added
+
+- Early HTML cache refresh before TTL expiry: the last successful produce time (`produceMs`) sets a lead window (`min(max(produceMs×2, 250ms), ttl/2)`). A still-fresh `HIT` in that window revalidates in the background; idle entries are soft-staled by a sweeper and drained over HTTP even without classic `prewarmPaths` (`PREWARM=0` disables both). In-flight refreshes no longer drop the entry when `staleUntil` elapses.
+
+## [0.5.0] - 2026-09-03
+
+### Added
+
+- Route-level stylesheets: put files in `styles/pages/*.css` and load them from the controller with `styles: ["home.css"]` (same contract as island `entries`). The layout emits them after global `app.css`; dev hot-swaps any changed `.css` manifest key without a full reload.
+
+## [0.4.8] - 2026-09-03
+
+### Added
+
+- Dev overlay Errors tab now lists failed SSR and browser `fetch` calls with page path, API URL, optional island name, and expandable response-body details (JSON instead of `[object Object]`). Server `console.error` / `console.warn` records also carry the current page when they fire during render.
+
+## [0.4.7] - 2026-09-03
+
+### Added
+
+- Visit-driven HTML prewarm (`cache().prewarm.onVisit`): after each public cacheable page response, same-origin links in the HTML are warmed in the background (document order, `perPage` cap). Mutually exclusive with classic prewarm (`max` / `priority` / `rotate` / `hooks.prewarmPaths`, etc.) — mixing them fails at config load.
+
+## [0.4.6] - 2026-09-03
+
+### Fixed
+
+- Remote image optimizer cache hits no longer 404. Disk cache lives under `.jskelet/image-cache/`; Express `sendFile` ignores dotfiles by default, so the file was written but the response still failed. `sendCached` now passes `dotfiles: "allow"`.
+
+## [0.4.5] - 2026-09-03
+
+### Added
+
+- Runtime remote image optimizer: set `images.remote.allowHosts` to proxy allowlisted http(s) images through `/_jskelet/image?url=&w=&q=` as resized webp (disk cache under `.jskelet/image-cache/`). `image()` rewrites matching remote `src` values automatically; `remoteImageUrl()` builds URLs by hand. Requires `sharp` at runtime; without it the endpoint 302-redirects to the source.
+
+## [0.4.4] - 2026-09-02
+
+### Added
 
-- The cache admin panel moved to a top-level `admin()` config section at
-  `/_jskelet/admin` (was `cache().panel` at `/_jskelet/cache`). Enable with
-  `admin() { return { enabled: true } }` or `JSKELET_ADMIN=1`. `JSKELET_CACHE_PANEL` and
-  `cache().panel` are removed. Auth is unchanged (per-process password in the
-  server log, cookie session, 404 for strangers); the action CSRF header is now
-  `X-JSkelet-Admin`.
+- Devtools SEO check: an **SEO** tab in the overlay lists document, heading, image, link and social-tag issues with error/warning severity. Optional page highlights draw red or yellow boxes around the offending elements; the label shows the short title and a click opens the full explanation. Served only in development as `/__jskelet/dev/seo.js` beside the overlay.
+
+### Changed
+
+- Marketing compare live latency demo now measures two same-sized fragments (cached vs `no-store`) with an explicit 80 ms simulated upstream inside the shared producer — a hit skips that wait so the gap is visible even when RTT dominates the wall clock. The island prints transferred bytes, Server-Timing `produce` duration, and a View Source section contrasts `__NEXT_DATA__` payload tax with plain JSkelet HTML. The measured-weight block also shows an estimated Next.js App Router first-load breakdown beside this site’s real gzip totals (clearly labelled estimate, not a build from this repo).
 
 ### Fixed
 
-- Remote image optimizer cache hits no longer 404. Disk cache lives under
-  `.jskelet/image-cache/`; Express `sendFile` ignores dotfiles by default, so
-  the file was written but the response still failed. `sendCached` now passes
-  `dotfiles: "allow"`.
-- Cloudflare analytics in the cache panel no longer asks for an open-ended
-  window. Queries used only `datetime_geq`, so Cloudflare closed the range at
-  query time and a default 24h lookback became `1d` plus network delay — Free
-  zones reject anything wider than one day. Both ends are now pinned from the
-  same clock (`datetime_leq` included).
-- Missing `/assets/*` responses no longer keep the long-lived `immutable`
-  Cache-Control that `headersMiddleware` stamps for static prefixes. A deploy
-  race (prune-before-write) could 404 a hashed CSS URL for a moment; a CDN then
-  cached that HTML 404 for a year and browsers refused it as a stylesheet
-  (`MIME type 'text/html'`). Catch-all and `notFound` handlers now set
-  `Cache-Control: no-store`. CSS and sprite builds write the new file before
-  pruning older hashes so the same content hash never has a gap.
+- Missing `/assets/*` responses no longer keep the long-lived `immutable` Cache-Control that `headersMiddleware` stamps for static prefixes. A deploy race (prune-before-write) could 404 a hashed CSS URL for a moment; a CDN then cached that HTML 404 for a year and browsers refused it as a stylesheet (`MIME type 'text/html'`). Catch-all and `notFound` handlers now set `Cache-Control: no-store`. CSS and sprite builds write the new file before pruning older hashes so the same content hash never has a gap.
+
+## [0.4.3] - 2026-09-02
 
 ### Added
 
-- Devtools SEO check: an **SEO** tab in the overlay lists document, heading,
-  image, link and social-tag issues with error/warning severity. Optional page
-  highlights draw red or yellow boxes around the offending elements; the label
-  shows the short title and a click opens the full explanation. Served only in
-  development as `/__jskelet/dev/seo.js` beside the overlay.
-- Marketing homepage ops storyboard: Redis L2, `/_jskelet/admin` panel mock and
-  Cloudflare purge flow, with tabbed visual scenes animated by the vanilla
-  `motion` API (Framer Motion’s non-React package) via an `ops-story` island.
-- VS Code / Cursor extension skeleton under `extensions/vscode-jsk`: `.jsk`
-  language id, TextMate highlighting (`{{ }}` / `{#if}` / `{#each}` /
-  components), language config, and snippets. Install from that folder or
-  launch **JSK: Extension** from the repo root. Bound attrs on HTML tags
-  (`:src="… + '/path'"`) highlight nested single-quoted strings.
-- Compile-time known components are discovered from **named exports** in
-  `views/components/**/*.js` (plus `.jsk` component files), not from the file
-  basename — so `<SectionHead />` resolves when `sectionHead` lives in
-  `ui.js` without a stub re-export. Docs cover the `.jsk` template-vs-component
-  boundary and a `{ items, error }` loader / `LoadErrorState` pattern so
-  upstream failures are not mistaken for empty data.
-- Build-time `.jsk` templates: declarative HTML-like syntax compiled to ESM
-  render modules under `.jskelet/templates/` (no request-time parse, `eval`, or
-  `new Function`). Coexists with EJS; compiled `.jsk` wins when both exist.
-  Syntax: `{{ }}` / `{{{ }}}`, `{#if}` / `{#each}` / `{#include}`, PascalCase
-  components (`:prop` bindings), built-ins `Link` / `Image` / `Icon` /
-  `CsrfField` / `PreloadImage`.
-- Feature-first conventions: `paths.features` / `paths.shared`, multi-root
-  views and components, `features/<name>/index.js` route registration after
-  `routes/`. CLI: `jskelet generate feature|page|island`. `jskelet init`
-  scaffolds a feature-first `.jsk` skeleton (`features/home/` with route,
-  page, component and island; global `views/pages/not-found.jsk`).
-- Template compile step in `jskelet build`; icon scan and Tailwind docs cover
-  `.jsk` / `features` / `shared`. Bench: `node scripts/bench-templates.mjs`.
-- Top-level `logs` config for persistent sinks: daily NDJSON files
-  (`logs.file`) and batched S3 PutObject (`logs.s3`) with embedded SigV4 — no
-  `@aws-sdk` dependency. `kinds` selects `http` / `event` / `error`; `console`
-  toggles runtime stdout lines. `JSKELET_LOG_BUCKET` / `JSKELET_S3_BUCKET`
-  (+ optional `JSKELET_S3_KEY_PREFIX`) may be a plain bucket or a
-  `bucket/prefix/…` path; with credentials present the sink turns on without
-  `enabled: true`. `JSKELET_S3_API_URL` sets the S3-compatible endpoint
-  (region defaults to `auto`). Env: `JSKELET_LOG_BUCKET`, `JSKELET_S3_*`.
-- Admin panel pages under `/_jskelet/admin`: Overview, Cache, Routes, Views,
-  Logs and System. Configurable `allowIps` (exact or CIDR), `blockBots` (default
-  on — crawler UAs get 404 before login), and `logSize`. Live Logs use an
-  in-process ring plus SSE (`/api/logs/stream`) with client-side filters for
-  method, status, cache, kind, path/route and text. Routes and Views are
-  read-only inventories; HTTP finish middleware records timings only while the
-  panel is enabled.
-- `trailingSlash` in `jskelet.config.mjs` (default `false`). When `true`,
-  canonical page URLs end with `/` and return 200; a request without the slash
-  is sent to the slashed form with a 308 (not 301). File URLs and
-  `/.well-known/**` are left alone. When `false`, no slash is enforced — unlike
-  Next.js, the default does not strip trailing slashes.
-- `cache().query`, a pattern → allowlist mapping that decides which query
-  parameters belong to the HTML cache key. An allowlist caches one entry per
-  distinct value of the listed parameters and ignores the rest, so every
-  `?utm_source=…` variant of a path shares one copy; `true` puts the whole query
-  in the key and `[]` ignores it entirely. Parameters enter the key sorted, so
-  `?a=1&b=2` and `?b=2&a=1` are one entry.
-- A cache admin panel surface (now under `admin()` — see Breaking) that lists
-  what the in-process tier holds (key, size, status, remaining TTL, dependency
-  count, precompressed bodies for HTML; key and TTL for data), reports whether
-  the Redis tier is connected or bypassed, and runs the operations you would
-  otherwise hand-write an admin route for: targeted invalidation with an
-  optional hard mode, dropping a single entry, clearing either cache, unlinking
-  the shared keys and triggering a prewarm pass. Unlike the dev overlay it does
-  not look at `NODE_ENV`, because "why is this page stale" is a production
-  question — but nothing is mounted until it is explicitly enabled, so the path
-  does not exist by default. Access is a 32-character password regenerated on
-  every process start and printed once to the server log; there is no persistent
-  secret to leak and a deploy revokes old access on its own. The password is
-  never accepted in a query string, three failed attempts ban the IP for 24
-  hours, and every banned or unauthorised response is a `404` rather than a 401
-  that would confirm the panel exists. The panel is excluded from indexing,
-  prewarming and navigation speculation.
-- A language picker in the cache panel header, Turkish and English. The first
-  visit follows the browser's language, the choice is kept in `localStorage` and
-  carries over to the login page, and switching costs no request. To keep this
-  from leaking UI concerns into the server, an `/action` response now returns
-  `{ ok, code, params }` instead of an English sentence and the panel builds the
-  text — the framework's log and API stay in one language while the panel
-  speaks two.
-- Cloudflare cache management, from the panel and from code. Set
-  `JSKELET_CLOUDFLARE_KEY` and `JSKELET_CLOUDFLARE_ZONE_ID` (or
-  `cache().cloudflare`) and the panel gains the CDN tier next to the origin one:
-  purge everything, purge every URL currently held in memory with one button or
-  a single row with `cf purge`, purge by prefix, host or cache tag, toggle
-  development mode, cache level, browser cache TTL, query string sorting,
-  Always Online, Tiered Cache, Regional Tiered Cache and Cache Reserve, clear
-  Cache Reserve, and read the cache hit ratio. This matters because
-  `invalidateHtmlCache()` refreshes the origin while the copy your visitors get
-  keeps being served from the edge until its TTL expires. The same surface is
-  exported as `purgeCloudflare()`, `toCloudflareUrls()`,
-  `fetchCloudflareOverview()`, `fetchCacheAnalytics()`, `fetchPathEdges()` and
-  `getCloudflareStatus()`; none of them throw, so a CDN outage returns
-  `{ ok: false, error }` instead of breaking a publish flow. Long purge lists
-  are batched at Cloudflare's 100-keys-per-request limit and sent sequentially
-  to stay inside the rate limit. The token is read from the environment, is
-  never returned in a response, and only cache related zone settings can be
-  changed.
-- An edge breakdown for a single path: `fetchPathEdges()` reports which
-  Cloudflare colos served it from cache and which went to the origin. This is
-  observation, not inventory — Cloudflare has no endpoint that lists which
-  edges currently hold a URL, and no way to warm an edge you pick, so the panel
-  says as much rather than implying otherwise.
-- `getRedisDetails()` reports where the shared tier actually points — address,
-  TLS, database, namespace, which kinds are shared and whether the purge channel
-  is subscribed — because "connected" alone does not explain a Redis that shares
-  nothing because of a wrong namespace. The password is never part of the
-  output. `inspectRedis()` counts the keys per kind plus `DBSIZE` and
-  `used_memory`; it runs a `SCAN`, so the panel keeps it behind its own button
-  instead of the refresh loop. When Redis is off, the panel explains what a
-  shared tier would buy and shows the memory and disk state of the host instead,
-  which is the number that decides whether `maxEntries` is too high.
-- `dropHtmlCacheKey()` and `dropDataCacheKey()` drop one exact cache key.
-  `invalidateHtmlCache()` matches a path pattern and takes down every query
-  variant of a path, which is the right default for a webhook but wrong when you
-  want `/list?page=2` gone and `/list?page=3` left hot.
+- Marketing homepage ops storyboard: Redis L2, `/_jskelet/admin` panel mock and Cloudflare purge flow, with tabbed visual scenes animated by the vanilla `motion` API (Framer Motion’s non-React package) via an `ops-story` island.
+
+## [0.4.2] - 2026-09-02
 
 ### Changed
 
-- README rewritten for the current surface: build-time `.jsk` as the default
-  template story (EJS still supported), feature-first `init` examples, `mount`
-  island contract, path-based `invalidateHtmlCache` (replacing the outdated
-  “no targeted invalidation” claim), Redis / admin / data-cache callouts, and
-  bilingual doc links under `docs/` and `docs/en/`.
-- Marketing compare live latency demo now measures two same-sized fragments
-  (cached vs `no-store`) with an explicit 80 ms simulated upstream inside the
-  shared producer — a hit skips that wait so the gap is visible even when RTT
-  dominates the wall clock. The island prints transferred bytes, Server-Timing
-  `produce` duration, and a View Source section contrasts `__NEXT_DATA__`
-  payload tax with plain JSkelet HTML. The measured-weight block also shows an
-  estimated Next.js App Router first-load breakdown beside this site’s real
-  gzip totals (clearly labelled estimate, not a build from this repo).
-- Duplicate component named exports (or the same PascalCase tag in two files)
-  now **fail** at build and at server startup instead of warning and letting
-  the second definition win. Overwriting `components/index.js` barrel exports
-  remains allowed.
-- `examples/minimal` pages moved to `.jsk`; adds `features/demo` as a
-  co-located route + view sample.
-- Marketing compare/FAQ copy no longer claims targeted invalidation is missing;
-  it points at `invalidateHtmlCache()` (and Redis pub/sub for multi-instance).
-
-- An adaptive per-host rate limit for upstream calls, `cache().upstream`. It sits
-  in the `fetch` wrapper rather than in the prewarm pass, because what spends the
-  quota is the API call, not the page: one render may make one call or twenty, so
-  `prewarm.rps` could never bound the real thing. A token bucket caps the average
-  rate, a concurrency limit caps the calls in flight, and `rate` is treated as a
-  ceiling that the limiter pulls down on its own — a 429 or 503 halves the rate,
-  `Retry-After` stops the bucket for exactly as long as the upstream asked, and
-  clean windows climb back one step at a time. A host that returns
-  `breakerFailures` rate limits in a row is bypassed for `breakerCooldownMs`,
-  which stops the worst waste: because a 429 counts as transient, the HTML
-  produced by a throttled call is never stored, so a pass in that state spends
-  quota and keeps nothing. Only 429 and 503 penalise the rate; a 400 or 500 is
-  not a quota problem. Off by default — set `rate` to turn it on.
-- `getUpstreamLimiterStatus()` reports the current rate, calls in flight, 429
-  count and breaker state per host. The dev panel's Server tab shows the same.
-- `getDataCacheStats()` counts how the data cache was used: fresh hits, stale
-  hits, misses, coalesced concurrent reads, values promoted from the shared tier
-  and — the only number that reaches the quota — real producer runs. A prewarm
-  pass now prints its own share of that (`12 upstream calls for 430 data reads
-(97% from the data cache)`), which is what tells you whether the fix is a
-  longer TTL or a rate limit. The dev report has a Data cache card for it.
-
-- The dev overlay header now shows the installed JSkelet version next to the
-  title, labelled `latest` when it matches npm and `outdated` with the newer
-  version when it does not, so you can tell at a glance which version the
-  project runs without opening the Server tab.
-- An optional Redis tier behind both caches, turned on with
-  `cache().redis: { enabled: true, url }` and `npm install ioredis`. The
-  in-process cache stays primary and every request still reads it; Redis only
-  does the two things a single process cannot. An instance that has never seen a
-  path finds the HTML another replica already produced, so a fresh container or a
-  post-deploy replacement does not re-render and re-fetch everything from
-  scratch. And `invalidateHtmlCache()`, `clearHtmlCache()` and
-  `clearDataCache()` now reach every replica over pub/sub instead of only the one
-  that received the webhook — until now the others waited out the TTL and a
-  visitor saw old or new content depending on where they landed. Keys live under
-  `_jskelet:{namespace}:{buildId}:…`, where the build id makes HTML from a
-  previous deploy expire on its own rather than pointing at asset files that no
-  longer exist. Personalised (`storable: false`), degraded and non-200 responses
-  are never shared. If `ioredis` is missing, Redis is unreachable or it goes down
-  mid-flight, a warning is printed and the site keeps serving from memory.
-- `getRedisStatus()` reports whether the shared tier is connected, which key
-  prefix and build id it is using, and how many command failures there have
-  been — usable from a healthcheck endpoint. The same summary appears in the dev
-  panel report.
-- Servers started with `startServer()` now shut down on `SIGTERM`/`SIGINT`
-  instead of being killed: the listener is closed and the Redis connection is
-  drained so in-flight writes are not cut mid-command.
-- Targeted HTML invalidation: `invalidateHtmlCache(target, { hard })` takes a
-  path, the config pattern syntax (`/news/:slug`), a regular expression or a list
-  of them, and returns how many entries were affected. By default it **stales**
-  the entries rather than deleting them, so a webhook that touches hundreds of
-  pages does not turn into hundreds of cold renders at the worst possible moment:
-  visitors keep getting the old HTML while the refresh runs in the background,
-  once per key. Matching is done against the path, so every query variant of a
-  page is covered by one call, and a render already in flight when the purge
-  arrives is not stored.
-- `clearDataCache()` now refreshes the HTML too. The `withDataCache` keys read
-  during a render are recorded, so dropping `news:abc` stales every page that
-  actually read it — the article, the home page listing it and the tag page —
-  without the application declaring any tags. Turn it off with
-  `cache().trackDependencies: false`; `getHtmlCacheEntries()` reports the
-  dependency count per page as `deps`.
-- Invalidated paths go to the front of the next prewarm pass, so an updated page
-  is refreshed without waiting for a visitor, while still respecting the `rps`
-  limit. The pass summary counts them separately.
-- An upstream data cache: `withDataCache(key, ttlSeconds, producer)` and the
-  `dataCache(fn, { key, revalidate })` wrapper, with `clearDataCache(prefix?)`,
-  `getDataCacheSize()` and `getDataCacheEntries()` alongside them. It keeps JSON
-  rather than HTML, so its default limit is 10,000 entries: a long-tail page that
-  was never prewarmed still renders without touching the API. Concurrent reads of
-  the same key collapse into one upstream request, an expired entry is served
-  immediately while it refreshes in the background, a failing producer falls back
-  to the stale value, and empty answers (`null`/`undefined`) are not stored
-  unless `storeEmpty: true` is passed.
-- `cache().prewarm.priority` decides the warm-up order and accepts both the
-  config pattern syntax (`/news/:slug`) and plain regular expressions. Matching
-  paths are warmed on every pass.
-- Drip prewarming for large sites: `cache().prewarm.rps` (also `PREWARM_RPS`)
-  caps requests per second regardless of parallelism, and `rotate` (on by
-  default) makes periodic passes continue through the queue where the previous
-  one stopped instead of re-warming the same first slice. A pass is skipped while
-  the previous one is still running.
-- `cache().prewarm.retryDelayMs` (also `PREWARM_RETRY_DELAY_MS`) waits before the
-  retry pass, since rate limit windows are measured in seconds.
-- `cache().maxEntries` configures the HTML cache limit, which used to be a fixed 500.
-- Transient upstream failures are now detected without any application code:
-  `globalThis.fetch` is wrapped during startup and `429`, `5xx` and network
-  errors raised inside a render are reported on their own, so rate limits stop
-  turning existing pages into 404s even when the data layer never calls
-  `reportUpstreamFailure()`. Requests outside a render and requests to the
-  server itself are ignored, deterministic answers such as `404` are not
-  reported, and the wrapper can be turned off with `cache().trackUpstream:
-false`.
-- `cache().transientRetry` (`{ attempts: 1, delayMs: 300 }` by default) retries a
-  page that called `notFound()` while upstream was failing. Each attempt runs in
-  a fresh upstream and per-request cache scope, so a page whose data arrives on
-  the second try is served and cached as usual instead of degrading to an error.
-- The dev report now includes the data cache entry count under `cache.data`.
+- README rewritten for the current surface: build-time `.jsk` as the default template story (EJS still supported), feature-first `init` examples, `mount` island contract, path-based `invalidateHtmlCache` (replacing the outdated “no targeted invalidation” claim), Redis / admin / data-cache callouts, and bilingual doc links under `docs/` and `docs/en/`.
+
+## [0.4.1] - 2026-09-02
+
+### Added
+
+- VS Code / Cursor extension skeleton under `extensions/vscode-jsk`: `.jsk` language id, TextMate highlighting (`{{ }}` / `{#if}` / `{#each}` / components), language config, and snippets. Install from that folder or launch **JSK: Extension** from the repo root. Bound attrs on HTML tags (`:src="… + '/path'"`) highlight nested single-quoted strings.
+- Compile-time known components are discovered from **named exports** in `views/components/**/*.js` (plus `.jsk` component files), not from the file basename — so `<SectionHead />` resolves when `sectionHead` lives in `ui.js` without a stub re-export. Docs cover the `.jsk` template-vs-component boundary and a `{ items, error }` loader / `LoadErrorState` pattern so upstream failures are not mistaken for empty data.
+
+### Changed
+
+- Duplicate component named exports (or the same PascalCase tag in two files) now **fail** at build and at server startup instead of warning and letting the second definition win. Overwriting `components/index.js` barrel exports remains allowed.
+- Marketing compare/FAQ copy no longer claims targeted invalidation is missing; it points at `invalidateHtmlCache()` (and Redis pub/sub for multi-instance).
+
+## [0.4.0] - 2026-09-02
+
+### Added
+
+- Build-time `.jsk` templates: declarative HTML-like syntax compiled to ESM render modules under `.jskelet/templates/` (no request-time parse, `eval`, or `new Function`). Coexists with EJS; compiled `.jsk` wins when both exist. Syntax: `{{ }}` / `{{{ }}}`, `{#if}` / `{#each}` / `{#include}`, PascalCase components (`:prop` bindings), built-ins `Link` / `Image` / `Icon` / `CsrfField` / `PreloadImage`.
+- Feature-first conventions: `paths.features` / `paths.shared`, multi-root views and components, `features/<name>/index.js` route registration after `routes/`. CLI: `jskelet generate feature|page|island`. `jskelet init` scaffolds a feature-first `.jsk` skeleton (`features/home/` with route, page, component and island; global `views/pages/not-found.jsk`).
+- Template compile step in `jskelet build`; icon scan and Tailwind docs cover `.jsk` / `features` / `shared`. Bench: `node scripts/bench-templates.mjs`.
+
+### Changed
+
+- `examples/minimal` pages moved to `.jsk`; adds `features/demo` as a co-located route + view sample.
+
+## [0.3.5] - 2026-09-02
+
+### Changed
+
+- S3 logging configuration refactored; docs clarified.
+
+## [0.3.4] - 2026-09-02
+
+### Changed
+
+- S3 logging pipeline now prints connection details at boot.
+
+## [0.3.3] - 2026-09-02
+
+### Changed
+
+- Internal packaging / release bump.
+
+## [0.3.2] - 2026-09-02
+
+### Added
+
+- Top-level `logs` config for persistent sinks: daily NDJSON files (`logs.file`) and batched S3 PutObject (`logs.s3`) with embedded SigV4 — no `@aws-sdk` dependency. `kinds` selects `http` / `event` / `error`; `console` toggles runtime stdout lines. `JSKELET_LOG_BUCKET` (and `logs.s3.bucket`) may be a plain bucket or a `bucket/prefix/…` path. `JSKELET_S3_API_URL` sets the R2/MinIO endpoint (region defaults to `auto`). Missing credentials warn and disable the S3 sink without taking the site down. Env: `JSKELET_LOG_BUCKET`, `JSKELET_S3_ACCESS_KEY_ID`, `JSKELET_S3_SECRET_ACCESS_KEY`, `JSKELET_S3_SESSION_TOKEN`, `JSKELET_S3_REGION`, `JSKELET_S3_API_URL`.
+
+## [0.3.1] - 2026-09-02
+
+### Added
+
+- Admin panel pages under `/_jskelet/admin`: Overview, Cache, Routes, Views, Logs and System. Configurable `allowIps` (exact or CIDR), `blockBots` (default on — crawler UAs get 404 before login), and `logSize`. Live Logs use an in-process ring plus SSE (`/api/logs/stream`) with client-side filters for method, status, cache, kind, path/route and text. Routes and Views are read-only inventories; HTTP finish middleware records timings only while the panel is enabled.
+- `trailingSlash` in `jskelet.config.mjs` (default `false`). When `true`, canonical page URLs end with `/` and return 200; a request without the slash is sent to the slashed form with a 308 (not 301). File URLs and `/.well-known/**` are left alone. When `false`, no slash is enforced — unlike Next.js, the default does not strip trailing slashes.
+- A cache admin panel surface (now under `admin()` — see Breaking) that lists what the in-process tier holds (key, size, status, remaining TTL, dependency count, precompressed bodies for HTML; key and TTL for data), reports whether the Redis tier is connected or bypassed, and runs the operations you would otherwise hand-write an admin route for: targeted invalidation with an optional hard mode, dropping a single entry, clearing either cache, unlinking the shared keys and triggering a prewarm pass. Unlike the dev overlay it does not look at `NODE_ENV`, because "why is this page stale" is a production question — but nothing is mounted until it is explicitly enabled, so the path does not exist by default. Access is a 32-character password regenerated on every process start and printed once to the server log; there is no persistent secret to leak and a deploy revokes old access on its own. The password is never accepted in a query string, three failed attempts ban the IP for 24 hours, and every banned or unauthorised response is a `404` rather than a 401 that would confirm the panel exists. The panel is excluded from indexing, prewarming and navigation speculation.
 
 ### Changed
 
-- Admin panel System meters (CPU, memory, disk) show this process's share of
-  the host — RSS and project disk footprint against machine totals, plus
-  process CPU across all cores — instead of whole-machine fullness. The panel
-  content width is wider (`1600px`) so Overview, Routes, Views and System use
-  the screen better.
-- The release history page in `examples/marketing` now shows one release at a
-  time: the newest one is expanded and older releases collapse to a single
-  header row with their date, status and change count. Every release used to be
-  printed open in a two-column grid, which made the page an unreadable wall as
-  soon as a few versions piled up. Version links and the quick-jump strip still
-  work, and they open the collapsed release they point at.
-- The prewarm retry pass no longer retries permanent failures. A `400`, `403` or
-  `404` does not get better on the second try, so those paths are dropped from
-  the retry round and counted as `N not retried (permanent)` in the summary. The
-  wait before the round now also honours the upstream rate limit: if a
-  `Retry-After` or an open circuit breaker is holding calls back, the pass waits
-  that out instead of retrying into the same 429.
-- Errors and warnings raised during a prewarm pass are no longer logged one per
-  page. Request errors and the per-page render warnings (`was produced with
-missing data`, `returned notFound() while upstream is failing`, `could not be
-produced`) are counted while the pass runs and printed as a single summary
-  block afterwards, grouped by message with the most frequent kinds first, so a
-  failing upstream can no longer bury the "warmed N/M pages" line under hundreds
-  of near-identical lines. Real traffic logs as before, and the dev tools panel
-  still shows the per-path detail.
-- The marketing example's changelog page is now a timeline: releases are laid out
-  along a rail with a sticky version column, each change group gets its own card
-  with a coloured rule and item count, and a row of version chips at the top
-  jumps straight to a release.
-- The dev tools panel is now fed over a WebSocket (`<devBasePath>/ws`) instead of
-  polling `/stats` every two seconds. The server pushes statistics as they change
-  and sends live reload and CSS hot-swap events over the same connection, so an
-  open tab no longer keeps hitting the server while the panel is closed. No new
-  dependency is involved; if the socket cannot be opened, the panel falls back to
-  the previous SSE plus polling path.
-- The server now binds to `::` instead of `0.0.0.0` when no `HOST` is given, so a
-  single dual-stack socket answers both IPv6 and IPv4. Browsers resolve
-  `localhost` to `::1` first and, unlike ordinary requests, a WebSocket handshake
-  does not fall back to IPv4 — which made the dev panel's live channel fail on an
-  IPv4-only socket. Where IPv6 is unavailable the bind falls back to `0.0.0.0`.
-- Prewarming no longer holds up the rest of the dev server. In development it now
-  runs with a single worker and a default limit of 4 requests per second
-  (`prewarm.rps` / `PREWARM_RPS` still override it), so page requests and the dev
-  panel stay responsive while a warm-up round is going on. Production behaviour
-  is unchanged.
-- `notFound()` is no longer served as a 404 when a transient upstream failure
-  (`429`, `5xx`, network error) happened during the same render. The page is
-  retried first and, if upstream is still failing, responds with an uncached
-  `503` and `Retry-After`. A temporary rate limit is no longer frozen into "this
-  page does not exist" for the whole TTL. A retry that gets a clean answer saying
-  the page is gone still returns a normal 404.
-- Responses produced with missing data are no longer offered to shared caches:
-  a `degraded` render is sent with `private, no-store` instead of
-  `public, s-maxage=…`. The `X-JSkelet-Cache` diagnostic header is still written.
-- The prewarm summary distinguishes paths left for the next pass
-  (`700 deferred to the next pass`) from paths dropped entirely
-  (`700 over the limit`).
-- The changelog page of the marketing example is generated from the project's
-  `CHANGELOG.md` instead of a hand-written list, and shows the version published
-  on npm next to the installed one.
-- The marketing example reads its markdown (documentation and changelog) from
-  the repository over GitHub's raw endpoint, falling back to the installed
-  package when the network is unavailable, so a deployment that ships without
-  `node_modules` can still serve the docs. In development the local file wins
-  and nothing is cached. The branch is overridable with `DOCS_REF`.
+- Admin panel System meters (CPU, memory, disk) show this process's share of the host — RSS and project disk footprint against machine totals, plus process CPU across all cores — instead of whole-machine fullness. The panel content width is wider (`1600px`) so Overview, Routes, Views and System use the screen better.
+
+### Breaking
+
+- The cache admin panel moved to a top-level `admin()` config section at `/_jskelet/admin` (was `cache().panel` at `/_jskelet/cache`). Enable with `admin() { return { enabled: true } }` or `JSKELET_ADMIN=1`. `JSKELET_CACHE_PANEL` and `cache().panel` are removed. Auth is unchanged (per-process password in the server log, cookie session, 404 for strangers); the action CSRF header is now `X-JSkelet-Admin`.
+
+## [0.2.5] - 2026-09-01
 
 ### Fixed
 
-- The dev panel's WebSocket handshake was answered with a `Sec-WebSocket-Accept`
-  value derived from a mistyped protocol constant. Browsers verify that value and
-  closed the connection immediately with "Incorrect 'Sec-WebSocket-Accept' header
-  value", so the panel silently fell back to polling.
+- Cloudflare analytics in the cache panel no longer asks for an open-ended window. Queries used only `datetime_geq`, so Cloudflare closed the range at query time and a default 24h lookback became `1d` plus network delay — Free zones reject anything wider than one day. Both ends are now pinned from the same clock (`datetime_leq` included).
+
+## [0.2.4] - 2026-08-31
+
+### Added
+
+- A language picker in the cache panel header, Turkish and English. The first visit follows the browser's language, the choice is kept in `localStorage` and carries over to the login page, and switching costs no request. To keep this from leaking UI concerns into the server, an `/action` response now returns `{ ok, code, params }` instead of an English sentence and the panel builds the text — the framework's log and API stay in one language while the panel speaks two.
+
+## [0.2.3] - 2026-08-31
+
+### Added
+
+- `cache().query`, a pattern → allowlist mapping that decides which query parameters belong to the HTML cache key. An allowlist caches one entry per distinct value of the listed parameters and ignores the rest, so every `?utm_source=…` variant of a path shares one copy; `true` puts the whole query in the key and `[]` ignores it entirely. Parameters enter the key sorted, so `?a=1&b=2` and `?b=2&a=1` are one entry.
+- Cloudflare cache management, from the panel and from code. Set `JSKELET_CLOUDFLARE_KEY` and `JSKELET_CLOUDFLARE_ZONE_ID` (or `cache().cloudflare`) and the panel gains the CDN tier next to the origin one: purge everything, purge every URL currently held in memory with one button or a single row with `cf purge`, purge by prefix, host or cache tag, toggle development mode, cache level, browser cache TTL, query string sorting, Always Online, Tiered Cache, Regional Tiered Cache and Cache Reserve, clear Cache Reserve, and read the cache hit ratio. This matters because `invalidateHtmlCache()` refreshes the origin while the copy your visitors get keeps being served from the edge until its TTL expires. The same surface is exported as `purgeCloudflare()`, `toCloudflareUrls()`, `fetchCloudflareOverview()`, `fetchCacheAnalytics()`, `fetchPathEdges()` and `getCloudflareStatus()`; none of them throw, so a CDN outage returns `{ ok: false, error }` instead of breaking a publish flow. Long purge lists are batched at Cloudflare's 100-keys-per-request limit and sent sequentially to stay inside the rate limit. The token is read from the environment, is never returned in a response, and only cache related zone settings can be changed.
+- An edge breakdown for a single path: `fetchPathEdges()` reports which Cloudflare colos served it from cache and which went to the origin. This is observation, not inventory — Cloudflare has no endpoint that lists which edges currently hold a URL, and no way to warm an edge you pick, so the panel says as much rather than implying otherwise.
+- `getRedisDetails()` reports where the shared tier actually points — address, TLS, database, namespace, which kinds are shared and whether the purge channel is subscribed — because "connected" alone does not explain a Redis that shares nothing because of a wrong namespace. The password is never part of the output. `inspectRedis()` counts the keys per kind plus `DBSIZE` and `used_memory`; it runs a `SCAN`, so the panel keeps it behind its own button instead of the refresh loop. When Redis is off, the panel explains what a shared tier would buy and shows the memory and disk state of the host instead, which is the number that decides whether `maxEntries` is too high.
+
+### Changed
+
+- The release history page in `examples/marketing` now shows one release at a time: the newest one is expanded and older releases collapse to a single header row with their date, status and change count. Every release used to be printed open in a two-column grid, which made the page an unreadable wall as soon as a few versions piled up. Version links and the quick-jump strip still work, and they open the collapsed release they point at.
 
 ### Breaking
 
-- A request that carries a query parameter is now dynamic by default: it is not
-  written to the HTML cache and the response is sent with `private, no-store`,
-  even when a `cache().html` pattern covers the path. Every query variant used
-  to become its own cache entry, which let campaign parameters
-  (`?utm_source=…`) mint unbounded keys and evict real pages from a 500-entry
-  store. Pages whose output genuinely depends on the query keep their cache by
-  listing the relevant parameters under `cache().query`.
+- A request that carries a query parameter is now dynamic by default: it is not written to the HTML cache and the response is sent with `private, no-store`, even when a `cache().html` pattern covers the path. Every query variant used to become its own cache entry, which let campaign parameters (`?utm_source=…`) mint unbounded keys and evict real pages from a 500-entry store. Pages whose output genuinely depends on the query keep their cache by listing the relevant parameters under `cache().query`.
+
+## [0.2.2] - 2026-08-31
+
+### Added
+
+- A cache admin panel at `/_jskelet/cache`, turned on with `cache().panel: { enabled: true }` or `JSKELET_CACHE_PANEL=1`. It lists what the in-process tier holds (key, size, status, remaining TTL, dependency count, precompressed bodies for HTML; key and TTL for data), reports whether the Redis tier is connected or bypassed, and runs the operations you would otherwise hand-write an admin route for: targeted invalidation with an optional hard mode, dropping a single entry, clearing either cache, unlinking the shared keys and triggering a prewarm pass. Unlike the dev overlay it does not look at `NODE_ENV`, because "why is this page stale" is a production question — but nothing is mounted until it is explicitly enabled, so the path does not exist by default. Access is a 32-character password regenerated on every process start and printed once to the server log; there is no persistent secret to leak and a deploy revokes old access on its own. The password is never accepted in a query string, three failed attempts ban the IP for 24 hours, and every banned or unauthorised response is a `404` rather than a 401 that would confirm the panel exists. The panel is excluded from indexing, prewarming and navigation speculation.
+- `dropHtmlCacheKey()` and `dropDataCacheKey()` drop one exact cache key. `invalidateHtmlCache()` matches a path pattern and takes down every query variant of a path, which is the right default for a webhook but wrong when you want `/list?page=2` gone and `/list?page=3` left hot.
+- An adaptive per-host rate limit for upstream calls, `cache().upstream`. It sits in the `fetch` wrapper rather than in the prewarm pass, because what spends the quota is the API call, not the page: one render may make one call or twenty, so `prewarm.rps` could never bound the real thing. A token bucket caps the average rate, a concurrency limit caps the calls in flight, and `rate` is treated as a ceiling that the limiter pulls down on its own — a 429 or 503 halves the rate, `Retry-After` stops the bucket for exactly as long as the upstream asked, and clean windows climb back one step at a time. A host that returns `breakerFailures` rate limits in a row is bypassed for `breakerCooldownMs`, which stops the worst waste: because a 429 counts as transient, the HTML produced by a throttled call is never stored, so a pass in that state spends quota and keeps nothing. Only 429 and 503 penalise the rate; a 400 or 500 is not a quota problem. Off by default — set `rate` to turn it on.
+- `getUpstreamLimiterStatus()` reports the current rate, calls in flight, 429 count and breaker state per host. The dev panel's Server tab shows the same.
+- `getDataCacheStats()` counts how the data cache was used: fresh hits, stale hits, misses, coalesced concurrent reads, values promoted from the shared tier and — the only number that reaches the quota — real producer runs. A prewarm pass now prints its own share of that (`12 upstream calls for 430 data reads (97% from the data cache)`), which is what tells you whether the fix is a longer TTL or a rate limit. The dev report has a Data cache card for it.
+- The dev overlay header now shows the installed JSkelet version next to the title, labelled `latest` when it matches npm and `outdated` with the newer version when it does not, so you can tell at a glance which version the project runs without opening the Server tab.
+
+### Changed
+
+- The prewarm retry pass no longer retries permanent failures. A `400`, `403` or `404` does not get better on the second try, so those paths are dropped from the retry round and counted as `N not retried (permanent)` in the summary. The wait before the round now also honours the upstream rate limit: if a `Retry-After` or an open circuit breaker is holding calls back, the pass waits that out instead of retrying into the same 429.
+
+## [0.2.1] - 2026-08-31
+
+### Changed
+
+- Errors and warnings raised during a prewarm pass are no longer logged one per page. Request errors and the per-page render warnings (`was produced with missing data`, `returned notFound() while upstream is failing`, `could not be produced`) are counted while the pass runs and printed as a single summary block afterwards, grouped by message with the most frequent kinds first, so a failing upstream can no longer bury the "warmed N/M pages" line under hundreds of near-identical lines. Real traffic logs as before, and the dev tools panel still shows the per-path detail.
+
+## [0.2.0] - 2026-08-31
+
+### Added
+
+- An optional Redis tier behind both caches, turned on with `cache().redis: { enabled: true, url }` and `npm install ioredis`. The in-process cache stays primary and every request still reads it; Redis only does the two things a single process cannot. An instance that has never seen a path finds the HTML another replica already produced, so a fresh container or a post-deploy replacement does not re-render and re-fetch everything from scratch. And `invalidateHtmlCache()`, `clearHtmlCache()` and `clearDataCache()` now reach every replica over pub/sub instead of only the one that received the webhook — until now the others waited out the TTL and a visitor saw old or new content depending on where they landed. Keys live under `_jskelet:{namespace}:{buildId}:…`, where the build id makes HTML from a previous deploy expire on its own rather than pointing at asset files that no longer exist. Personalised (`storable: false`), degraded and non-200 responses are never shared. If `ioredis` is missing, Redis is unreachable or it goes down mid-flight, a warning is printed and the site keeps serving from memory.
+- `getRedisStatus()` reports whether the shared tier is connected, which key prefix and build id it is using, and how many command failures there have been — usable from a healthcheck endpoint. The same summary appears in the dev panel report.
+- Servers started with `startServer()` now shut down on `SIGTERM`/`SIGINT` instead of being killed: the listener is closed and the Redis connection is drained so in-flight writes are not cut mid-command.
+
+### Changed
+
+- Request errors raised during a prewarm pass are no longer logged one by one. They are counted while the pass runs and printed as a single summary line afterwards, grouped by status and message with the most frequent kinds first, so a flaky upstream can no longer bury the "warmed N/M pages" line under hundreds of stack traces. Errors from real traffic are logged as before, and the dev tools panel still shows the per-path detail.
+
+## [0.1.9] - 2026-08-31
+
+### Fixed
+
+- The dev panel's WebSocket handshake was answered with a `Sec-WebSocket-Accept` value derived from a mistyped protocol constant. Browsers verify that value and closed the connection immediately with "Incorrect 'Sec-WebSocket-Accept' header value", so the panel silently fell back to polling.
+
+## [0.1.8] - 2026-08-31
+
+### Changed
+
+- The marketing example's changelog page is now a timeline: releases are laid out along a rail with a sticky version column, each change group gets its own card with a coloured rule and item count, and a row of version chips at the top jumps straight to a release.
+- The server now binds to `::` instead of `0.0.0.0` when no `HOST` is given, so a single dual-stack socket answers both IPv6 and IPv4. Browsers resolve `localhost` to `::1` first and, unlike ordinary requests, a WebSocket handshake does not fall back to IPv4 — which made the dev panel's live channel fail on an IPv4-only socket. Where IPv6 is unavailable the bind falls back to `0.0.0.0`.
+
+## [0.1.7] - 2026-08-31
+
+### Changed
+
+- Devtools WebSocket connection handling hardened.
+
+## [0.1.6] - 2026-08-31
+
+### Added
+
+- Targeted HTML invalidation: `invalidateHtmlCache(target, { hard })` takes a path, the config pattern syntax (`/news/:slug`), a regular expression or a list of them, and returns how many entries were affected. By default it **stales** the entries rather than deleting them, so a webhook that touches hundreds of pages does not turn into hundreds of cold renders at the worst possible moment: visitors keep getting the old HTML while the refresh runs in the background, once per key. Matching is done against the path, so every query variant of a page is covered by one call, and a render already in flight when the purge arrives is not stored.
+- `clearDataCache()` now refreshes the HTML too. The `withDataCache` keys read during a render are recorded, so dropping `news:abc` stales every page that actually read it — the article, the home page listing it and the tag page — without the application declaring any tags. Turn it off with `cache().trackDependencies: false`; `getHtmlCacheEntries()` reports the dependency count per page as `deps`.
+- Invalidated paths go to the front of the next prewarm pass, so an updated page is refreshed without waiting for a visitor, while still respecting the `rps` limit. The pass summary counts them separately.
+
+### Changed
+
+- Prewarming no longer holds up the rest of the dev server. In development it now runs with a single worker and a default limit of 4 requests per second (`prewarm.rps` / `PREWARM_RPS` still override it), so page requests and the dev panel stay responsive while a warm-up round is going on. Production behaviour is unchanged.
+
+## [0.1.5] - 2026-08-30
+
+### Changed
+
+- The dev tools panel is now fed over a WebSocket (`<devBasePath>/ws`) instead of polling `/stats` every two seconds. The server pushes statistics as they change and sends live reload and CSS hot-swap events over the same connection, so an open tab no longer keeps hitting the server while the panel is closed. No new dependency is involved; if the socket cannot be opened, the panel falls back to the previous SSE plus polling path.
+
+## [0.1.4] - 2026-08-30
+
+### Added
+
+- Transient upstream failures are now detected without any application code: `globalThis.fetch` is wrapped during startup and `429`, `5xx` and network errors raised inside a render are reported on their own, so rate limits stop turning existing pages into 404s even when the data layer never calls `reportUpstreamFailure()`. Requests outside a render and requests to the server itself are ignored, deterministic answers such as `404` are not reported, and the wrapper can be turned off with `cache().trackUpstream: false`.
+- `cache().transientRetry` (`{ attempts: 1, delayMs: 300 }` by default) retries a page that called `notFound()` while upstream was failing. Each attempt runs in a fresh upstream and per-request cache scope, so a page whose data arrives on the second try is served and cached as usual instead of degrading to an error.
+
+### Changed
+
+- The changelog page of the marketing example is generated from the project's `CHANGELOG.md` instead of a hand-written list, and shows the version published on npm next to the installed one.
+- The marketing example reads its markdown (documentation and changelog) from the repository over GitHub's raw endpoint, falling back to the installed package when the network is unavailable, so a deployment that ships without `node_modules` can still serve the docs. In development the local file wins and nothing is cached. The branch is overridable with `DOCS_REF`.
+
+## [0.1.3] - 2026-08-30
+
+### Changed
+
+- Patch release; no user-facing changelog entries beyond 0.1.2.
 
 ## [0.1.2] - 2026-08-30
 
@@ -533,7 +408,39 @@ Initial release.
 - Documentation under `docs/` and three examples: `minimal`, `blog`,
   `marketing`.
 
-[Unreleased]: https://github.com/ayberkenis/jskelet/compare/v0.1.2...HEAD
+[Unreleased]: https://github.com/ayberkenis/jskelet/compare/v0.5.4...HEAD
+[0.5.4]: https://github.com/ayberkenis/jskelet/compare/v0.5.3...v0.5.4
+[0.5.3]: https://github.com/ayberkenis/jskelet/compare/v0.5.2...v0.5.3
+[0.5.2]: https://github.com/ayberkenis/jskelet/compare/v0.5.1...v0.5.2
+[0.5.1]: https://github.com/ayberkenis/jskelet/compare/v0.5.0...v0.5.1
+[0.5.0]: https://github.com/ayberkenis/jskelet/compare/v0.4.8...v0.5.0
+[0.4.8]: https://github.com/ayberkenis/jskelet/compare/v0.4.7...v0.4.8
+[0.4.7]: https://github.com/ayberkenis/jskelet/compare/v0.4.6...v0.4.7
+[0.4.6]: https://github.com/ayberkenis/jskelet/compare/v0.4.5...v0.4.6
+[0.4.5]: https://github.com/ayberkenis/jskelet/compare/v0.4.4...v0.4.5
+[0.4.4]: https://github.com/ayberkenis/jskelet/compare/v0.4.3...v0.4.4
+[0.4.3]: https://github.com/ayberkenis/jskelet/compare/v0.4.2...v0.4.3
+[0.4.2]: https://github.com/ayberkenis/jskelet/compare/v0.4.1...v0.4.2
+[0.4.1]: https://github.com/ayberkenis/jskelet/compare/v0.4.0...v0.4.1
+[0.4.0]: https://github.com/ayberkenis/jskelet/compare/v0.3.5...v0.4.0
+[0.3.5]: https://github.com/ayberkenis/jskelet/compare/v0.3.4...v0.3.5
+[0.3.4]: https://github.com/ayberkenis/jskelet/compare/v0.3.3...v0.3.4
+[0.3.3]: https://github.com/ayberkenis/jskelet/compare/v0.3.2...v0.3.3
+[0.3.2]: https://github.com/ayberkenis/jskelet/compare/v0.3.1...v0.3.2
+[0.3.1]: https://github.com/ayberkenis/jskelet/compare/v0.2.5...v0.3.1
+[0.2.5]: https://github.com/ayberkenis/jskelet/compare/v0.2.4...v0.2.5
+[0.2.4]: https://github.com/ayberkenis/jskelet/compare/v0.2.3...v0.2.4
+[0.2.3]: https://github.com/ayberkenis/jskelet/compare/v0.2.2...v0.2.3
+[0.2.2]: https://github.com/ayberkenis/jskelet/compare/v0.2.1...v0.2.2
+[0.2.1]: https://github.com/ayberkenis/jskelet/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/ayberkenis/jskelet/compare/v0.1.9...v0.2.0
+[0.1.9]: https://github.com/ayberkenis/jskelet/compare/v0.1.8...v0.1.9
+[0.1.8]: https://github.com/ayberkenis/jskelet/compare/v0.1.7...v0.1.8
+[0.1.7]: https://github.com/ayberkenis/jskelet/compare/v0.1.6...v0.1.7
+[0.1.6]: https://github.com/ayberkenis/jskelet/compare/v0.1.5...v0.1.6
+[0.1.5]: https://github.com/ayberkenis/jskelet/compare/v0.1.4...v0.1.5
+[0.1.4]: https://github.com/ayberkenis/jskelet/compare/v0.1.3...v0.1.4
+[0.1.3]: https://github.com/ayberkenis/jskelet/compare/v0.1.2...v0.1.3
 [0.1.2]: https://github.com/ayberkenis/jskelet/compare/v0.1.1...v0.1.2
 [0.1.1]: https://github.com/ayberkenis/jskelet/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/ayberkenis/jskelet/releases/tag/v0.1.0

package/docs/07-yapilandirma.md

@@ -88,7 +88,7 @@ export default {
   watch: ["data"],
 
   fonts: [{ family: "Inter", weights: [400, 600, 700] }],
-  icons: { scan: ["views", "client", "routes", "lib"] },
+  icons: { dir: "icons", scan: ["views", "client", "routes", "lib"] },
   images: { widths: [400, 800, 1200], quality: 78, skip: ["indirmeler"] },
   clientEnv: ["PUBLIC_WS_URL"],
 
@@ -487,21 +487,27 @@ fonts: [
 
 ## `icons`
 
-**Tip:** `{ scan?: string[] } | false` — **Varsayılan:** `{}`
+**Tip:** `{ scan?: string[], dir?: string } | false` — **Varsayılan:** `{ dir: "icons" }`
 
-Phosphor SVG sprite üretimi.
+SVG ikon sprite üretimi. Kaynak **XOR** seçilir: `icons.dir` dizini varsa
+yalnızca oradaki düz SVG'ler; yoksa `@phosphor-icons/core` (kuruluysa).
 
 | Değer | Sonuç |
 | --- | --- |
-| `{}` (varsayılan) | Sprite üretilir; taranan dizinler `["views", "client", "routes", "lib", "features", "shared"]` |
+| `{}` (varsayılan) | `dir: "icons"`; taranan dizinler `["views", "client", "routes", "lib", "features", "shared"]` |
+| `{ dir: "assets/icons" }` | Yerel SVG kökü değiştirilir |
 | `{ scan: [...] }` | Taranan dizinler değiştirilir |
 | `false` | Sprite adımı tamamen atlanır |
 
-`@phosphor-icons/core` uygulamanın `node_modules`'ünde yoksa adım sessizce
-atlanır. Ayrıntı: [08-build.md](./08-build.md).
+Yerel dizin (varsa) düz dosya adları kullanır: `house.svg` → `house:regular`,
+`house-bold.svg` → `house:bold`. Boş bir `icons/` dizini Phosphor'a düşmez —
+dizini silmek fallback'i açar. Ayrıntı: [08-build.md](./08-build.md).
 
 ```js
-icons: { scan: ["views", "client", "routes", "lib", "content"] }
+icons: {
+  dir: "icons",
+  scan: ["views", "client", "routes", "lib", "content"],
+}
 ```
 
 ## `images`

package/docs/08-build.md

@@ -249,16 +249,32 @@ bu dosyalara otomatik olarak `immutable` cache yazılır.
 
 ## İkon sprite
 
-`@phosphor-icons/core` içindeki tek tek SVG'lerden, **yalnızca kaynakta
-kullanılan** ikonlar için `<symbol>` seti üretir. Tüm seti göndermek 1500+ ikon,
-yani birkaç megabayt; kullanım taraması sprite'ı tipik olarak 10-30 sembolde
-tutuyor.
+**Yalnızca kaynakta kullanılan** ikonlar için bir `<symbol>` seti üretir. Tüm
+seti göndermek 1500+ ikon, yani birkaç megabayt; kullanım taraması sprite'ı
+tipik olarak 10-30 sembolde tutuyor. Çıktı hash'li `sprite.svg` olarak
+`public/assets/` altına yazılır ve precompress kapsamına girer.
+
+Kaynak **XOR** seçilir — ikisi birleştirilmez:
+
+1. `icons.dir` (varsayılan `icons/`) **dizin olarak varsa** yalnızca oradaki
+   düz SVG'ler. Boş dizin Phosphor'a düşmez; fallback için dizini silin.
+2. Aksi hâlde `@phosphor-icons/core` (uygulamanın `node_modules`'ünden). Kurulu
+   değilse adım sessizce atlanır.
+
+Yerel dosya adları:
+
+| Dosya | Sprite anahtarı |
+| --- | --- |
+| `icons/house.svg` | `house:regular` |
+| `icons/house-regular.svg` | `house:regular` |
+| `icons/arrow-right-bold.svg` | `arrow-right:bold` |
 
 - Sembol id'si: `<kebab-ad>-<weight>`, örn. `arrow-right-bold`.
-- Paket **uygulamanın** `node_modules`'ünden çözülür (ikon seti uygulamanın
-  devDependency'si); kurulu değilse adım sessizce atlanır.
-- Taranan dizinler varsayılan olarak `views`, `client`, `routes`, `lib`;
-  `icons.scan` ile değiştirilebilir. Taranan uzantılar: `.ejs`, `.js`, `.mjs`.
+- `viewBox` kaynak SVG'den `<symbol>`'e taşınır; yoksa `0 0 256 256`
+  (Phosphor ve `icon()` ile uyum için önerilen kutu).
+- Taranan dizinler varsayılan olarak `views`, `client`, `routes`, `lib`,
+  `features`, `shared`; `icons.scan` ile değiştirilebilir. Taranan uzantılar:
+  `.ejs`, `.jsk`, `.js`, `.mjs`.
 - Ağırlıklar: `thin`, `light`, `regular`, `bold`, `fill`, `duotone`. Tanınmayan
   bir ağırlık `regular` sayılır.
 
@@ -285,7 +301,7 @@ Bu uyarıyı görürseniz ya adı sabit yazın, ya `icons.scan` listesine ilgili
 dizini ekleyin, ya da adı bir yapılandırma alanında `icon: "XLogo"` biçiminde
 tutun.
 
-Phosphor'da bulunamayan adlar build sonunda özet olarak uyarılır:
+Kaynakta bulunamayan adlar build sonunda özet olarak uyarılır:
 `N icons missing → …`
 
 ## Görsel optimizasyonu
@@ -355,7 +371,7 @@ Bu dosyaları `staticPrecompressed` middleware'i servis eder; kopya yoksa istek
 | `tailwindcss` | CSS (peer) | Tailwind direktifleri çözülemez |
 | `lightningcss` | CSS minifikasyonu | Tailwind çıktısı kullanılır, birkaç kB daha büyük |
 | `sharp` | Görsel optimizasyonu | Adım atlanır; `image()` orijinali kullanır |
-| `@phosphor-icons/core` | İkon sprite | Adım atlanır; `icon()` boş `<use>` üretir |
+| `@phosphor-icons/core` | İkon sprite (yerel `icons/` yoksa) | Adım atlanır; `icon()` boş `<use>` üretir |
 
 CSS kullanmayacaksanız `paths.styles` dosyasını hiç oluşturmayın: adım uyarıyla
 atlanır ve postcss'e ihtiyaç kalmaz.

package/docs/en/07-configuration.md

@@ -92,7 +92,7 @@ export default {
   watch: ["data"],
 
   fonts: [{ family: "Inter", weights: [400, 600, 700] }],
-  icons: { scan: ["views", "client", "routes", "lib"] },
+  icons: { dir: "icons", scan: ["views", "client", "routes", "lib"] },
   images: { widths: [400, 800, 1200], quality: 78, skip: ["downloads"] },
   clientEnv: ["PUBLIC_WS_URL"],
 
@@ -500,21 +500,29 @@ fonts: [
 
 ## `icons`
 
-**Type:** `{ scan?: string[] } | false` — **Default:** `{}`
+**Type:** `{ scan?: string[], dir?: string } | false` — **Default:** `{ dir: "icons" }`
 
-Phosphor SVG sprite generation.
+SVG icon sprite generation. The source is chosen **XOR**: if the `icons.dir`
+directory exists, only the flat SVGs there are used; otherwise
+`@phosphor-icons/core` (when installed).
 
 | Value | Result |
 | --- | --- |
-| `{}` (default) | The sprite is generated; scanned directories are `["views", "client", "routes", "lib"]` |
+| `{}` (default) | `dir: "icons"`; scanned directories are `["views", "client", "routes", "lib", "features", "shared"]` |
+| `{ dir: "assets/icons" }` | Changes the local SVG root |
 | `{ scan: [...] }` | Changes the scanned directories |
 | `false` | The sprite step is skipped entirely |
 
-If `@phosphor-icons/core` is not in the application's `node_modules`, the step is
-silently skipped. Details: [08-build.md](./08-build.md).
+A local directory (when present) uses flat file names: `house.svg` →
+`house:regular`, `house-bold.svg` → `house:bold`. An empty `icons/` directory
+does not fall back to Phosphor — delete the directory to open the fallback.
+Details: [08-build.md](./08-build.md).
 
 ```js
-icons: { scan: ["views", "client", "routes", "lib", "content"] }
+icons: {
+  dir: "icons",
+  scan: ["views", "client", "routes", "lib", "content"],
+}
 ```
 
 ## `images`

package/docs/en/08-build.md

@@ -259,17 +259,33 @@ Because the `.woff2` extension and the `/fonts/` prefix are in the default
 
 ## Icon sprite
 
-From the individual SVGs inside `@phosphor-icons/core`, it produces a `<symbol>`
-set for **only the icons actually used in the source**. Shipping the whole set
-means 1500+ icons, i.e. several megabytes; usage scanning typically keeps the
-sprite at 10-30 symbols.
+Produces a `<symbol>` set for **only the icons actually used in the source**.
+Shipping the whole set means 1500+ icons, i.e. several megabytes; usage scanning
+typically keeps the sprite at 10-30 symbols. The hashed `sprite.svg` is written
+under `public/assets/` and is covered by precompress.
+
+The source is chosen **XOR** — the two are never merged:
+
+1. If `icons.dir` (default `icons/`) **exists as a directory**, only the flat
+   SVGs there. An empty directory does not fall back to Phosphor; delete the
+   directory to open the fallback.
+2. Otherwise `@phosphor-icons/core` (from the application's `node_modules`). If
+   it is not installed, the step is silently skipped.
+
+Local file names:
+
+| File | Sprite key |
+| --- | --- |
+| `icons/house.svg` | `house:regular` |
+| `icons/house-regular.svg` | `house:regular` |
+| `icons/arrow-right-bold.svg` | `arrow-right:bold` |
 
 - Symbol id: `<kebab-name>-<weight>`, e.g. `arrow-right-bold`.
-- The package is resolved from the **application's** `node_modules` (the icon set
-  is the application's devDependency); if it is not installed, the step is
-  silently skipped.
-- The scanned directories default to `views`, `client`, `routes`, `lib`; they can
-  be changed with `icons.scan`. Scanned extensions: `.ejs`, `.js`, `.mjs`.
+- `viewBox` is copied from the source SVG onto the `<symbol>`; if missing,
+  `0 0 256 256` (recommended for Phosphor / `icon()` compatibility).
+- The scanned directories default to `views`, `client`, `routes`, `lib`,
+  `features`, `shared`; they can be changed with `icons.scan`. Scanned
+  extensions: `.ejs`, `.jsk`, `.js`, `.mjs`.
 - Weights: `thin`, `light`, `regular`, `bold`, `fill`, `duotone`. An
   unrecognised weight counts as `regular`.
 
@@ -296,8 +312,8 @@ If you see this warning, either write the name as a constant, or add the relevan
 directory to the `icons.scan` list, or keep the name in a configuration field in
 the form `icon: "XLogo"`.
 
-Names that cannot be found in Phosphor are warned about as a summary at the end
-of the build: `N icons missing → …`
+Names that cannot be found in the chosen source are warned about as a summary at
+the end of the build: `N icons missing → …`
 
 ## Image optimisation
 
@@ -373,7 +389,7 @@ copy, the request is handed over to `express.static`
 | `tailwindcss` | CSS (peer) | Tailwind directives cannot be resolved |
 | `lightningcss` | CSS minification | Tailwind's output is used, a few kB bigger |
 | `sharp` | Image optimisation | The step is skipped; `image()` uses the original |
-| `@phosphor-icons/core` | Icon sprite | The step is skipped; `icon()` produces an empty `<use>` |
+| `@phosphor-icons/core` | Icon sprite (when no local `icons/` dir) | The step is skipped; `icon()` produces an empty `<use>` |
 
 If you are not going to use CSS, simply never create the `paths.styles` file: the
 step is skipped with a warning and postcss is not needed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jskelet",
-  "version": "0.5.4",
+  "version": "0.5.5",
   "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",

package/src/build/tasks/icons.mjs

@@ -1,12 +1,17 @@
 /**
- * Phosphor SVG sprite üretimi.
+ * SVG ikon sprite üretimi.
  *
- * `@phosphor-icons/core` içindeki tek tek SVG'lerden, **yalnızca kaynakta
- * kullanılan** ikonlar için `<symbol>` seti üretir. Tüm seti göndermek 1500+
- * ikon, yani birkaç megabayt; kullanım taraması sprite'ı tipik olarak 10-30
- * sembolde tutuyor.
+ * Kaynak XOR seçilir: uygulama kökünde `icons/` (veya `icons.dir`) dizini
+ * varsa yalnızca oradaki düz SVG'ler; yoksa `@phosphor-icons/core`. İkisi
+ * birleştirilmez — boş bir `icons/` dizini Phosphor'a düşmez.
+ *
+ * Yalnızca kaynakta kullanılan ikonlar `<symbol>` olur. Tüm seti göndermek
+ * 1500+ ikon, yani birkaç megabayt; kullanım taraması sprite'ı tipik olarak
+ * 10-30 sembolde tutuyor. Çıktı `public/assets/` altında hash'li
+ * `sprite.svg` olduğu için mevcut precompress kapsamına girer.
  *
  * Sembol id'si: `<kebab-name>-<weight>` (örn. `arrow-right-bold`).
+ * Yerel dosya adı: `house.svg` → `house:regular`, `house-bold.svg` → `house:bold`.
  *
  * Tarama statik metin üzerinden yapıldığı için adı çalışma anında hesaplanan
  * bir `icon()` çağrısı sprite'a girmez. Bu yüzden ad taşıyan yapılandırma
@@ -41,6 +46,8 @@ const QUOTED_NAME = /["']([A-Z][A-Za-z0-9]*)["']/g;
 
 const WEIGHTS = new Set(["thin", "light", "regular", "bold", "fill", "duotone"]);
 
+const DEFAULT_VIEWBOX = "0 0 256 256";
+
 /**
  * `ArrowRightIcon` → `arrow-right`
  * @param {string} name
@@ -54,6 +61,50 @@ function toKebab(name) {
     .toLowerCase();
 }
 
+/**
+ * Düz dizin dosya adı → `name` + `weight`.
+ * `house.svg` / `house-regular.svg` → regular; `arrow-right-bold.svg` → bold.
+ *
+ * @param {string} fileName uzantılı veya uzantısız
+ * @returns {{ name: string, weight: string } | null}
+ */
+export function parseIconFileName(fileName) {
+  const base = String(fileName).replace(/\.svg$/i, "");
+  if (!base) return null;
+
+  let name = base;
+  let weight = "regular";
+
+  const dash = base.lastIndexOf("-");
+  if (dash > 0) {
+    const maybeWeight = base.slice(dash + 1);
+    if (WEIGHTS.has(maybeWeight)) {
+      name = base.slice(0, dash);
+      weight = maybeWeight;
+    }
+  }
+
+  // kebab: harf/rakam segmentleri, başta/sonda tire yok
+  if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name)) return null;
+
+  return { name, weight };
+}
+
+/**
+ * @param {import('../../config/index.js').ResolvedConfig} config
+ * @returns {string | null} mutlak dizin; yoksa veya dizin değilse null
+ */
+function resolveLocalIconsDir(config) {
+  const relative = config.icons?.dir ?? "icons";
+  const dir = path.resolve(config.root, relative);
+  try {
+    if (fs.statSync(dir).isDirectory()) return dir;
+  } catch {
+    // yok
+  }
+  return null;
+}
+
 /**
  * Paket, framework'ün değil **uygulamanın** node_modules'ünden çözülür:
  * ikon seti uygulamanın devDependency'si.
@@ -160,21 +211,80 @@ function scanUsedIcons(scanDirs) {
   return used;
 }
 
+/**
+ * @param {string} svg
+ * @returns {{ body: string, viewBox: string }}
+ */
+function parseSvgParts(svg) {
+  const open = svg.match(/<svg\b[^>]*>/i)?.[0] ?? "";
+  const viewBox =
+    open.match(/\bviewBox\s*=\s*["']([^"']+)["']/i)?.[1]?.trim() ||
+    DEFAULT_VIEWBOX;
+  const body = svg
+    .replace(/^[\s\S]*?<svg[^>]*>/i, "")
+    .replace(/<\/svg>\s*$/i, "")
+    .trim();
+  return { body, viewBox };
+}
+
+/**
+ * Düz `icons/` altındaki `*.svg` dosyalarından `name:weight` → parça haritası.
+ *
+ * @param {string} dir
+ * @returns {Map<string, { body: string, viewBox: string }>}
+ */
+function indexLocalIcons(dir) {
+  /** @type {Map<string, { body: string, viewBox: string }>} */
+  const index = new Map();
+
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (!entry.isFile() || path.extname(entry.name).toLowerCase() !== ".svg") {
+      continue;
+    }
+
+    const parsed = parseIconFileName(entry.name);
+    if (!parsed) {
+      log.warn(`icon file ignored (bad name) → ${entry.name}`);
+      continue;
+    }
+
+    const key = `${parsed.name}:${parsed.weight}`;
+    const svg = fs.readFileSync(path.join(dir, entry.name), "utf8");
+    index.set(key, parseSvgParts(svg));
+  }
+
+  return index;
+}
+
 /**
  * @param {string} coreAssets
  * @param {string} name kebab
  * @param {string} weight
- * @returns {string | null}
+ * @returns {{ body: string, viewBox: string } | null}
  */
-function readIconBody(coreAssets, name, weight) {
+function readPhosphorIcon(coreAssets, name, weight) {
   const fileName = weight === "regular" ? `${name}.svg` : `${name}-${weight}.svg`;
   const filePath = path.join(coreAssets, weight, fileName);
 
   if (!fs.existsSync(filePath)) return null;
 
-  const svg = fs.readFileSync(filePath, "utf8");
-  const inner = svg.replace(/^[\s\S]*?<svg[^>]*>/, "").replace(/<\/svg>\s*$/, "");
-  return inner.trim();
+  return parseSvgParts(fs.readFileSync(filePath, "utf8"));
+}
+
+/**
+ * @param {Map<string, { body: string, viewBox: string }>} index
+ * @param {string} name
+ * @param {string} weight
+ * @returns {{ body: string, viewBox: string } | null}
+ */
+function readLocalIcon(index, name, weight) {
+  const exact = index.get(`${name}:${weight}`);
+  if (exact) return exact;
+
+  // `house.svg` regular sayılır; tarama `house:regular` ister.
+  if (weight === "regular") return index.get(`${name}:regular`) ?? null;
+
+  return null;
 }
 
 /**
@@ -182,10 +292,22 @@ function readIconBody(coreAssets, name, weight) {
  * @returns {Promise<Record<string, string>>}
  */
 export async function buildIconSprite(config) {
-  const coreAssets = resolveIconAssets(config.root);
-  if (!coreAssets) {
-    log.detail("@phosphor-icons/core not installed, skipped");
-    return {};
+  const localDir = resolveLocalIconsDir(config);
+  /** @type {Map<string, { body: string, viewBox: string }> | null} */
+  let localIndex = null;
+  /** @type {string | null} */
+  let coreAssets = null;
+
+  if (localDir) {
+    localIndex = indexLocalIcons(localDir);
+    const rel = path.relative(config.root, localDir) || ".";
+    log.detail(`icons from ${rel} (${localIndex.size} files)`);
+  } else {
+    coreAssets = resolveIconAssets(config.root);
+    if (!coreAssets) {
+      log.detail("@phosphor-icons/core not installed, skipped");
+      return {};
+    }
   }
 
   const scanDirs = (
@@ -198,15 +320,17 @@ export async function buildIconSprite(config) {
 
   for (const entry of used) {
     const [name, weight] = entry.split(":");
-    const body = readIconBody(coreAssets, name, weight);
+    const parts = localIndex
+      ? readLocalIcon(localIndex, name, weight)
+      : readPhosphorIcon(/** @type {string} */ (coreAssets), name, weight);
 
-    if (!body) {
+    if (!parts?.body) {
       missing.push(entry);
       continue;
     }
 
     symbols.push(
-      `<symbol id="${name}-${weight}" viewBox="0 0 256 256">${body}</symbol>`,
+      `<symbol id="${name}-${weight}" viewBox="${parts.viewBox}">${parts.body}</symbol>`,
     );
   }
 

package/src/config/index.js

@@ -141,7 +141,7 @@ const CONFIG_FILE = "jskelet.config.mjs";
  * @property {string[]} prewarmSkip
  * @property {string[]} watch Dev sunucusunun izlediği ek dizinler.
  * @property {{ family: string, slug?: string, weights: number[] }[]} fonts
- * @property {{ scan?: string[] } | false} icons
+ * @property {{ scan?: string[], dir: string } | false} icons
  * @property {ImagesConfig | false} images
  * @property {string[]} clientEnv Client bundle'a gömülecek env anahtarları.
  */
@@ -987,6 +987,34 @@ function normalizeSecurity(raw) {
   };
 }
 
+/**
+ * İkon sprite ayarları. `false` → adım atlanır. `dir` varsayılanı `"icons"`:
+ * o dizin varsa yalnızca yerel SVG'ler; yoksa Phosphor.
+ *
+ * @param {unknown} raw
+ * @returns {{ scan?: string[], dir: string } | false}
+ */
+function normalizeIcons(raw) {
+  if (raw === false) return false;
+
+  const source = /** @type {Record<string, any>} */ (raw ?? {});
+  const dir =
+    typeof source.dir === "string" && source.dir.trim()
+      ? source.dir.trim()
+      : "icons";
+
+  /** @type {{ scan?: string[], dir: string }} */
+  const icons = { dir };
+
+  if (source.scan != null) {
+    icons.scan = asArray(source.scan, "icons.scan")
+      .filter((entry) => typeof entry === "string" && entry.trim())
+      .map((entry) => String(entry).trim());
+  }
+
+  return icons;
+}
+
 /**
  * Build + runtime görsel ayarları. `false` → her iki yüzey de kapalı.
  * `remote.allowHosts` boşsa remote kapalı kalır (açık proxy olmasın).
@@ -1237,7 +1265,7 @@ export async function loadConfig(options = {}) {
     // Build tarafı ayarları. Sunucu bunları okumaz ama config tek dosya
     // olsun diye aynı yerden geçer.
     fonts: source.fonts ?? [],
-    icons: source.icons ?? {},
+    icons: normalizeIcons(source.icons),
     images: normalizeImages(source.images),
     clientEnv: source.clientEnv ?? [],
   };