jskelet 0.4.2 → 0.4.4

package/CHANGELOG.md

@@ -24,9 +24,24 @@ one is listed under a **Breaking** heading.
   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.
 
 ### 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
@@ -144,6 +159,14 @@ one is listed under a **Breaking** heading.
   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

package/docs/09-dev-araclari.md

@@ -170,9 +170,9 @@ basılır:
 ```
 
 Overlay dosyası **build'e dâhil değildir.** Sunucu onu framework paketinden ham
-olarak servis eder; bu yüzden içinde bundler yoktur, tek dosya olarak çalışır ve
-prod çıktısına hiçbir şey eklemez. Tüm arayüz shadow DOM içinde durur, sayfanın
-CSS'i ile karışmaz.
+olarak servis eder; bundler yoktur. Aynı dizindeki `seo.js` gibi kardeş
+modüller native ESM import ile yüklenir ve prod çıktısına hiçbir şey eklenmez.
+Tüm arayüz shadow DOM içinde durur, sayfanın CSS'i ile karışmaz.
 
 Gösterdikleri:
 
@@ -180,6 +180,14 @@ Gösterdikleri:
   (`img`/`script`/`link`), ve sunucudaki `console.error` / `console.warn`
   çıktıları. Sunucu tarafında `console` sarılır, böylece uyarılar terminalde
   kaybolmaz.
+- **SEO:** açık sayfanın istemci tarafı taraması — title ve meta description
+  uzunluğu, `html lang`, viewport, canonical, robots/`noindex`, Open Graph ve
+  Twitter etiketleri, H1/outline, görsel `alt`, boş linkler ve JSON-LD parse
+  hataları. Bulgular panelde listelenir; **Highlight issues on the page**
+  açılınca sorunlu elemanların üzerine kırmızı (error) veya sarı (warning)
+  dikdörtgenler çizilir, kenarda kısa başlık durur. Etikete (ya da panel
+  satırına) tıklanınca ayrıntılı açıklama açılır. Tarama overlay'in yanındaki
+  `/seo.js` dosyasındadır; production paketine girmez.
 - **İstekler:** her HTML isteğinin metodu, yolu, durumu, süresi ve
   `X-JSkelet-Cache` değeri. Aynı satırlar terminale de basılır.
 - **Web Vitals:** TTFB, FCP, LCP, CLS, INP, DCL, load, uzun task sayısı ve
@@ -261,6 +269,7 @@ Rapor katmanı yalnızca development'ta yüklenir, üretim çıktısına hiç gi
 | Yol | Metot | İşi |
 | --- | --- | --- |
 | `/overlay.js` | GET | Overlay script'i |
+| `/seo.js` | GET | SEO tarama + sayfa highlight yardımcısı (overlay import eder) |
 | `/logo.png` | GET | Overlay logosu |
 | `/ws` | GET (upgrade) | Canlı kanal: istatistikler, live reload ve CSS hot-swap olayları |
 | `/events` | GET | SSE: yalnızca WebSocket kurulamazsa kullanılan yedek olay akışı |

package/docs/README.md

@@ -24,7 +24,7 @@ eşlenik tutuluyor; birini değiştiriyorsan diğerini de değiştir.
 | [06-cache.md](./06-cache.md) | `withHtmlCache`, `revalidate`, stale-while-revalidate, cache anahtarı, `X-JSkelet-Cache`, istek içi cache, degraded render, prewarm |
 | [07-yapilandirma.md](./07-yapilandirma.md) | `jskelet.config.mjs` tam referansı, `source` desen sözdizimi, ortam değişkenleri tablosu |
 | [08-build.md](./08-build.md) | Build hattı, manifest, hash'li varlıklar, CSS/Tailwind `@source`, fontlar, ikon sprite, görsel optimizasyonu, precompress |
-| [09-dev-araclari.md](./09-dev-araclari.md) | `jskelet dev` akışı, watch dizinleri, CSS hot-swap, devtools overlay (Alt+D), rapor sayfası, dev gate |
+| [09-dev-araclari.md](./09-dev-araclari.md) | `jskelet dev` akışı, watch dizinleri, CSS hot-swap, devtools overlay (Alt+D, SEO highlight), rapor sayfası, dev gate |
 | [10-dagitim.md](./10-dagitim.md) | Prod build + start, ortam değişkenleri, Docker, ters proxy, sağlık kontrolü |
 | [11-tasima.md](./11-tasima.md) | Next.js'ten taşıma: karşılık tablosu ve adım adım plan |
 | [12-panel-ve-oturum.md](./12-panel-ve-oturum.md) | Kişiye özel sayfalar: `private: true`, imzalı cookie oturumu, CSRF, `fragment()`, parça takası ve form döngüsü |

package/docs/en/09-dev-tools.md

@@ -173,9 +173,10 @@ by clicking the backdrop. It is only emitted by the layout when
 ```
 
 The overlay file is **not part of the build.** The server serves it raw from the
-framework package; that is why there is no bundler involved, it works as a
-single file, and it adds nothing to the production output. The entire UI lives
-inside a shadow DOM and does not mix with the page's CSS.
+framework package; that is why there is no bundler involved. It loads sibling
+modules such as `seo.js` with native ESM imports, and it adds nothing to the
+production output. The entire UI lives inside a shadow DOM and does not mix with
+the page's CSS.
 
 What it shows:
 
@@ -183,6 +184,14 @@ What it shows:
   (`img`/`script`/`link`), and the server's `console.error` / `console.warn`
   output. On the server side `console` is wrapped so warnings do not get lost in
   the terminal.
+- **SEO:** a client-side scan of the current page — title and meta description
+  length, `html lang`, viewport, canonical, robots/`noindex`, Open Graph and
+  Twitter tags, H1/outline, image `alt`, empty links, and JSON-LD parse errors.
+  Findings appear in the panel; turning on **Highlight issues on the page**
+  draws red (error) or yellow (warning) boxes on the elements, with a short
+  title on the border. Clicking the label (or a row in the panel) opens the
+  full explanation. The scan lives in `/seo.js` next to the overlay and is not
+  part of the production bundle.
 - **Requests:** the method, path, status, duration and `X-JSkelet-Cache` value
   of every HTML request. The same lines are printed to the terminal too.
 - **Web Vitals:** TTFB, FCP, LCP, CLS, INP, DCL, load, long task count and
@@ -265,6 +274,7 @@ Under `brand.devBasePath` (default `/__jskelet/dev`):
 | Path | Method | Job |
 | --- | --- | --- |
 | `/overlay.js` | GET | The overlay script |
+| `/seo.js` | GET | SEO scan + page highlight helper (imported by the overlay) |
 | `/logo.png` | GET | The overlay logo |
 | `/ws` | GET (upgrade) | Live channel: statistics, live reload and CSS hot-swap events |
 | `/events` | GET | SSE: the fallback event stream, used only when WebSocket cannot be established |

package/docs/en/README.md

@@ -27,7 +27,7 @@ change one, change the other.
 | [06-caching.md](./06-caching.md) | `withHtmlCache`, `revalidate`, stale-while-revalidate, the cache key, `X-JSkelet-Cache`, in-request cache, degraded render, prewarm |
 | [07-configuration.md](./07-configuration.md) | Full `jskelet.config.mjs` reference, the `source` pattern syntax, environment variable table |
 | [08-build.md](./08-build.md) | The build pipeline, the manifest, hashed assets, CSS/Tailwind `@source`, fonts, icon sprite, image optimization, precompress |
-| [09-dev-tools.md](./09-dev-tools.md) | The `jskelet dev` flow, watch directories, CSS hot-swap, devtools overlay (Alt+D), the report page, the dev gate |
+| [09-dev-tools.md](./09-dev-tools.md) | The `jskelet dev` flow, watch directories, CSS hot-swap, devtools overlay (Alt+D, SEO highlight), the report page, the dev gate |
 | [10-deployment.md](./10-deployment.md) | Prod build + start, environment variables, Docker, reverse proxy, health check |
 | [11-migration.md](./11-migration.md) | Migrating from Next.js: the equivalence table and a step-by-step plan |
 | [12-dashboards-and-sessions.md](./12-dashboards-and-sessions.md) | Per-visitor pages: `private: true`, signed cookie sessions, CSRF, `fragment()`, swapping regions and the form loop |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jskelet",
-  "version": "0.4.2",
+  "version": "0.4.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",

package/src/build/paths.mjs

@@ -131,13 +131,23 @@ export function patchManifest(key, url) {
 /**
  * Eski hash'li çıktıları temizler.
  *
+ * Yeni dosya **önce** yazılmalı, prune sonra gelmeli: aynı içerik aynı hash'i
+ * üretir ve önce silmek `/assets/app.<hash>.css` için kısa bir 404 penceresi
+ * açar. CDN o 404'ü `immutable` ile saklarsa (eski headersMiddleware
+ * davranışı) tarayıcı bir yıl boyunca stilsiz kalır.
+ *
  * @param {string[]} prefixes
+ * @param {{ keep?: string[] }} [options] Korunacak dosya adları (ör. yeni
+ *   yazılan `app.<hash>.css`); `.br` / `.gz` sonekleri de eşleşir.
  */
-export function pruneAssets(prefixes) {
+export function pruneAssets(prefixes, { keep = [] } = {}) {
   if (!fs.existsSync(paths.assets)) return;
+
   for (const file of fs.readdirSync(paths.assets)) {
-    if (prefixes.some((prefix) => file.startsWith(prefix))) {
-      fs.rmSync(path.join(paths.assets, file), { force: true });
+    if (!prefixes.some((prefix) => file.startsWith(prefix))) continue;
+    if (keep.some((name) => file === name || file.startsWith(`${name}.`))) {
+      continue;
     }
+    fs.rmSync(path.join(paths.assets, file), { force: true });
   }
 }

package/src/build/tasks/css.mjs

@@ -64,9 +64,11 @@ export async function buildCss(config, { watch = false } = {}) {
 
   const run = async () => {
     const started = Date.now();
-    pruneAssets(["app."]);
     const css = await compile(input);
+    // Önce yaz, sonra eski hash'leri sil — aynı hash'e düşen içerikte 404
+    // penceresi olmasın (CDN immutable zehirlenmesi).
     const url = writeAsset("app.css", css);
+    pruneAssets(["app."], { keep: [path.basename(url)] });
     return { url, bytes: Buffer.byteLength(css), elapsed: Date.now() - started };
   };
 

package/src/build/tasks/icons.mjs

@@ -192,8 +192,6 @@ export async function buildIconSprite(config) {
     config.icons?.scan ?? ["views", "client", "routes", "lib", "features", "shared"]
   ).map((dir) => path.resolve(config.root, dir));
 
-  pruneAssets(["sprite."]);
-
   const used = [...scanUsedIcons(scanDirs)].sort();
   const symbols = [];
   const missing = [];
@@ -214,6 +212,7 @@ export async function buildIconSprite(config) {
 
   const sprite = `<svg xmlns="http://www.w3.org/2000/svg" style="display:none">${symbols.join("")}</svg>`;
   const url = writeAsset("sprite.svg", sprite);
+  pruneAssets(["sprite."], { keep: [path.basename(url)] });
 
   log.detail(`${symbols.length} symbols`);
   if (missing.length) {

package/src/client/devtools/overlay.js

@@ -1,15 +1,17 @@
 /**
- * Dev overlay: sağ altta yüzen baloncuk; hataları ve performans
- * istatistiklerini gösterir.
+ * Dev overlay: sağ altta yüzen baloncuk; hataları, performans
+ * istatistiklerini ve SEO taramasını gösterir.
  *
  * Bu dosya **build'e dahil değildir**. `npm run dev` sırasında sunucu onu
  * `/__jskelet/dev/overlay.js` altından ham olarak servis eder, layout da
- * script etiketini yalnızca development'ta basar. Bu yüzden burada bundler
- * yok: import yapmadan, tek dosya olarak çalışır.
+ * script etiketini yalnızca development'ta basar. Bundler yok: yalnızca aynı
+ * dizindeki `seo.js` gibi native ESM import'ları kullanılır.
  *
  * Tüm arayüz shadow DOM içinde durur; sayfanın CSS'i ile karışmaz.
  */
 
+import { scanSeo, SeoHighlighter } from "./seo.js";
+
 const BASE = "/__jskelet/dev";
 /** Soket kurulamadığında düşülen yedek yoklama sıklığı. */
 const POLL_MS = 2000;
@@ -40,6 +42,19 @@ let open = false;
 /** Açık bırakılan yığın izleri; panel her poll'da yeniden çizildiği için gerekir. */
 let expanded = new Set();
 
+/** Sayfa üzeri SEO dikdörtgenleri; panel kapalıyken de açık kalabilir. */
+let seoHighlight = false;
+/** Panel listesinde açılan sorun açıklaması. */
+let seoExpandedId = null;
+/** @type {import('./seo.js').SeoIssue[]} */
+let seoIssues = [];
+const seoLayer = new SeoHighlighter();
+seoLayer.onSelect = (id) => {
+  seoExpandedId = id;
+  lastBody = "";
+  render();
+};
+
 /**
  * Sunucu `node --watch` ile yeniden başladığında ya da sayfa tazelendiğinde
  * panelin kapanmaması için görünüm durumu ve tarayıcı hata günlüğü sekme
@@ -60,6 +75,8 @@ function saveState() {
         open,
         activeTab,
         aboutSection,
+        seoHighlight,
+        seoExpandedId,
         expanded: [...expanded],
         errors: clientErrors.slice(0, 30),
       }),
@@ -77,6 +94,8 @@ function loadState() {
     open = Boolean(saved.open);
     activeTab = saved.activeTab ?? "errors";
     aboutSection = saved.aboutSection ?? "framework";
+    seoHighlight = Boolean(saved.seoHighlight);
+    seoExpandedId = saved.seoExpandedId ?? null;
     expanded = new Set(saved.expanded ?? []);
     clientErrors.push(...(saved.errors ?? []));
     nextId = Math.max(nextId, ...clientErrors.map((item) => item.id + 1));
@@ -826,12 +845,43 @@ h4:first-child { margin-top: 0; }
   padding: 9px 11px; margin-bottom: 8px;
 }
 .item.warn { border-inline-start-color: var(--mid); }
+.item.selected { border-color: rgba(255,255,255,.22); background: var(--surface-hover); }
 .item .meta { color: var(--muted); font-size: 10.5px; display: flex; align-items: center; gap: 8px; margin-bottom: 3px; }
 .tag { border: 1px solid var(--line); border-radius: 999px; padding: 0 7px; text-transform: uppercase; letter-spacing: .05em; font-weight: 600; font-size: 9.5px; }
 .msg { word-break: break-word; color: var(--text); }
 .item pre { margin: 8px 0 0; padding: 8px 10px; background: rgba(0,0,0,.4); border-radius: 8px; white-space: pre-wrap; word-break: break-word; color: #b8c0cb; font-size: 11px; font-family: ui-monospace, SFMono-Regular, monospace; max-height: 150px; overflow: auto; }
+.item .detail-text { margin: 8px 0 0; color: #b8c0cb; font-size: 12px; line-height: 1.55; }
 .link { background: none; border: 0; padding: 0; margin-top: 6px; color: var(--muted); font-size: 11px; font-weight: 600; cursor: pointer; }
 .link:hover { color: var(--text); }
+.item.clickable { cursor: pointer; }
+.item.clickable:hover { border-color: var(--line); }
+
+.toggle-row {
+  display: flex; align-items: center; justify-content: space-between; gap: 12px;
+  margin: 12px 0 4px; padding: 10px 12px; border-radius: 12px;
+  background: var(--surface); border: 1px solid var(--line);
+}
+.toggle-row span { color: #c6ced9; font-size: 12px; }
+.toggle {
+  position: relative; width: 36px; height: 20px; border-radius: 999px; border: 0;
+  background: rgba(255,255,255,.12); cursor: pointer; flex: none;
+  transition: background .15s ease;
+}
+.toggle.on { background: rgba(52,211,153,.45); }
+.toggle i {
+  position: absolute; top: 2px; left: 2px; width: 16px; height: 16px; border-radius: 50%;
+  background: #fff; transition: transform .15s ease;
+}
+.toggle.on i { transform: translateX(16px); }
+
+.seo-chip {
+  display: inline-flex; align-items: center; gap: 6px; white-space: nowrap;
+  padding: 5px 11px; border-radius: 999px; border: 1px solid var(--line);
+  background: rgba(12,14,18,.92); color: #cfd6de; font-size: 11.5px; font-weight: 600;
+  box-shadow: 0 8px 24px rgba(0,0,0,.4); cursor: pointer;
+}
+.seo-chip.bad { color: #ffd7de; border-color: rgba(251,113,133,.4); }
+.seo-chip.warn { color: #ffeec2; border-color: rgba(251,191,36,.4); }
 
 .copy {
   display: inline-flex; align-items: center; gap: 5px; cursor: pointer;
@@ -891,6 +941,7 @@ let shadow = null;
  */
 const TAB_ICONS = {
   errors: `<svg viewBox="0 0 16 16"><path d="M8 5.5v4M8 11.5h.01M8 1.8 1.8 13.2h12.4L8 1.8Z"/></svg>`,
+  seo: `<svg viewBox="0 0 16 16"><circle cx="7.2" cy="7.2" r="4.4"/><path d="M10.4 10.4 13.6 13.6M5.2 7.2h4M7.2 5.2v4"/></svg>`,
   perf: `<svg viewBox="0 0 16 16"><path d="M2 13V8m4 5V3m4 10V6m4 7v-3"/></svg>`,
   server: `<svg viewBox="0 0 16 16"><path d="M2.5 3.5h11v3h-11zM2.5 9.5h11v3h-11zM5 5h.01M5 11h.01"/></svg>`,
   warm: `<svg viewBox="0 0 16 16"><path d="M8 14c2.5 0 4.2-1.7 4.2-3.9C12.2 6.5 8 2 8 2S3.8 6.5 3.8 10.1C3.8 12.3 5.5 14 8 14Z"/></svg>`,
@@ -916,6 +967,7 @@ const SKELETON = `
         </div>
         <div class="rail">
           <button class="tab" data-tab="errors">${TAB_ICONS.errors} Errors<span class="chip" data-part="chip" hidden></span></button>
+          <button class="tab" data-tab="seo">${TAB_ICONS.seo} SEO<span class="chip" data-part="seo-chip" hidden></span></button>
           <button class="tab" data-tab="perf">${TAB_ICONS.perf} Performance</button>
           <button class="tab" data-tab="server">${TAB_ICONS.server} Server<span class="chip neutral" data-part="version-chip" hidden>update</span></button>
           <button class="tab" data-tab="warm">${TAB_ICONS.warm} Prewarming<span class="chip neutral" data-part="warm-chip" hidden></span></button>
@@ -931,6 +983,7 @@ const SKELETON = `
       </div>
     </div>
     <div class="dock">
+      <button type="button" class="seo-chip" data-part="seo-dock" data-action="seo-focus" hidden></button>
       <span class="warm" data-part="warm" hidden>
         <span class="ring"></span>
         <span data-part="warm-text"></span>
@@ -1151,6 +1204,86 @@ function errorsTab() {
   `;
 }
 
+/**
+ * DOM'u yeniden tarar; highlight açıksa katmanı da günceller.
+ * @param {{ select?: string | null }} [opts]
+ */
+function refreshSeo(opts = {}) {
+  seoIssues = scanSeo(document);
+  if (seoHighlight) {
+    seoLayer.show(seoIssues, { select: opts.select ?? seoExpandedId });
+  } else if (seoLayer.active) {
+    seoLayer.hide();
+  }
+}
+
+function seoTab() {
+  refreshSeo();
+
+  const errors = seoIssues.filter((item) => item.severity === "error").length;
+  const warns = seoIssues.length - errors;
+  const tone = errors ? "bad" : warns ? "mid" : "good";
+
+  clipboard.set(
+    "seo",
+    seoIssues
+      .map(
+        (item) =>
+          `[${item.severity}] ${item.category} · ${item.title}\n${item.detail}`,
+      )
+      .join("\n\n") || "No SEO issues on this page.",
+  );
+
+  const groups = new Map();
+  for (const issue of seoIssues) {
+    const list = groups.get(issue.category) ?? [];
+    list.push(issue);
+    groups.set(issue.category, list);
+  }
+
+  const body = seoIssues.length
+    ? [...groups.entries()]
+        .map(
+          ([category, list]) => `
+      <h4>${escapeHtml(category)}</h4>
+      ${list
+        .map((issue) => {
+          const openIssue = seoExpandedId === issue.id;
+          return `<div class="item clickable ${issue.severity === "warn" ? "warn" : ""} ${openIssue ? "selected" : ""}"
+            data-action="seo-issue" data-id="${escapeHtml(issue.id)}">
+            <div class="meta">
+              <span class="tag">${escapeHtml(issue.severity)}</span>
+              <span class="spacer"></span>
+              <span>${openIssue ? "▾ details" : "▸ details"}</span>
+            </div>
+            <div class="msg">${escapeHtml(issue.title)}</div>
+            ${openIssue ? `<p class="detail-text">${escapeHtml(issue.detail)}</p>` : ""}
+          </div>`;
+        })
+        .join("")}`,
+        )
+        .join("")
+    : `<div class="empty">No SEO issues on this page.</div>`;
+
+  return `
+    ${lede(
+      tone,
+      errors || warns
+        ? `This page has <strong>${errors} SEO errors</strong> and <strong>${warns} warnings</strong>. Turn on page highlights to see red/yellow boxes on the offending elements; click a label for the full explanation.`
+        : "Document title, description, headings, images and social tags look fine on this page.",
+    )}
+    <div class="toggle-row">
+      <span>Highlight issues on the page</span>
+      <button type="button" class="toggle ${seoHighlight ? "on" : ""}" data-action="seo-toggle"
+        aria-pressed="${seoHighlight}" title="Draw boxes around SEO issues">
+        <i></i>
+      </button>
+    </div>
+    <h4>Findings<span class="head-action">${copyButton("seo", "copy all")}<button class="btn mini" data-action="seo-rescan" style="margin-inline-start:6px">${REFRESH_ICON} Rescan</button></span></h4>
+    ${body}
+  `;
+}
+
 function perfTab() {
   const resources = resourceSummary();
   const islands = islandSummary();
@@ -1740,23 +1873,38 @@ function paint() {
   const warnCount =
     clientErrors.length + (serverStats?.errors ?? []).length - errorCount;
 
-  const tone = errorCount ? "bad" : warnCount ? "warn" : "";
-  const badgeCount = errorCount || warnCount;
+  const seoErrors = seoIssues.filter((item) => item.severity === "error").length;
+  const seoWarns = seoIssues.length - seoErrors;
+
+  const tone = errorCount || seoErrors ? "bad" : warnCount || seoWarns ? "warn" : "";
+  const badgeCount = errorCount || warnCount || seoErrors || seoWarns;
   const lcpLabel = metrics.lcp ? `${Math.round(metrics.lcp)} ms` : "measuring";
 
   const bubble = root.querySelector(".bubble");
   bubble.className = `bubble ${tone}`;
   bubble.title = `JSkelet dev tools — LCP ${lcpLabel}${
-    badgeCount ? `, ${errorCount} errors, ${warnCount} warnings` : ""
+    badgeCount
+      ? `, ${errorCount} errors, ${warnCount} warnings, ${seoIssues.length} SEO`
+      : ""
   }`;
 
   const badge = root.querySelector(".badge");
   badge.hidden = !badgeCount;
-  badge.className = `badge ${errorCount ? "" : "warn"}`;
+  badge.className = `badge ${errorCount || seoErrors ? "" : "warn"}`;
   badge.textContent = badgeCount > 99 ? "99+" : String(badgeCount);
 
   paintPrewarm(root);
 
+  const seoDock = root.querySelector("[data-part='seo-dock']");
+  if (seoHighlight && seoIssues.length) {
+    seoDock.hidden = false;
+    seoDock.className = `seo-chip ${seoErrors ? "bad" : "warn"}`;
+    seoDock.textContent = `${seoIssues.length} SEO`;
+    seoDock.title = "Open SEO tab · page highlights are on";
+  } else {
+    seoDock.hidden = true;
+  }
+
   const backdrop = root.querySelector(".backdrop");
   backdrop.hidden = !open;
   if (!open) return;
@@ -1765,14 +1913,19 @@ function paint() {
   pill.className = `pill ${offline ? "warn" : tone}`;
   pill.querySelector("[data-part='pill']").textContent = offline
     ? "server restarting…"
-    : errorCount || warnCount
-      ? `${errorCount} errors · ${warnCount} warnings`
+    : errorCount || warnCount || seoIssues.length
+      ? `${errorCount} errors · ${warnCount} warnings · ${seoIssues.length} SEO`
       : "all good";
 
   const chip = root.querySelector("[data-part='chip']");
   chip.hidden = !errorCount;
   chip.textContent = String(errorCount);
 
+  const seoChip = root.querySelector("[data-part='seo-chip']");
+  seoChip.hidden = !seoIssues.length;
+  seoChip.className = `chip ${seoErrors ? "" : "neutral"}`;
+  seoChip.textContent = String(seoIssues.length);
+
   const version = serverStats?.version;
   paintVersion(root, version);
   const versionChip = root.querySelector("[data-part='version-chip']");
@@ -1798,13 +1951,15 @@ function paint() {
   const html =
     activeTab === "errors"
       ? errorsTab()
-      : activeTab === "perf"
-        ? perfTab()
-        : activeTab === "about"
-          ? aboutTab()
-          : activeTab === "warm"
-            ? warmTab()
-            : serverTab();
+      : activeTab === "seo"
+        ? seoTab()
+        : activeTab === "perf"
+          ? perfTab()
+          : activeTab === "about"
+            ? aboutTab()
+            : activeTab === "warm"
+              ? warmTab()
+              : serverTab();
 
   if (html !== lastBody) {
     const body = root.querySelector(".body");
@@ -1921,6 +2076,45 @@ function bind(root) {
       return;
     }
 
+    if (target.dataset.action === "seo-toggle") {
+      seoHighlight = !seoHighlight;
+      if (!seoHighlight) seoExpandedId = null;
+      refreshSeo();
+      saveState();
+      lastBody = "";
+      render();
+      return;
+    }
+
+    if (target.dataset.action === "seo-rescan") {
+      refreshSeo();
+      lastBody = "";
+      render();
+      return;
+    }
+
+    if (target.dataset.action === "seo-focus") {
+      activeTab = "seo";
+      setOpen(true);
+      return;
+    }
+
+    if (target.dataset.action === "seo-issue") {
+      const id = target.dataset.id;
+      seoExpandedId = seoExpandedId === id ? null : id;
+      if (seoExpandedId) {
+        seoHighlight = true;
+        refreshSeo({ select: seoExpandedId });
+        seoLayer.select(seoExpandedId);
+      } else if (seoHighlight) {
+        seoLayer.select(null);
+      }
+      saveState();
+      lastBody = "";
+      render();
+      return;
+    }
+
     if (target.dataset.action === "copy") {
       copy(target.dataset.key);
       return;
@@ -1936,6 +2130,7 @@ function start() {
   captureMetrics();
   captureFetch();
   bind(ensureRoot());
+  refreshSeo();
   render();
 
   // Panel kapalıyken de rozet güncel kalsın diye kanal her zaman açılır;
@@ -1949,13 +2144,33 @@ function start() {
   });
   window.addEventListener("pagehide", () => sendPageReport(true));
 
+  // Island'lar ve lazy img'ler geç gelebilir; highlight açıksa bir kez daha tara.
+  setTimeout(() => {
+    if (!seoHighlight && activeTab !== "seo") return;
+    refreshSeo();
+    lastBody = "";
+    render();
+  }, 2500);
+
   window.addEventListener("keydown", (event) => {
     if (event.altKey && event.code === "KeyD") {
       setOpen(!open);
       return;
     }
 
-    if (event.key === "Escape" && open) setOpen(false);
+    if (event.key === "Escape") {
+      if (open) {
+        setOpen(false);
+        return;
+      }
+      if (seoExpandedId) {
+        seoExpandedId = null;
+        if (seoHighlight) seoLayer.select(null);
+        saveState();
+        lastBody = "";
+        render();
+      }
+    }
   });
 }
 

package/src/client/devtools/seo.js

@@ -0,0 +1,628 @@
+/**
+ * Dev SEO taraması: sayfanın DOM'unu okur, sorun listesi üretir ve isteğe
+ * bağlı olarak elemanları kırmızı/sarı dikdörtgenlerle işaretler.
+ *
+ * Overlay ile aynı şekilde build'e girmez; `/__jskelet/dev/seo.js` altında
+ * ham servis edilir. Kurallar bilinçli olarak küçük tutulur — Lighthouse
+ * yerine geliştirme sırasında kaçırılan meta/başlık/alt boşluklarını yakalar.
+ */
+
+/**
+ * @typedef {'error' | 'warn'} SeoSeverity
+ *
+ * @typedef {{
+ *   id: string,
+ *   severity: SeoSeverity,
+ *   title: string,
+ *   detail: string,
+ *   category: string,
+ *   element?: Element | null,
+ * }} SeoIssue
+ */
+
+/** @param {string} text */
+export function trimText(text) {
+  return String(text ?? "").replace(/\s+/g, " ").trim();
+}
+
+/**
+ * Başlık uzunluğu. Google genelde ~50–60 karakterde keser.
+ * @param {string} title
+ * @returns {{ severity: SeoSeverity, title: string, detail: string } | null}
+ */
+export function gradeTitleLength(title) {
+  const value = trimText(title);
+  if (!value) {
+    return {
+      severity: "error",
+      title: "Missing document title",
+      detail:
+        "Every page needs a unique <title>. Search results and browser tabs use it; without one the URL is shown instead.",
+    };
+  }
+  if (value.length < 10) {
+    return {
+      severity: "warn",
+      title: "Title is very short",
+      detail: `The title is ${value.length} characters. Aim for roughly 30–60 so the result snippet is informative.`,
+    };
+  }
+  if (value.length > 60) {
+    return {
+      severity: "warn",
+      title: "Title may be truncated",
+      detail: `The title is ${value.length} characters. Search engines often cut around 60; put the distinctive words first.`,
+    };
+  }
+  return null;
+}
+
+/**
+ * @param {string | null | undefined} description
+ * @returns {{ severity: SeoSeverity, title: string, detail: string } | null}
+ */
+export function gradeDescriptionLength(description) {
+  const value = trimText(description ?? "");
+  if (!value) {
+    return {
+      severity: "error",
+      title: "Missing meta description",
+      detail:
+        "Add <meta name=\"description\">. It does not rank directly, but it is the default snippet under the title in search results.",
+    };
+  }
+  if (value.length < 50) {
+    return {
+      severity: "warn",
+      title: "Description is short",
+      detail: `The description is ${value.length} characters. Around 120–160 characters usually fills the snippet without trailing off.`,
+    };
+  }
+  if (value.length > 160) {
+    return {
+      severity: "warn",
+      title: "Description may be truncated",
+      detail: `The description is ${value.length} characters. Keep the important clause in the first ~155 characters.`,
+    };
+  }
+  return null;
+}
+
+/**
+ * @param {string | null} alt
+ * @param {boolean} hasAttr
+ * @returns {{ severity: SeoSeverity, title: string, detail: string } | null}
+ */
+export function gradeImageAlt(alt, hasAttr) {
+  if (!hasAttr) {
+    return {
+      severity: "error",
+      title: "Image missing alt",
+      detail:
+        "Add an alt attribute. Describe the image for screen readers and image search; use alt=\"\" only when the image is purely decorative.",
+    };
+  }
+  const value = trimText(alt ?? "");
+  // Boş alt dekoratif kabul edilir; uzun "image of …" gürültüsü uyarıdır.
+  if (value.length > 125) {
+    return {
+      severity: "warn",
+      title: "Alt text is very long",
+      detail: `Alt is ${value.length} characters. Keep it to a short phrase; the surrounding copy should carry the rest.`,
+    };
+  }
+  return null;
+}
+
+/**
+ * @param {number[]} levels heading seviyeleri sırayla (1–6)
+ * @returns {{ severity: SeoSeverity, title: string, detail: string } | null}
+ */
+export function gradeHeadingSkip(levels) {
+  if (!levels.length) return null;
+  let previous = levels[0];
+  for (let i = 1; i < levels.length; i++) {
+    const level = levels[i];
+    if (level > previous + 1) {
+      return {
+        severity: "warn",
+        title: "Heading level skipped",
+        detail: `Found an h${level} right after an h${previous}. Keep the outline sequential (h1 → h2 → h3) so assistive tech and outline tools can follow the structure.`,
+      };
+    }
+    previous = level;
+  }
+  return null;
+}
+
+/**
+ * @param {Document} doc
+ * @param {string} name
+ * @returns {string | null}
+ */
+function metaContent(doc, name) {
+  const node = doc.querySelector(`meta[name="${name}" i]`);
+  return node?.getAttribute("content") ?? null;
+}
+
+/**
+ * @param {Document} doc
+ * @param {string} property
+ * @returns {string | null}
+ */
+function ogContent(doc, property) {
+  const node = doc.querySelector(`meta[property="${property}" i]`);
+  return node?.getAttribute("content") ?? null;
+}
+
+/**
+ * @param {Element | null | undefined} element
+ * @returns {string}
+ */
+function describeElement(element) {
+  if (!element) return "document";
+  const tag = element.tagName.toLowerCase();
+  const id = element.id ? `#${element.id}` : "";
+  const cls = element.classList?.[0] ? `.${element.classList[0]}` : "";
+  return `<${tag}${id}${cls}>`;
+}
+
+/**
+ * Sayfadaki SEO sorunlarını tarar. `element` referansı highlight katmanı için
+ * tutulur; JSON'a serileştirilmez.
+ *
+ * @param {Document} [doc]
+ * @returns {SeoIssue[]}
+ */
+export function scanSeo(doc = document) {
+  /** @type {SeoIssue[]} */
+  const issues = [];
+  let seq = 0;
+  /** @param {Omit<SeoIssue, 'id'>} issue */
+  const push = (issue) => {
+    issues.push({ ...issue, id: `seo-${++seq}` });
+  };
+
+  const titleEl = doc.querySelector("title");
+  const titleGrade = gradeTitleLength(titleEl?.textContent ?? "");
+  if (titleGrade) {
+    push({ ...titleGrade, category: "document", element: titleEl ?? doc.documentElement });
+  }
+
+  const descEl = doc.querySelector('meta[name="description" i]');
+  const descGrade = gradeDescriptionLength(descEl?.getAttribute("content"));
+  if (descGrade) {
+    push({
+      ...descGrade,
+      category: "document",
+      element: descEl ?? doc.head ?? doc.documentElement,
+    });
+  }
+
+  const html = doc.documentElement;
+  if (!html?.getAttribute("lang")?.trim()) {
+    push({
+      severity: "warn",
+      title: "Missing html lang",
+      detail:
+        "Set <html lang=\"…\"> to the page language. Screen readers and translation tools use it; search engines treat it as a language signal.",
+      category: "document",
+      element: html,
+    });
+  }
+
+  if (!doc.querySelector('meta[name="viewport" i]')) {
+    push({
+      severity: "error",
+      title: "Missing viewport meta",
+      detail:
+        "Mobile Googlebot expects a viewport tag. Without it the page may be treated as non-mobile-friendly.",
+      category: "document",
+      element: doc.head ?? html,
+    });
+  }
+
+  const canonicals = [...doc.querySelectorAll('link[rel="canonical" i]')];
+  if (!canonicals.length) {
+    push({
+      severity: "warn",
+      title: "Missing canonical URL",
+      detail:
+        "Add <link rel=\"canonical\"> so duplicate URLs (tracking params, trailing slash variants) consolidate to one preferred address.",
+      category: "document",
+      element: doc.head ?? html,
+    });
+  } else if (canonicals.length > 1) {
+    push({
+      severity: "error",
+      title: "Multiple canonical links",
+      detail: `Found ${canonicals.length} canonical tags. Only one should appear per page; extras confuse crawlers.`,
+      category: "document",
+      element: canonicals[0],
+    });
+  } else {
+    const href = canonicals[0].getAttribute("href")?.trim() ?? "";
+    if (!href) {
+      push({
+        severity: "error",
+        title: "Empty canonical href",
+        detail: "The canonical link has no href. Point it at the preferred absolute or site-relative URL for this page.",
+        category: "document",
+        element: canonicals[0],
+      });
+    }
+  }
+
+  const robots = trimText(metaContent(doc, "robots") ?? "").toLowerCase();
+  if (/\bnoindex\b/.test(robots)) {
+    push({
+      severity: "warn",
+      title: "Page is marked noindex",
+      detail:
+        "robots contains noindex, so search engines should not list this URL. Confirm that is intentional for this environment/page.",
+      category: "document",
+      element: doc.querySelector('meta[name="robots" i]') ?? doc.head ?? html,
+    });
+  }
+
+  for (const prop of ["og:title", "og:description", "og:image"]) {
+    if (!trimText(ogContent(doc, prop) ?? "")) {
+      push({
+        severity: "warn",
+        title: `Missing ${prop}`,
+        detail: `Open Graph ${prop} is empty. Social previews and some crawlers fall back to weaker signals without it.`,
+        category: "social",
+        element: doc.querySelector(`meta[property="${prop}" i]`) ?? doc.head ?? html,
+      });
+    }
+  }
+
+  if (!trimText(metaContent(doc, "twitter:card") ?? "")) {
+    push({
+      severity: "warn",
+      title: "Missing twitter:card",
+      detail:
+        "Without twitter:card, X/Twitter may pick a poor preview layout. summary or summary_large_image are the usual choices.",
+      category: "social",
+      element: doc.head ?? html,
+    });
+  }
+
+  const headings = [...doc.querySelectorAll("h1, h2, h3, h4, h5, h6")].filter(
+    (node) => !node.closest("#jskelet-devtools, #jskelet-seo-layer"),
+  );
+  const h1s = headings.filter((node) => node.tagName === "H1");
+  if (!h1s.length) {
+    push({
+      severity: "error",
+      title: "Missing H1",
+      detail:
+        "Add a single top-level heading that names the page topic. It anchors the outline and is a strong on-page signal.",
+      category: "structure",
+      element: doc.body ?? html,
+    });
+  } else if (h1s.length > 1) {
+    push({
+      severity: "warn",
+      title: "Multiple H1 headings",
+      detail: `Found ${h1s.length} H1 elements. Prefer one primary H1; demote section titles to H2+.`,
+      category: "structure",
+      element: h1s[1],
+    });
+  }
+
+  const levels = headings.map((node) => Number(node.tagName.slice(1)));
+  const skip = gradeHeadingSkip(levels);
+  if (skip) {
+    const offender = headings.find((node, index) => {
+      if (index === 0) return false;
+      return Number(node.tagName.slice(1)) > levels[index - 1] + 1;
+    });
+    push({ ...skip, category: "structure", element: offender ?? headings[0] });
+  }
+
+  const images = [...doc.querySelectorAll("img")].filter(
+    (node) => !node.closest("#jskelet-devtools, #jskelet-seo-layer"),
+  );
+  for (const img of images) {
+    const grade = gradeImageAlt(img.getAttribute("alt"), img.hasAttribute("alt"));
+    if (!grade) continue;
+    const src = img.getAttribute("src") || img.getAttribute("data-src") || describeElement(img);
+    push({
+      ...grade,
+      title: grade.title,
+      detail: `${grade.detail} (${src})`,
+      category: "media",
+      element: img,
+    });
+  }
+
+  const links = [...doc.querySelectorAll("a[href]")].filter(
+    (node) => !node.closest("#jskelet-devtools, #jskelet-seo-layer"),
+  );
+  for (const link of links) {
+    const href = (link.getAttribute("href") ?? "").trim();
+    if (!href || href === "#") {
+      push({
+        severity: "warn",
+        title: "Empty or placeholder link",
+        detail:
+          "This anchor has href=\"#\" or an empty href. Give it a real destination, or use a button if it only triggers a script.",
+        category: "links",
+        element: link,
+      });
+      continue;
+    }
+
+    const name = trimText(
+      link.getAttribute("aria-label") ||
+        link.getAttribute("title") ||
+        link.textContent ||
+        "",
+    );
+    const hasImgAlt = [...link.querySelectorAll("img")].some((img) =>
+      trimText(img.getAttribute("alt") ?? ""),
+    );
+    if (!name && !hasImgAlt) {
+      push({
+        severity: "warn",
+        title: "Link has no accessible name",
+        detail:
+          "The link has no text, aria-label, title, or image alt. Add a short label so users and crawlers know where it goes.",
+        category: "links",
+        element: link,
+      });
+    }
+  }
+
+  for (const script of doc.querySelectorAll('script[type="application/ld+json"]')) {
+    const raw = script.textContent?.trim() ?? "";
+    if (!raw) {
+      push({
+        severity: "warn",
+        title: "Empty JSON-LD block",
+        detail: "A structured-data script is present but empty. Remove it or fill in valid JSON-LD.",
+        category: "structured",
+        element: script,
+      });
+      continue;
+    }
+    try {
+      JSON.parse(raw);
+    } catch (error) {
+      push({
+        severity: "error",
+        title: "Invalid JSON-LD",
+        detail: `Structured data failed to parse: ${error instanceof Error ? error.message : String(error)}`,
+        category: "structured",
+        element: script,
+      });
+    }
+  }
+
+  const rank = { error: 0, warn: 1 };
+  issues.sort(
+    (a, b) =>
+      rank[a.severity] - rank[b.severity] || a.category.localeCompare(b.category) || a.title.localeCompare(b.title),
+  );
+  return issues;
+}
+
+/* -------------------------------------------------------------- highlight */
+
+const LAYER_CSS = `
+:host { all: initial; }
+* { box-sizing: border-box; font-family: ui-sans-serif, system-ui, -apple-system, sans-serif; }
+.layer { position: fixed; inset: 0; pointer-events: none; z-index: 2147483646; }
+.box {
+  position: fixed; pointer-events: none;
+  border: 2px solid var(--tone);
+  background: color-mix(in srgb, var(--tone) 8%, transparent);
+  border-radius: 4px;
+}
+.box.error { --tone: #fb7185; }
+.box.warn { --tone: #fbbf24; }
+.box.active {
+  background: color-mix(in srgb, var(--tone) 18%, transparent);
+  box-shadow: 0 0 0 1px color-mix(in srgb, var(--tone) 55%, transparent);
+}
+.label {
+  position: fixed; pointer-events: auto; cursor: pointer;
+  max-width: min(280px, 70vw);
+  padding: 3px 8px; border-radius: 4px 4px 0 0;
+  font-size: 11px; font-weight: 700; line-height: 1.3;
+  color: #1a1010; background: var(--tone);
+  white-space: nowrap; overflow: hidden; text-overflow: ellipsis;
+  box-shadow: 0 4px 14px rgba(0,0,0,.28);
+  transform: translateY(-100%);
+}
+.label.warn { color: #2a1d00; }
+.detail {
+  position: fixed; pointer-events: auto; z-index: 1;
+  width: min(340px, calc(100vw - 24px));
+  padding: 12px 14px; border-radius: 10px;
+  background: #10131a; color: #eef1f5; border: 1px solid rgba(255,255,255,.12);
+  box-shadow: 0 18px 40px rgba(0,0,0,.45);
+  font-size: 12.5px; line-height: 1.55;
+}
+.detail .head {
+  display: flex; align-items: center; gap: 8px; margin-bottom: 6px;
+  font-size: 12px; font-weight: 700;
+}
+.detail .sev {
+  font-size: 9.5px; font-weight: 700; letter-spacing: .06em; text-transform: uppercase;
+  border-radius: 999px; padding: 1px 7px;
+}
+.detail .sev.error { background: rgba(251,113,133,.2); color: #fb7185; }
+.detail .sev.warn { background: rgba(251,191,36,.18); color: #fbbf24; }
+.detail .cat { color: #8b95a3; font-size: 10.5px; margin-left: auto; text-transform: uppercase; letter-spacing: .05em; }
+.detail p { margin: 0; color: #c6ced9; }
+.detail .close {
+  position: absolute; top: 8px; right: 8px; border: 0; background: transparent;
+  color: #8b95a3; cursor: pointer; font-size: 14px; line-height: 1; padding: 4px;
+}
+.detail .close:hover { color: #fff; }
+`;
+
+/**
+ * Sayfa üzeri SEO işaretleri. Shadow DOM; sayfa CSS'i karışmaz.
+ */
+export class SeoHighlighter {
+  constructor() {
+    /** @type {SeoIssue[]} */
+    this.issues = [];
+    /** @type {string | null} */
+    this.openId = null;
+    /** @type {((id: string | null) => void) | null} */
+    this.onSelect = null;
+    /** @type {HTMLElement | null} */
+    this.host = null;
+    /** @type {ShadowRoot | null} */
+    this.shadow = null;
+    /** @type {(() => void) | null} */
+    this._onViewport = null;
+  }
+
+  /** @returns {boolean} */
+  get active() {
+    return Boolean(this.host);
+  }
+
+  /**
+   * @param {SeoIssue[]} issues
+   * @param {{ select?: string | null }} [opts]
+   */
+  show(issues, opts = {}) {
+    this.issues = issues.filter((issue) => issue.element);
+    if (opts.select !== undefined) this.openId = opts.select;
+    this.#ensure();
+    this.#paint();
+    this.#bindViewport();
+  }
+
+  hide() {
+    this.#unbindViewport();
+    this.host?.remove();
+    this.host = null;
+    this.shadow = null;
+    this.openId = null;
+  }
+
+  /** @param {string | null} id */
+  select(id) {
+    this.openId = id;
+    const issue = this.issues.find((item) => item.id === id);
+    issue?.element?.scrollIntoView({ block: "center", behavior: "smooth" });
+    this.#paint();
+    this.onSelect?.(id);
+  }
+
+  #ensure() {
+    if (this.host) return;
+    const host = document.createElement("div");
+    host.id = "jskelet-seo-layer";
+    host.setAttribute("data-jskelet", "seo-layer");
+    document.documentElement.append(host);
+    const shadow = host.attachShadow({ mode: "open" });
+    const style = document.createElement("style");
+    style.textContent = LAYER_CSS;
+    const root = document.createElement("div");
+    root.className = "layer";
+    shadow.append(style, root);
+    root.addEventListener("click", (event) => {
+      const target = /** @type {HTMLElement} */ (event.target).closest("[data-seo-id], [data-action]");
+      if (!target) return;
+      event.preventDefault();
+      event.stopPropagation();
+      if (target.dataset.action === "close") {
+        this.openId = null;
+        this.#paint();
+        this.onSelect?.(null);
+        return;
+      }
+      const id = target.dataset.seoId;
+      if (!id) return;
+      this.openId = this.openId === id ? null : id;
+      this.#paint();
+      this.onSelect?.(this.openId);
+    });
+    this.host = host;
+    this.shadow = shadow;
+  }
+
+  #bindViewport() {
+    if (this._onViewport) return;
+    this._onViewport = () => this.#paint();
+    window.addEventListener("scroll", this._onViewport, true);
+    window.addEventListener("resize", this._onViewport);
+  }
+
+  #unbindViewport() {
+    if (!this._onViewport) return;
+    window.removeEventListener("scroll", this._onViewport, true);
+    window.removeEventListener("resize", this._onViewport);
+    this._onViewport = null;
+  }
+
+  #paint() {
+    const root = this.shadow?.querySelector(".layer");
+    if (!root) return;
+
+    const parts = [];
+    for (const issue of this.issues) {
+      const el = issue.element;
+      if (!el || !el.isConnected) continue;
+      const rect = el.getBoundingClientRect();
+      if (rect.width < 1 && rect.height < 1) continue;
+
+      const top = Math.max(0, rect.top);
+      const left = Math.max(0, rect.left);
+      const width = Math.min(rect.width, window.innerWidth - left);
+      const height = Math.min(rect.height, window.innerHeight - top);
+      if (width < 2 || height < 2) continue;
+
+      const active = this.openId === issue.id ? " active" : "";
+      parts.push(`
+        <div class="box ${issue.severity}${active}"
+          style="top:${top}px;left:${left}px;width:${width}px;height:${height}px"></div>
+        <button type="button" class="label ${issue.severity}" data-seo-id="${escapeAttr(issue.id)}"
+          style="top:${top}px;left:${left}px" title="${escapeAttr(issue.title)}">${escapeHtml(issue.title)}</button>
+      `);
+    }
+
+    if (this.openId) {
+      const issue = this.issues.find((item) => item.id === this.openId);
+      const el = issue?.element;
+      if (issue && el?.isConnected) {
+        const rect = el.getBoundingClientRect();
+        const detailTop = Math.min(window.innerHeight - 160, Math.max(8, rect.bottom + 8));
+        const detailLeft = Math.min(window.innerWidth - 360, Math.max(12, rect.left));
+        parts.push(`
+          <div class="detail" style="top:${detailTop}px;left:${detailLeft}px" role="dialog">
+            <button type="button" class="close" data-action="close" aria-label="Close">✕</button>
+            <div class="head">
+              <span class="sev ${issue.severity}">${issue.severity}</span>
+              <span>${escapeHtml(issue.title)}</span>
+              <span class="cat">${escapeHtml(issue.category)}</span>
+            </div>
+            <p>${escapeHtml(issue.detail)}</p>
+          </div>
+        `);
+      }
+    }
+
+    root.innerHTML = parts.join("");
+  }
+}
+
+/** @param {string} value */
+function escapeHtml(value) {
+  return String(value).replace(/[&<>"]/g, (char) =>
+    ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[char],
+  );
+}
+
+/** @param {string} value */
+function escapeAttr(value) {
+  return escapeHtml(value).replace(/'/g, "&#39;");
+}

package/src/server/create-app.js

@@ -148,7 +148,10 @@ export async function createApp(options = {}) {
 
   app.use(async (req, res, next) => {
     try {
-      res.status(404).type("html").send(await renderNotFound());
+      // headersMiddleware `/assets/*` için immutable basmış olabilir; eksik bir
+      // hash'li dosyanın 404'ü CDN'de bir yıl zehirlenmesin.
+      res.status(404).setHeader("Cache-Control", "no-store");
+      res.type("html").send(await renderNotFound());
     } catch (error) {
       next(error);
     }
@@ -168,7 +171,8 @@ export async function createApp(options = {}) {
     }
 
     if (isNotFoundError(error)) {
-      res.status(404).type("html").send(await renderNotFound());
+      res.status(404).setHeader("Cache-Control", "no-store");
+      res.type("html").send(await renderNotFound());
       return;
     }
 

package/src/server/dev/devtools.js

@@ -339,6 +339,13 @@ function router() {
     fs.createReadStream(OVERLAY_FILE).pipe(res);
   });
 
+  // Overlay'in SEO taraması; native ESM import ile yüklenir.
+  api.get("/seo.js", (req, res) => {
+    res.type("application/javascript");
+    res.setHeader("Cache-Control", "no-store");
+    fs.createReadStream(path.join(DEVTOOLS_DIR, "seo.js")).pipe(res);
+  });
+
   api.get("/logo.png", (req, res) => {
     res.type("image/png");
     // Logo geliştirme sırasında değişmiyor; her gezinmede yeniden indirmesin.