@ywal123456/jskim 0.3.1 → 0.4.0

package/README.md

@@ -14,14 +14,16 @@ Nunjucks を使った汎用の静的 HTML ビルド環境です。
 - ファイル監視（`watch`）後の全体再ビルド
 - ビルド結果のローカル静的サーバー（`serve`）
 - 開発サーバー（`dev` = build + watch + serve）
-- 成功した再ビルド後のページ全体ライブリロード（SSE）
+- 成功した再ビルド後のライブリロード（SSE）
+- 再ビルド失敗時の browser error overlay（`dev` + `liveReload`）
+- 安全な CSS 変更時の stylesheet soft reload（`dev` + `liveReload`）
 - CLI binary `jskim`
 - プロジェクト生成 CLI `create-jskim`
 
 ## 現在の非対応範囲
 
 - ブラウザ自動起動
-- HMR / CSS だけのホット更新
+- HMR / JavaScript module hot replacement
 - JSON / YAML などの外部データファイル自動読み込み
 - API / Mock API
 - 増分ビルド
@@ -234,9 +236,14 @@ http://127.0.0.1:3000/
 - `serve` は自動で build / watch を実行しません
 - サーバールートは `outputDir`（例: `dist/sample`）
 - `serve` は HTML を変換せず、ライブリロード script を注入しません
-- `dev` は成功した再ビルドのあとだけ SSE でページ全体 reload を送ります
-- `dev` でも `dist` ファイルへ script は書き込みません
+- `watch` にも browser overlay / CSS soft reload はありません
+- `dev` は `dev.liveReload: true` のときだけ browser 向け機能を有効にします
+- 再ビルド失敗時は terminal 診断に加え、browser error overlay を表示します（成功するまで full reload / CSS reload は送りません）
+- CSS ファイルだけが安全に変更された再ビルドでは、ページ全体ではなく stylesheet を更新します
+- CSS 以外の変更や判定が不確実な場合は、従来どおりページ全体 reload します
+- `dev` でも `dist` ファイルへ runtime は書き込みません
 - ブラウザ自動起動はサポートしません
+- 厳格な Content Security Policy で inline script または inline style が禁止されている場合、dev の live reload・error overlay・CSS soft reload が動作しないことがあります
 
 `/_jskim/live-reload` は `dev.liveReload: true` のときだけ使う内部予約パスです。実際の静的ファイルパスとしては使わないことを推奨します。
 

package/docs/configuration.md

@@ -309,16 +309,21 @@ files mode では出力パスの衝突を検出します。たとえば同じ `f
 
 - `GET /_jskim/live-reload` で SSE を提供
 - HTML レスポンスにだけ client script を一時注入（`dist` には書き込まない）
-- 成功した再ビルドのあとだけ `reload` event を送信
+- 成功した再ビルドのあとだけ browser 更新を送信（通常はページ全体 reload）
+- 再ビルド失敗時は browser error overlay を表示（成功するまで reload / CSS 更新は送らない）
+- CSS ファイルだけが安全に変更された場合は、ページ全体ではなく stylesheet を更新
 
 `false` のとき:
 
 - SSE endpoint は提供しない（404）
 - HTML への script 注入なし
+- error overlay / CSS soft reload も無効
 - build + watch + serve 自体は動作
 
 `/_jskim/live-reload` は内部予約パスです。プロジェクトの静的ファイルとしては使わないことを推奨します。
 
+厳格な Content Security Policy で inline script または inline style が禁止されている場合、dev の live reload・error overlay・CSS soft reload が動作しないことがあります。`watch` と `serve` にはこれらの browser 機能はありません。
+
 ## config hot reload
 
 `watch` と `dev` はワークスペースルートの `jskim.config.js` を監視します。

package/docs/create-jskim.md

@@ -54,12 +54,12 @@ project/
 
 `jskim.config.js` は `files: [{ from: 'pages', to: '' }]` を使います。`.njk` は末尾の `.njk` だけを外してレンダリングし、画像などはそのままコピーします。
 
-`package.json` の scripts は bin 名 `jskim` を使います（package name ではありません）。既定の engine dependency は `@ywal123456/jskim`（`^0.3.0`）です。
+`package.json` の scripts は bin 名 `jskim` を使います（package name ではありません）。既定の engine dependency は `@ywal123456/jskim`（`^0.4.0`）です。
 
 ```json
 {
   "devDependencies": {
-    "@ywal123456/jskim": "^0.3.0"
+    "@ywal123456/jskim": "^0.4.0"
   },
   "scripts": {
     "build": "jskim build sample",
@@ -85,7 +85,7 @@ create package の `package.json` に `jskimEngine` metadata を持ち、生成
 {
   "jskimEngine": {
     "packageName": "@ywal123456/jskim",
-    "version": "^0.3.0"
+    "version": "^0.4.0"
   }
 }
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ywal123456/jskim",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Nunjucks-based static HTML build environment with watch, serve, and live reload",
   "keywords": [
     "nunjucks",

package/scripts/lib/classify-reload.js

@@ -0,0 +1,131 @@
+'use strict';
+
+const path = require('node:path');
+const fs = require('node:fs');
+
+/**
+ * rebuild 単位の watcher events から browser 更新方法を分類します。
+ * 不確実な場合は必ず full reload にします。
+ *
+ * @param {object} options
+ * @param {Array<{ event?: string, absolutePath?: string, file?: string }>} options.events
+ * @param {string} options.sourceDir
+ * @param {string[]} [options.templates]
+ * @returns {'css'|'reload'}
+ */
+function classifyReload(options) {
+  const events = Array.isArray(options.events) ? options.events : [];
+  if (events.length === 0) {
+    return 'reload';
+  }
+
+  const templateRoots = resolveTemplateRoots(
+    options.sourceDir,
+    options.templates
+  );
+
+  for (const item of events) {
+    if (!item || typeof item !== 'object') {
+      return 'reload';
+    }
+
+    const eventName = item.event;
+    if (eventName !== 'change') {
+      return 'reload';
+    }
+
+    const absolutePath = resolveEventAbsolutePath(item);
+    if (!absolutePath) {
+      return 'reload';
+    }
+
+    if (isInsideAny(templateRoots, absolutePath)) {
+      return 'reload';
+    }
+
+    if (!isCssSourcePath(absolutePath)) {
+      return 'reload';
+    }
+  }
+
+  return 'css';
+}
+
+/**
+ * @param {{ absolutePath?: string, file?: string }} item
+ * @returns {string|null}
+ */
+function resolveEventAbsolutePath(item) {
+  if (item.absolutePath && typeof item.absolutePath === 'string') {
+    const abs = path.resolve(item.absolutePath);
+    if (path.isAbsolute(abs)) {
+      return abs;
+    }
+  }
+  return null;
+}
+
+/**
+ * 末尾が .css または .css.njk のときだけ true（大文字小文字は無視）。
+ * @param {string} absolutePath
+ * @returns {boolean}
+ */
+function isCssSourcePath(absolutePath) {
+  const normalized = absolutePath.split(path.sep).join('/').toLowerCase();
+  return normalized.endsWith('.css.njk') || normalized.endsWith('.css');
+}
+
+function resolveTemplateRoots(sourceDir, templates) {
+  const roots = [];
+  if (!sourceDir) {
+    return roots;
+  }
+  for (const rel of Array.isArray(templates) ? templates : []) {
+    if (!rel) {
+      continue;
+    }
+    const abs = path.resolve(sourceDir, rel);
+    try {
+      if (fs.existsSync(abs) && fs.statSync(abs).isDirectory()) {
+        roots.push(abs);
+      }
+    } catch {
+      // 存在確認失敗は root として扱わない
+    }
+  }
+  return roots;
+}
+
+function isInsideAny(roots, candidate) {
+  for (const root of roots) {
+    if (isInsideOrSame(root, candidate)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function isInsideOrSame(parent, child) {
+  const p = path.resolve(parent);
+  const c = path.resolve(child);
+  if (samePath(p, c)) {
+    return true;
+  }
+  const rel = path.relative(p, c);
+  return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
+}
+
+function samePath(a, b) {
+  const na = path.resolve(a);
+  const nb = path.resolve(b);
+  if (process.platform === 'win32') {
+    return na.toLowerCase() === nb.toLowerCase();
+  }
+  return na === nb;
+}
+
+module.exports = {
+  classifyReload,
+  isCssSourcePath,
+  resolveTemplateRoots,
+};

package/scripts/lib/create-live-reload.js

@@ -1,7 +1,14 @@
 'use strict';
 
+const {
+  isSameOriginStylesheetHref,
+  appendCacheBustParam,
+} = require('./stylesheet-reload');
+
 const LIVE_RELOAD_PATH = '/_jskim/live-reload';
 const HEARTBEAT_MS = 20000;
+const CSS_LOAD_TIMEOUT_MS = 8000;
+const OVERLAY_HOST_ID = '__jskim_error_overlay__';
 
 /**
  * SSE ベースのライブリロード管理です。
@@ -15,6 +22,10 @@ function createLiveReload({ projectName, enabled = true }) {
   const clients = new Set();
   let heartbeatTimer = null;
   let closed = false;
+  /** @type {string|null} */
+  let configError = null;
+  /** @type {string|null} */
+  let buildError = null;
 
   function ensureHeartbeat() {
     if (!enabled || heartbeatTimer || closed) {
@@ -46,6 +57,32 @@ function createLiveReload({ projectName, enabled = true }) {
     }
   }
 
+  function writeEvent(res, eventName, data) {
+    const payload = `event: ${eventName}\ndata: ${JSON.stringify(data)}\n\n`;
+    res.write(payload);
+  }
+
+  function broadcast(eventName, data) {
+    if (!enabled || closed) {
+      return;
+    }
+    for (const res of [...clients]) {
+      try {
+        writeEvent(res, eventName, data);
+      } catch {
+        removeClient(res);
+      }
+    }
+  }
+
+  function getActiveErrorMessage() {
+    return configError || buildError;
+  }
+
+  function hasConfigError() {
+    return Boolean(configError);
+  }
+
   /**
    * 内部 SSE リクエストを処理します。
    * @returns {boolean} 処理したら true
@@ -80,7 +117,6 @@ function createLiveReload({ projectName, enabled = true }) {
     res.setHeader('Content-Type', 'text/event-stream; charset=utf-8');
     res.setHeader('Cache-Control', 'no-store');
     res.setHeader('Connection', 'keep-alive');
-    // nginx 等のバッファリング回避（ローカルでも無害）
     res.setHeader('X-Accel-Buffering', 'no');
 
     if (method === 'HEAD') {
@@ -92,6 +128,18 @@ function createLiveReload({ projectName, enabled = true }) {
     clients.add(res);
     ensureHeartbeat();
 
+    const active = getActiveErrorMessage();
+    if (active) {
+      try {
+        writeEvent(res, 'error', {
+          project: projectName,
+          message: active,
+        });
+      } catch {
+        removeClient(res);
+      }
+    }
+
     const onClose = () => {
       removeClient(res);
     };
@@ -103,30 +151,13 @@ function createLiveReload({ projectName, enabled = true }) {
   }
 
   function getClientScript() {
-    return [
-      '<script>',
-      '(function () {',
-      '  try {',
-      `    var source = new EventSource(${JSON.stringify(LIVE_RELOAD_PATH)});`,
-      "    source.addEventListener('reload', function () {",
-      '      window.location.reload();',
-      '    });',
-      '    source.onerror = function () {',
-      "      console.info('[JSKim] ライブリロード接続を再試行しています…');",
-      '    };',
-      '  } catch (err) {',
-      "    console.warn('[JSKim] ライブリロードを開始できませんでした。');",
-      '  }',
-      '})();',
-      '</script>',
-    ].join('');
+    return buildClientScript({
+      liveReloadPath: LIVE_RELOAD_PATH,
+      overlayHostId: OVERLAY_HOST_ID,
+      cssLoadTimeoutMs: CSS_LOAD_TIMEOUT_MS,
+    });
   }
 
-  /**
-   * HTML 文字列に client script を注入します（メモリ上のみ）。
-   * @param {string} html
-   * @returns {string}
-   */
   function injectHtml(html) {
     if (!enabled || typeof html !== 'string') {
       return html;
@@ -146,22 +177,113 @@ function createLiveReload({ projectName, enabled = true }) {
     return html + script;
   }
 
-  function broadcastReload() {
+  function broadcastConfigError(message) {
+    if (!enabled || closed) {
+      return;
+    }
+    configError = normalizeErrorMessage(message);
+    broadcast('error', {
+      project: projectName,
+      message: configError,
+    });
+  }
+
+  function broadcastBuildError(message) {
+    if (!enabled || closed) {
+      return;
+    }
+    buildError = normalizeErrorMessage(message);
+    // 未解決の config error がある間は config を優先表示する
+    if (!configError) {
+      broadcast('error', {
+        project: projectName,
+        message: buildError,
+      });
+    }
+  }
+
+  /**
+   * 後方互換: source を指定して error を送る。
+   * @param {unknown} message
+   * @param {'build'|'config'} [source='build']
+   */
+  function broadcastError(message, source = 'build') {
+    if (source === 'config') {
+      broadcastConfigError(message);
+      return;
+    }
+    broadcastBuildError(message);
+  }
+
+  function clearConfigError() {
+    configError = null;
+  }
+
+  function clearBuildError() {
+    buildError = null;
+  }
+
+  function clearErrorState() {
+    configError = null;
+    buildError = null;
+  }
+
+  function broadcastClearError() {
     if (!enabled || closed) {
       return;
     }
+    clearErrorState();
+    broadcast('clear-error', {
+      project: projectName,
+    });
+  }
 
-    const payload = `event: reload\ndata: ${JSON.stringify({
+  function broadcastCssReload() {
+    if (!enabled || closed) {
+      return false;
+    }
+    // 未解決の config エラー中は source 成功で overlay を消さない
+    if (configError) {
+      return false;
+    }
+    clearBuildError();
+    broadcast('clear-error', {
+      project: projectName,
+    });
+    broadcast('css', {
       project: projectName,
-    })}\n\n`;
+    });
+    return true;
+  }
 
-    for (const res of [...clients]) {
-      try {
-        res.write(payload);
-      } catch {
-        removeClient(res);
-      }
+  function broadcastReload() {
+    if (!enabled || closed) {
+      return false;
+    }
+    // reconnect で stale error が復帰しないよう、reload 前に server 状態を消す
+    clearErrorState();
+    broadcast('reload', {
+      project: projectName,
+    });
+    return true;
+  }
+
+  /**
+   * source rebuild 成功時専用。config error が残っていれば何もしない。
+   * @param {'css'|'reload'} kind
+   * @returns {boolean}
+   */
+  function notifySourceBuildSuccess(kind) {
+    if (!enabled || closed) {
+      return false;
     }
+    if (configError) {
+      return false;
+    }
+    if (kind === 'css') {
+      return broadcastCssReload();
+    }
+    return broadcastReload();
   }
 
   function close() {
@@ -169,6 +291,7 @@ function createLiveReload({ projectName, enabled = true }) {
       return;
     }
     closed = true;
+    clearErrorState();
 
     if (heartbeatTimer) {
       clearInterval(heartbeatTimer);
@@ -187,15 +310,282 @@ function createLiveReload({ projectName, enabled = true }) {
     handleRequest,
     injectHtml,
     broadcastReload,
+    broadcastError,
+    broadcastConfigError,
+    broadcastBuildError,
+    broadcastClearError,
+    broadcastCssReload,
+    notifySourceBuildSuccess,
+    clearConfigError,
+    clearBuildError,
+    clearErrorState,
+    hasConfigError,
     getClientScript,
     close,
     get clientCount() {
       return clients.size;
     },
+    get lastErrorMessage() {
+      return getActiveErrorMessage();
+    },
+    get configErrorMessage() {
+      return configError;
+    },
+    get buildErrorMessage() {
+      return buildError;
+    },
   };
 }
 
+function normalizeErrorMessage(message) {
+  if (message == null) {
+    return String(message);
+  }
+  if (typeof message === 'string') {
+    return message;
+  }
+  if (typeof message === 'object' && typeof message.message === 'string') {
+    return message.message;
+  }
+  return String(message);
+}
+
+/**
+ * browser に注入する runtime script を組み立てます。
+ * stylesheet 判定は stylesheet-reload.js の関数本体を埋め込み、実装 drift を防ぎます。
+ *
+ * @param {object} options
+ * @returns {string}
+ */
+function buildClientScript(options) {
+  const liveReloadPath = JSON.stringify(options.liveReloadPath);
+  const overlayHostId = JSON.stringify(options.overlayHostId);
+  const cssLoadTimeoutMs = Number(options.cssLoadTimeoutMs) || CSS_LOAD_TIMEOUT_MS;
+
+  return [
+    '<script>',
+    '(function () {',
+    '  var LIVE_RELOAD_PATH = ' + liveReloadPath + ';',
+    '  var OVERLAY_HOST_ID = ' + overlayHostId + ';',
+    '  var CSS_LOAD_TIMEOUT_MS = ' + cssLoadTimeoutMs + ';',
+    '  var overlayHost = null;',
+    '  var fallbackReloadScheduled = false;',
+    '  var isSameOriginStylesheetHref = ' +
+      isSameOriginStylesheetHref.toString() +
+      ';',
+    '  var appendCacheBustParam = ' + appendCacheBustParam.toString() + ';',
+    '',
+    '  function scheduleFullReload() {',
+    '    if (fallbackReloadScheduled) {',
+    '      return;',
+    '    }',
+    '    fallbackReloadScheduled = true;',
+    '    window.location.reload();',
+    '  }',
+    '',
+    '  function ensureOverlayHost() {',
+    '    var existing = document.getElementById(OVERLAY_HOST_ID);',
+    '    if (existing) {',
+    '      overlayHost = existing;',
+    '      return existing;',
+    '    }',
+    '    var host = document.createElement("div");',
+    '    host.id = OVERLAY_HOST_ID;',
+    '    host.setAttribute("data-jskim-overlay", "true");',
+    '    host.style.all = "initial";',
+    '    host.style.position = "fixed";',
+    '    host.style.inset = "0";',
+    '    host.style.zIndex = "2147483646";',
+    '    host.style.pointerEvents = "none";',
+    '    document.documentElement.appendChild(host);',
+    '    overlayHost = host;',
+    '    return host;',
+    '  }',
+    '',
+    '  function showErrorOverlay(message) {',
+    '    var host = ensureOverlayHost();',
+    '    var shadow = host.shadowRoot || host.attachShadow({ mode: "open" });',
+    '    while (shadow.firstChild) {',
+    '      shadow.removeChild(shadow.firstChild);',
+    '    }',
+    '    var style = document.createElement("style");',
+    '    style.textContent = [',
+    '      ":host { all: initial; }",',
+    '      ".wrap { pointer-events: auto; position: fixed; inset: 0; display: flex; align-items: flex-start; justify-content: center; padding: 24px 16px; box-sizing: border-box; background: rgba(20, 20, 20, 0.55); font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; }",',
+    '      ".panel { width: min(920px, 100%); max-height: min(80vh, 720px); display: flex; flex-direction: column; background: #111; color: #f5f5f5; border: 1px solid #444; box-shadow: 0 12px 40px rgba(0,0,0,0.45); }",',
+    '      ".head { display: flex; align-items: center; justify-content: space-between; gap: 12px; padding: 12px 14px; border-bottom: 1px solid #333; background: #1a1a1a; }",',
+    '      ".title { font-size: 14px; font-weight: 700; letter-spacing: 0.02em; }",',
+    '      ".close { pointer-events: auto; border: 1px solid #666; background: #222; color: #fff; padding: 4px 10px; cursor: pointer; font: inherit; }",',
+    '      ".body { overflow: auto; padding: 14px; margin: 0; white-space: pre-wrap; word-break: break-word; font-size: 12px; line-height: 1.5; }"',
+    '    ].join("");',
+    '    var wrap = document.createElement("div");',
+    '    wrap.className = "wrap";',
+    '    var panel = document.createElement("div");',
+    '    panel.className = "panel";',
+    '    var head = document.createElement("div");',
+    '    head.className = "head";',
+    '    var title = document.createElement("div");',
+    '    title.className = "title";',
+    '    title.textContent = "JSKim dev error";',
+    '    var closeBtn = document.createElement("button");',
+    '    closeBtn.type = "button";',
+    '    closeBtn.className = "close";',
+    '    closeBtn.textContent = "Close";',
+    '    closeBtn.addEventListener("click", function () {',
+    '      hideErrorOverlay();',
+    '    });',
+    '    var body = document.createElement("pre");',
+    '    body.className = "body";',
+    '    body.textContent = String(message == null ? "" : message);',
+    '    head.appendChild(title);',
+    '    head.appendChild(closeBtn);',
+    '    panel.appendChild(head);',
+    '    panel.appendChild(body);',
+    '    wrap.appendChild(panel);',
+    '    shadow.appendChild(style);',
+    '    shadow.appendChild(wrap);',
+    '    host.style.display = "block";',
+    '    host.style.pointerEvents = "none";',
+    '  }',
+    '',
+    '  function hideErrorOverlay() {',
+    '    var host = overlayHost || document.getElementById(OVERLAY_HOST_ID);',
+    '    if (!host) {',
+    '      return;',
+    '    }',
+    '    if (host.shadowRoot) {',
+    '      while (host.shadowRoot.firstChild) {',
+    '        host.shadowRoot.removeChild(host.shadowRoot.firstChild);',
+    '      }',
+    '    }',
+    '    host.style.display = "none";',
+    '  }',
+    '',
+    '  function isSameOriginHref(href) {',
+    '    return isSameOriginStylesheetHref(href, window.location.href);',
+    '  }',
+    '',
+    '  function withCacheBust(href, token) {',
+    '    return appendCacheBustParam(href, window.location.href, token);',
+    '  }',
+    '',
+    '  function reloadStylesheets() {',
+    '    var links = Array.prototype.slice.call(',
+    '      document.querySelectorAll(\'link[rel~="stylesheet"]\')',
+    '    );',
+    '    var targets = [];',
+    '    for (var i = 0; i < links.length; i += 1) {',
+    '      var link = links[i];',
+    '      var href = link.getAttribute("href") || link.href;',
+    '      if (isSameOriginHref(href)) {',
+    '        targets.push(link);',
+    '      }',
+    '    }',
+    '    if (targets.length === 0) {',
+    '      scheduleFullReload();',
+    '      return;',
+    '    }',
+    '',
+    '    var token = String(Date.now());',
+    '    var remaining = targets.length;',
+    '    var failed = false;',
+    '',
+    '    function doneOne(ok) {',
+    '      if (failed) {',
+    '        return;',
+    '      }',
+    '      if (!ok) {',
+    '        failed = true;',
+    '        scheduleFullReload();',
+    '        return;',
+    '      }',
+    '      remaining -= 1;',
+    '      if (remaining <= 0) {',
+    '        fallbackReloadScheduled = false;',
+    '      }',
+    '    }',
+    '',
+    '    for (var j = 0; j < targets.length; j += 1) {',
+    '      (function (oldLink) {',
+    '        var nextHref = withCacheBust(oldLink.getAttribute("href") || oldLink.href, token);',
+    '        if (!nextHref) {',
+    '          doneOne(false);',
+    '          return;',
+    '        }',
+    '        var clone = oldLink.cloneNode(true);',
+    '        clone.setAttribute("href", nextHref);',
+    '        var settled = false;',
+    '        var timer = setTimeout(function () {',
+    '          if (settled) {',
+    '            return;',
+    '          }',
+    '          settled = true;',
+    '          doneOne(false);',
+    '        }, CSS_LOAD_TIMEOUT_MS);',
+    '        function finish(ok) {',
+    '          if (settled) {',
+    '            return;',
+    '          }',
+    '          settled = true;',
+    '          clearTimeout(timer);',
+    '          if (ok) {',
+    '            if (oldLink.parentNode) {',
+    '              oldLink.parentNode.removeChild(oldLink);',
+    '            }',
+    '          }',
+    '          doneOne(ok);',
+    '        }',
+    '        clone.addEventListener("load", function () { finish(true); });',
+    '        clone.addEventListener("error", function () { finish(false); });',
+    '        if (oldLink.parentNode) {',
+    '          oldLink.parentNode.insertBefore(clone, oldLink.nextSibling);',
+    '        } else {',
+    '          finish(false);',
+    '        }',
+    '      })(targets[j]);',
+    '    }',
+    '  }',
+    '',
+    '  try {',
+    '    var source = new EventSource(LIVE_RELOAD_PATH);',
+    '    source.addEventListener("reload", function () {',
+    '      window.location.reload();',
+    '    });',
+    '    source.addEventListener("error", function (event) {',
+    '      if (event && typeof event.data === "string" && event.data) {',
+    '        try {',
+    '          var payload = JSON.parse(event.data);',
+    '          showErrorOverlay(payload.message || "Build error");',
+    '        } catch (err) {',
+    '          showErrorOverlay("Build error");',
+    '        }',
+    '        return;',
+    '      }',
+    '      console.info("[JSKim] ライブリロード接続を再試行しています…");',
+    '    });',
+    '    source.addEventListener("clear-error", function () {',
+    '      hideErrorOverlay();',
+    '    });',
+    '    source.addEventListener("css", function () {',
+    '      try {',
+    '        reloadStylesheets();',
+    '      } catch (err) {',
+    '        scheduleFullReload();',
+    '      }',
+    '    });',
+    '  } catch (err) {',
+    '    console.warn("[JSKim] ライブリロードを開始できませんでした。");',
+    '  }',
+    '})();',
+    '</script>',
+  ].join('\n');
+}
+
 module.exports = {
   createLiveReload,
   LIVE_RELOAD_PATH,
+  OVERLAY_HOST_ID,
+  CSS_LOAD_TIMEOUT_MS,
+  buildClientScript,
+  normalizeErrorMessage,
 };

package/scripts/lib/create-project-watcher.js

@@ -114,9 +114,11 @@ function createProjectWatcher(project, options = {}) {
       return;
     }
 
+    const absolutePath = path.resolve(filePath);
     pendingEvents.push({
       event: eventName,
-      file: toDisplayPath(filePath, workspaceRoot),
+      file: toDisplayPath(absolutePath, workspaceRoot),
+      absolutePath,
     });
 
     if (debounceTimer) {

package/scripts/lib/create-watch-runtime.js

@@ -9,6 +9,7 @@ const { createProjectWatcher } = require('./create-project-watcher');
 const { createStaticServer } = require('./create-static-server');
 const { createLiveReload } = require('./create-live-reload');
 const { formatListenError } = require('../commands/serve-errors');
+const { classifyReload } = require('./classify-reload');
 
 const DEV_RESTART_KEYS = [
   'outputDir',
@@ -77,13 +78,15 @@ function createWatchRuntime(options) {
     currentProject = resolved.project;
     configPath = resolved.configPath;
 
+    // ready ログより先に config 監視を開始する。
+    // そうしないと「監視しています」直後の config 変更を見逃すことがある。
+    beginConfigWatching();
+
     if (mode === 'dev') {
       await startDevSession(currentProject, { initial: true });
     } else {
       await startWatchSession(currentProject, { initial: true });
     }
-
-    beginConfigWatching();
   }
 
   async function startWatchSession(project, { initial }) {
@@ -185,10 +188,28 @@ function createWatchRuntime(options) {
   }
 
   function wireDevSourceReload(watcher) {
-    watcher.on('build:success', ({ initial }) => {
-      if (!initial && liveReloadEnabled && liveReload) {
-        liveReload.broadcastReload();
+    watcher.on('build:success', ({ initial, events }) => {
+      if (initial || !liveReloadEnabled || !liveReload) {
+        return;
       }
+      // 未解決の config error がある間は source 成功で overlay/reload しない
+      if (liveReload.hasConfigError()) {
+        return;
+      }
+      const kind = classifyReload({
+        events,
+        sourceDir: currentProject && currentProject.sourceDir,
+        templates: currentProject && currentProject.templates,
+      });
+      liveReload.notifySourceBuildSuccess(kind);
+    });
+
+    watcher.on('build:failure', ({ error }) => {
+      if (!liveReloadEnabled || !liveReload) {
+        return;
+      }
+      // Error.message は完成済みの診断文字列を再利用する
+      liveReload.broadcastBuildError(error);
     });
   }
 
@@ -305,9 +326,17 @@ function createWatchRuntime(options) {
       console.error('[JSKim] 設定ファイルの再読み込みに失敗しました。');
       console.error(message);
       console.error('[JSKim] 以前の正常な設定を継続します。');
+      if (mode === 'dev' && liveReloadEnabled && liveReload) {
+        liveReload.broadcastConfigError(message);
+      }
       return;
     }
 
+    // candidate は validation 済み。以降の失敗は build error として扱う
+    if (mode === 'dev' && liveReloadEnabled && liveReload) {
+      liveReload.clearConfigError();
+    }
+
     if (mode === 'dev') {
       const restartKeys = getRestartRequiredChanges(currentProject, candidate);
       if (restartKeys.length > 0) {
@@ -348,6 +377,9 @@ function createWatchRuntime(options) {
       console.error('[JSKim] 設定の再読み込み後に監視の更新に失敗しました。');
       console.error(message);
       console.error('[JSKim] 以前の正常な設定を継続します。');
+      if (mode === 'dev' && liveReloadEnabled && liveReload) {
+        liveReload.broadcastConfigError(message);
+      }
       return;
     }
 
@@ -388,9 +420,9 @@ function createWatchRuntime(options) {
         hooks.onInitialBuildSuccess();
       }
     };
-    const onFailure = ({ initial }) => {
+    const onFailure = ({ initial, error }) => {
       if (initial && hooks.onInitialBuildFailure) {
-        hooks.onInitialBuildFailure();
+        hooks.onInitialBuildFailure(error);
       }
     };
     projectWatcher.on('build:success', onSuccess);

package/scripts/lib/stylesheet-reload.js

@@ -0,0 +1,58 @@
+'use strict';
+
+const CSS_CACHE_PARAM = '_jskim';
+
+/**
+ * same-origin の stylesheet URL かどうかを判定します。
+ * browser runtime へ Function#toString で埋め込むため、外部クロージャに依存しません。
+ *
+ * @param {string} href
+ * @param {string} pageOrigin location.origin または location.href
+ * @returns {boolean}
+ */
+function isSameOriginStylesheetHref(href, pageOrigin) {
+  if (!href || typeof href !== 'string') {
+    return false;
+  }
+  const trimmed = href.trim();
+  if (!trimmed || trimmed.startsWith('data:')) {
+    return false;
+  }
+
+  try {
+    const resolved = new URL(trimmed, pageOrigin);
+    const origin = new URL(pageOrigin);
+    return resolved.origin === origin.origin;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * cache-busting query を付与または更新します。hash と他 query は維持します。
+ * browser runtime へ Function#toString で埋め込むため、パラメータ名はリテラルです。
+ *
+ * @param {string} href
+ * @param {string} pageOrigin
+ * @param {string|number} token
+ * @returns {string|null}
+ */
+function appendCacheBustParam(href, pageOrigin, token) {
+  if (!isSameOriginStylesheetHref(href, pageOrigin)) {
+    return null;
+  }
+
+  try {
+    const url = new URL(href, pageOrigin);
+    url.searchParams.set('_jskim', String(token));
+    return `${url.pathname}${url.search}${url.hash}`;
+  } catch {
+    return null;
+  }
+}
+
+module.exports = {
+  CSS_CACHE_PARAM,
+  isSameOriginStylesheetHref,
+  appendCacheBustParam,
+};