@ywal123456/jskim 0.3.0 → 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.0",
+  "version": "0.4.0",
   "description": "Nunjucks-based static HTML build environment with watch, serve, and live reload",
   "keywords": [
     "nunjucks",

package/scripts/commands/path-display.js

@@ -1,20 +1,6 @@
 'use strict';
 
-const path = require('node:path');
-
-/**
- * ワークスペース相対の表示用パスへ変換します。
- * @param {string} abs
- * @param {string} workspaceRoot
- * @returns {string}
- */
-function toDisplayPath(abs, workspaceRoot) {
-  const rel = path.relative(workspaceRoot, abs);
-  if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) {
-    return abs.split(path.sep).join('/');
-  }
-  return rel.split(path.sep).join('/');
-}
+const { toDisplayPath } = require('../lib/to-display-path');
 
 module.exports = {
   toDisplayPath,

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,
+};