jskelet 0.4.6 → 0.4.8

package/src/client/devtools/overlay.js

@@ -17,7 +17,7 @@ const BASE = "/__jskelet/dev";
 const POLL_MS = 2000;
 const MAX_ERRORS = 100;
 
-/** @type {{ id: number, level: string, message: string, stack: string | null, source: string, at: number }[]} */
+/** @type {{ id: number, level: string, message: string, stack: string | null, source: string, page?: string | null, island?: string | null, url?: string | null, details?: unknown, at: number }[]} */
 const clientErrors = [];
 let nextId = 1;
 
@@ -109,7 +109,14 @@ function loadState() {
 /**
  * @param {string} level
  * @param {string} message
- * @param {{ stack?: string | null, source?: string }} [extra]
+ * @param {{
+ *   stack?: string | null,
+ *   source?: string,
+ *   page?: string | null,
+ *   island?: string | null,
+ *   url?: string | null,
+ *   details?: unknown,
+ * }} [extra]
  */
 function pushError(level, message, extra = {}) {
   clientErrors.unshift({
@@ -118,6 +125,10 @@ function pushError(level, message, extra = {}) {
     message,
     stack: extra.stack ?? null,
     source: extra.source ?? "client",
+    page: extra.page ?? location.pathname,
+    island: extra.island ?? null,
+    url: extra.url ?? null,
+    details: extra.details ?? null,
     at: Date.now(),
   });
   if (clientErrors.length > MAX_ERRORS) clientErrors.length = MAX_ERRORS;
@@ -318,6 +329,8 @@ const clientApi = [];
 /**
  * Tarayıcıdaki veri çağrıları. Panelin kendi uçları ve statik varlıklar
  * sayılmaz; amaç sayfanın hangi API'lere kaç ms harcadığını görmek.
+ * 4xx/5xx ve ağ hataları Errors sekmesine de düşer — hangi sayfa / island
+ * bağlamı mümkün olduğunca doldurulur.
  */
 function captureFetch() {
   const original = window.fetch.bind(window);
@@ -326,13 +339,34 @@ function captureFetch() {
     const url = typeof input === "string" ? input : (input?.url ?? String(input));
     if (url.includes(BASE)) return original(input, init);
 
+    const method = String(init?.method ?? "GET").toUpperCase();
     const started = performance.now();
     try {
       const response = await original(input, init);
       record(url, performance.now() - started, response.status, response);
+      if (!response.ok) {
+        void reportFailedFetch({
+          url,
+          method,
+          status: response.status,
+          response,
+        });
+      }
       return response;
     } catch (error) {
       record(url, performance.now() - started, 0, null);
+      pushError(
+        "error",
+        `${method} ${shortUrl(url)} → network error`,
+        {
+          source: "fetch",
+          url,
+          page: location.pathname + location.search,
+          island: inferIsland(),
+          stack: error instanceof Error ? error.stack : null,
+          details: error instanceof Error ? error.message : String(error),
+        },
+      );
       throw error;
     }
   };
@@ -355,6 +389,99 @@ function captureFetch() {
   }
 }
 
+/**
+ * Başarısız bir tarayıcı fetch'ini Errors listesine yazar. Gövdeyi klonlayıp
+ * okur; asıl Response tüketilmez.
+ *
+ * @param {{ url: string, method: string, status: number, response: Response }} call
+ */
+async function reportFailedFetch(call) {
+  const details = await readResponseDetails(call.response);
+  const summary = detailSummary(details);
+  pushError(
+    "error",
+    `${call.method} ${shortUrl(call.url)} → ${call.status}${
+      summary ? `: ${summary}` : ""
+    }`,
+    {
+      source: "fetch",
+      url: call.url,
+      page: location.pathname + location.search,
+      island: inferIsland(),
+      details,
+    },
+  );
+}
+
+/**
+ * @param {Response} response
+ * @returns {Promise<unknown>}
+ */
+async function readResponseDetails(response) {
+  try {
+    const text = (await response.clone().text()).slice(0, 4000);
+    if (!text) return null;
+    try {
+      return JSON.parse(text);
+    } catch {
+      return text;
+    }
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {unknown} details
+ * @returns {string | null}
+ */
+function detailSummary(details) {
+  if (details == null) return null;
+  if (typeof details === "string") return details.slice(0, 200);
+  if (typeof details !== "object") return String(details);
+  const record = /** @type {Record<string, unknown>} */ (details);
+  for (const key of ["details", "detail", "message", "error", "title"]) {
+    const value = record[key];
+    if (typeof value === "string" && value.trim()) return value.slice(0, 200);
+    if (value && typeof value === "object") {
+      const nested = detailSummary(value);
+      if (nested) return nested;
+    }
+  }
+  try {
+    return JSON.stringify(details).slice(0, 200);
+  } catch {
+    return null;
+  }
+}
+
+/** @param {string} url */
+function shortUrl(url) {
+  try {
+    const parsed = new URL(url, location.origin);
+    return parsed.origin === location.origin
+      ? parsed.pathname + parsed.search
+      : parsed.host + parsed.pathname + parsed.search;
+  } catch {
+    return url;
+  }
+}
+
+/**
+ * Çağrı yığınında `islands/ad` izi varsa ya da bir island mount edilirken
+ * yakalanmışsa ada bağlar.
+ *
+ * @returns {string | null}
+ */
+function inferIsland() {
+  const mounting = globalThis.__JSKELET_MOUNTING_ISLAND;
+  if (typeof mounting === "string" && mounting) return mounting;
+
+  const stack = new Error().stack ?? "";
+  const match = stack.match(/islands[/\\]([A-Za-z0-9_-]+)/);
+  return match?.[1] ?? null;
+}
+
 /**
  * Sayfa ölçümlerini rapora gönderir. Sekme kapanırken de gitmesi gerektiği
  * için mümkünse `sendBeacon` kullanılır.
@@ -847,7 +974,11 @@ h4:first-child { margin-top: 0; }
 .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; }
+.item .ctx-row { flex-wrap: wrap; gap: 6px; margin-bottom: 6px; }
+.item .ctx { font-family: ui-monospace, SFMono-Regular, monospace; font-size: 10.5px; color: #cfd6de; }
+.item .ctx.muted { color: var(--muted); max-width: 100%; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
 .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; }
+.tag.island { text-transform: none; letter-spacing: 0; color: #c4b5fd; border-color: rgba(196,181,253,.35); }
 .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; }
@@ -1101,29 +1232,80 @@ const clipboard = new Map();
 let copiedKey = null;
 
 /**
- * @param {{ level: string, message: string, stack?: string | null, source?: string, at: number }} item
+ * @param {{
+ *   level: string,
+ *   message: string,
+ *   stack?: string | null,
+ *   source?: string,
+ *   page?: string | null,
+ *   island?: string | null,
+ *   url?: string | null,
+ *   details?: unknown,
+ *   at: number,
+ * }} item
  * @returns {string}
  */
 function asText(item) {
   const time = new Date(item.at).toISOString();
+  const details =
+    item.details == null
+      ? ""
+      : typeof item.details === "string"
+        ? item.details
+        : safeJson(item.details);
   return [
     `[${item.level}] ${item.source ?? "server"} · ${time}`,
+    item.page ? `page: ${item.page}` : "",
+    item.island ? `island: ${item.island}` : "",
+    item.url ? `url: ${item.url}` : "",
     item.message,
+    details,
     item.stack ?? "",
   ]
     .filter(Boolean)
     .join("\n");
 }
 
-/** @param {{ id?: number, level: string, message: string, stack?: string | null, source?: string, at: number }[]} list */
+/**
+ * @param {unknown} value
+ * @returns {string}
+ */
+function formatDetails(value) {
+  if (value == null) return "";
+  if (typeof value === "string") return value;
+  try {
+    return JSON.stringify(value, null, 2);
+  } catch {
+    return safeJson(value);
+  }
+}
+
+/** @param {{ id?: number, level: string, message: string, stack?: string | null, source?: string, page?: string | null, island?: string | null, url?: string | null, details?: unknown, at: number }[]} list */
 function errorList(list, scope) {
   if (!list.length) return `<div class="empty">No records.</div>`;
   return list
     .map((item) => {
       const key = `${scope}:${item.id ?? item.at}`;
       const shown = expanded.has(key);
+      const detailsKey = `${key}:details`;
+      const detailsShown = expanded.has(detailsKey);
+      const detailsText = formatDetails(item.details);
       clipboard.set(key, asText(item));
 
+      const context = [
+        item.page
+          ? `<span class="ctx" title="Page">${pathLink(item.page)}</span>`
+          : "",
+        item.island
+          ? `<span class="tag island" title="Island">${escapeHtml(item.island)}</span>`
+          : "",
+        item.url && item.url !== item.page
+          ? `<span class="ctx muted" title="Request">${escapeHtml(shortUrl(item.url))}</span>`
+          : "",
+      ]
+        .filter(Boolean)
+        .join("");
+
       return `<div class="item ${item.level === "warn" ? "warn" : ""}">
         <div class="meta">
           <span class="tag">${escapeHtml(item.source ?? "server")}</span>
@@ -1131,7 +1313,14 @@ function errorList(list, scope) {
           <span class="spacer"></span>
           ${copyButton(key)}
         </div>
+        ${context ? `<div class="meta ctx-row">${context}</div>` : ""}
         <div class="msg">${escapeHtml(item.message)}</div>
+        ${
+          detailsText
+            ? `<button class="link" data-action="stack" data-key="${escapeHtml(detailsKey)}">${detailsShown ? "▾ hide details" : "▸ show details"}</button>
+               ${detailsShown ? `<pre>${escapeHtml(detailsText)}</pre>` : ""}`
+            : ""
+        }
         ${
           item.stack
             ? `<button class="link" data-action="stack" data-key="${escapeHtml(key)}">${shown ? "▾ hide stack" : "▸ show stack"}</button>
@@ -1187,7 +1376,7 @@ function errorsTab() {
     ${lede(
       errorCount ? "bad" : total ? "mid" : "good",
       errorCount
-        ? `<strong>${errorCount} errors</strong> captured${total - errorCount ? `, plus ${total - errorCount} warnings` : ""}. Newest first; expand the stack trace and copy a record with one click.`
+        ? `<strong>${errorCount} errors</strong> captured${total - errorCount ? `, plus ${total - errorCount} warnings` : ""}. Newest first; expand details or the stack, and copy a record with one click. Failed fetch calls include the page and API path.`
         : total
           ? `No errors, <strong>${total} warnings</strong>. Warnings usually come from missing data or islands that were never ported.`
           : "No browser or server side errors were seen in this session.",

package/src/client/devtools/report.js

@@ -556,6 +556,7 @@ function apiTab() {
       "api-calls",
       [
         { key: "url", label: "URL" },
+        { key: "page", label: "Page", render: (row) => (row.page ? link(row.page) : "—") },
         { key: "method", label: "Method" },
         { key: "status", label: "Status", render: (row) => `<span class="status ${row.error ? "bad" : ""}">${row.status || "—"}</span>` },
         { key: "ms", label: "Time", value: (row) => row.ms, render: (row) => `<span class="${tone(row.ms, [200, 800])}">${ms(row.ms)}</span>` },
@@ -589,6 +590,25 @@ function errorsTab() {
       "errors",
       [
         { key: "message", label: "Message" },
+        { key: "page", label: "Page", render: (row) => (row.page ? link(row.page) : "—") },
+        {
+          key: "details",
+          label: "Details",
+          render: (row) => {
+            if (row.details == null) return "—";
+            const text =
+              typeof row.details === "string"
+                ? row.details
+                : (() => {
+                    try {
+                      return JSON.stringify(row.details);
+                    } catch {
+                      return String(row.details);
+                    }
+                  })();
+            return `<span class="hint" title="${escapeHtml(text)}">${escapeHtml(text.slice(0, 120))}${text.length > 120 ? "…" : ""}</span>`;
+          },
+        },
         { key: "level", label: "Level", render: (row) => `<span class="tag">${escapeHtml(row.level)}</span>` },
         { key: "at", label: "Time", value: (row) => row.at, render: (row) => new Date(row.at).toLocaleTimeString() },
       ],

package/src/client/registry.js

@@ -110,6 +110,12 @@ async function mountIsland(element) {
 
   markMounted(element);
 
+  // Dev overlay başarısız fetch'i hangi island'dan geldiğine bağlayabilsin.
+  // Mount bittikten sonra (event handler'lar) bu işaret kalkar; o durumda
+  // yığın izine düşülür.
+  const previous = globalThis.__JSKELET_MOUNTING_ISLAND;
+  globalThis.__JSKELET_MOUNTING_ISLAND = name;
+
   try {
     const module = await loader();
     const cleanup = module.mount(element, readProps(element));
@@ -130,6 +136,8 @@ async function mountIsland(element) {
     element.dataset.islandReady = "true";
   } catch (error) {
     console.error(`[island] ${name} failed to load`, error);
+  } finally {
+    globalThis.__JSKELET_MOUNTING_ISLAND = previous;
   }
 }
 

package/src/config/defaults.js

@@ -50,7 +50,11 @@ export const DEFAULT_DEV_GATE_BYPASS = [
   "/favicon.ico",
 ];
 
-/** Prewarm ayarlarının kod içi varsayılanları. */
+/**
+ * Klasik (liste tabanlı) prewarm ayarları. `onVisit` modu bunlarla birlikte
+ * kullanılamaz — ya açılış/`prewarmPaths` turu, ya ziyaret edilen sayfadaki
+ * linkleri ısıtma.
+ */
 export const DEFAULT_PREWARM = {
   enabled: true,
   max: 400,
@@ -85,6 +89,41 @@ export const DEFAULT_PREWARM = {
   priority: [],
 };
 
+/**
+ * Ziyaret tabanlı ısıtma. Bir sayfa servis edilince HTML'deki aynı-origin
+ * linkler kuyruğa alınır; bir sonraki tıklama (veya başka ziyaretçi) çoğu
+ * zaman HIT görür. Klasik `prewarm` alanlarıyla karşılıklı dışlayıcıdır.
+ */
+export const DEFAULT_PREWARM_ON_VISIT = {
+  enabled: false,
+  /** Sayfa başına üstten alta en fazla kaç link kuyruğa alınır. */
+  perPage: 20,
+  /**
+   * Paralel işçi; `null` → klasik prewarm ile aynı varsayılan
+   * (prod 4 / dev 1) `startPrewarm` içinde çözülür.
+   * @type {number | null}
+   */
+  concurrency: null,
+  /**
+   * Saniyedeki istek tavanı; `null` → klasik ile aynı (prod 0 / dev 4).
+   * @type {number | null}
+   */
+  rps: null,
+};
+
+/** `onVisit` açıkken `cache().prewarm` kökünde yasak olan klasik alanlar. */
+export const CLASSIC_PREWARM_KEYS = [
+  "enabled",
+  "max",
+  "intervalSeconds",
+  "concurrency",
+  "delayMs",
+  "rps",
+  "retryDelayMs",
+  "rotate",
+  "priority",
+];
+
 /**
  * HTML önbelleğinin girdi sınırı. 500 girdi ortalama bir sayfa boyutunda
  * yaklaşık 100-200 MB tutar; uzun kuyruklu siteler bunu yükseltmek yerine

package/src/config/index.js

@@ -42,7 +42,9 @@ import {
   DEFAULT_NAVIGATION,
   DEFAULT_NAVIGATION_EXCLUDE,
   DEFAULT_PREWARM,
+  DEFAULT_PREWARM_ON_VISIT,
   DEFAULT_PREWARM_SKIP,
+  CLASSIC_PREWARM_KEYS,
   DEFAULT_REDIS,
   DEFAULT_SECURITY,
   DEFAULT_STATIC,
@@ -655,7 +657,7 @@ function normalizeCache(raw) {
     html.push({ pattern, seconds: value });
   }
 
-  const prewarm = { ...DEFAULT_PREWARM, ...(raw?.prewarm ?? {}) };
+  const prewarm = normalizePrewarm(raw?.prewarm);
   const queryRules = normalizeQueryRules(raw?.query);
   const maxEntries = Number(raw?.maxEntries);
 
@@ -688,6 +690,98 @@ function normalizeCache(raw) {
   };
 }
 
+/**
+ * @param {unknown} raw
+ * @returns {{ enabled: boolean } & typeof DEFAULT_PREWARM_ON_VISIT}
+ */
+function normalizeOnVisit(raw) {
+  if (raw === true) {
+    return { ...DEFAULT_PREWARM_ON_VISIT, enabled: true };
+  }
+
+  if (raw == null || raw === false) {
+    return { ...DEFAULT_PREWARM_ON_VISIT, enabled: false };
+  }
+
+  if (typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error(
+      "[config] cache().prewarm.onVisit must be true, false, or an object",
+    );
+  }
+
+  const source = /** @type {Record<string, unknown>} */ (raw);
+  const perPage = Number(source.perPage);
+  const concurrency = Number(source.concurrency);
+  const rps = Number(source.rps);
+
+  return {
+    ...DEFAULT_PREWARM_ON_VISIT,
+    enabled: source.enabled !== false,
+    perPage:
+      Number.isFinite(perPage) && perPage > 0
+        ? Math.floor(perPage)
+        : DEFAULT_PREWARM_ON_VISIT.perPage,
+    concurrency:
+      Number.isFinite(concurrency) && concurrency > 0
+        ? Math.floor(concurrency)
+        : null,
+    rps: Number.isFinite(rps) && rps >= 0 ? rps : null,
+  };
+}
+
+/**
+ * Klasik liste ısıtması ile `onVisit` karşılıklı dışlayıcıdır. İkisini birden
+ * yazmak sessizce yanlış moda düşmesin diye yüklemede hata verir.
+ *
+ * @param {unknown} raw
+ * @returns {Record<string, unknown>}
+ */
+function normalizePrewarm(raw) {
+  const source =
+    raw && typeof raw === "object" && !Array.isArray(raw)
+      ? /** @type {Record<string, unknown>} */ ({ ...raw })
+      : {};
+
+  const onVisit = normalizeOnVisit(source.onVisit);
+
+  if (onVisit.enabled) {
+    const conflicts = Object.keys(source).filter(
+      (key) => key !== "onVisit" && CLASSIC_PREWARM_KEYS.includes(key),
+    );
+    if (conflicts.length) {
+      throw new Error(
+        "[config] cache().prewarm.onVisit cannot be combined with classic " +
+          `prewarm settings (${conflicts.join(", ")}). Use either onVisit or ` +
+          "classic settings (max, priority, rotate, …), not both.",
+      );
+    }
+
+    const unknown = Object.keys(source).filter((key) => key !== "onVisit");
+    if (unknown.length) {
+      throw new Error(
+        "[config] cache().prewarm.onVisit cannot be combined with " +
+          `${unknown.join(", ")}. On-visit mode only accepts the onVisit object.`,
+      );
+    }
+
+    return {
+      ...DEFAULT_PREWARM,
+      enabled: true,
+      onVisit,
+    };
+  }
+
+  // Klasik mod: `onVisit: false` yazılmış olabilir; diğer alanlar varsayılanlarla
+  // birleşir. `onVisit` anahtarı çözülmüş nesnede her zaman durur.
+  const classic = { ...source };
+  delete classic.onVisit;
+  return {
+    ...DEFAULT_PREWARM,
+    ...classic,
+    onVisit,
+  };
+}
+
 /** Speculation Rules'un tanıdığı eagerness değerleri. */
 const EAGERNESS = new Set(["conservative", "moderate", "eager"]);
 
@@ -1043,6 +1137,17 @@ export async function loadConfig(options = {}) {
     clientEnv: source.clientEnv ?? [],
   };
 
+  if (
+    config.prewarm?.onVisit?.enabled &&
+    typeof config.hooks?.prewarmPaths === "function"
+  ) {
+    throw new Error(
+      "[config] hooks.prewarmPaths() cannot be used with cache().prewarm.onVisit. " +
+        "On-visit mode warms links from each response; classic mode uses prewarmPaths. " +
+        "Choose one.",
+    );
+  }
+
   // Dev'de build ve sunucu ayrı alt süreçler; üçü de aynı özeti basınca satır
   // banner'ın ve build bloğunun arasına üç kez giriyor. Özeti dış süreç basar.
   if (loaded && !process.env.JSKELET_CHILD) {

package/src/http/request-context.js

@@ -25,13 +25,15 @@ import { AsyncLocalStorage } from "node:async_hooks";
  * @property {string[]} taintReasons Hangi erişimler işaretledi (teşhis için).
  * @property {string | null} csrfToken
  * @property {import('express').Response | null} res
+ * @property {string | null} pathname Devtools: bu isteğin sayfa yolu (SSR
+ *   sırasında upstream hatasına "hangi sayfa" bağlamak için).
  */
 
 /** @type {AsyncLocalStorage<RequestContext>} */
 const storage = new AsyncLocalStorage();
 
 /**
- * @param {{ private?: boolean, res?: import('express').Response }} [initial]
+ * @param {{ private?: boolean, res?: import('express').Response, pathname?: string | null }} [initial]
  * @returns {RequestContext}
  */
 export function createRequestContext(initial = {}) {
@@ -41,6 +43,7 @@ export function createRequestContext(initial = {}) {
     taintReasons: [],
     csrfToken: null,
     res: initial.res ?? null,
+    pathname: initial.pathname ?? null,
   };
 }
 

package/src/index.js

@@ -77,7 +77,7 @@ export {
 } from "./server/cloudflare.js";
 // Upstream hız freninin host başına durumu: healthcheck ve teşhis uçları için.
 export { getUpstreamLimiterStatus } from "./server/upstream-limiter.js";
-export { prewarm, prewarmProgress } from "./server/prewarm.js";
+export { prewarm, prewarmProgress, extractSameOriginLinks, isOnVisitPrewarm } from "./server/prewarm.js";
 export { createProxy } from "./server/middleware/upstream-proxy.js";
 export { getConfig, loadConfig } from "./config/index.js";
 export { attrs, cn, cx, esc, jsonScript } from "./views/helpers/html.js";