pugkit 1.3.0 → 1.5.0

package/README.md

@@ -28,11 +28,12 @@ $ touch ./src/index.pug
 
 ## Commands
 
-| コマンド        | 内容                          |
-| --------------- | ----------------------------- |
-| `pugkit`        | 開発モード（Ctrl + C で停止） |
-| `pugkit build`  | 本番ビルド                    |
-| `pugkit sprite` | SVGスプライト生成             |
+| コマンド        | 内容                           |
+| --------------- | ------------------------------ |
+| `pugkit`        | 開発モード（Ctrl + C で停止）  |
+| `pugkit build`  | 本番ビルド                     |
+| `pugkit sprite` | SVGスプライト生成              |
+| `pugkit bench`  | 画像サイズベンチマーク（全体） |
 
 ## Directory Structure
 
@@ -81,25 +82,38 @@ export default defineConfig({
     startPath: '/'
   },
   build: {
-    imageOptimization: 'webp'
+    // 'avif' | 'webp' | 'compress' | false
+    imageOptimization: 'webp',
+    html: {
+      indent_size: 2,
+      wrap_line_length: 0
+    }
   }
 })
 ```
 
-| Option                    | Description                                                                                  | Type / Values                       | Default       |
-| ------------------------- | -------------------------------------------------------------------------------------------- | ----------------------------------- | ------------- |
-| `siteUrl`                 | サイトのベースURL（`Builder.url` に使用）                                                    | `string`                            | `''`          |
-| `subdir`                  | サブディレクトリのパス                                                                       | `string`                            | `''`          |
-| `outDir`                  | ビルド出力先ディレクトリ。相対・絶対パス・ネスト（`htdocs/v2`）・上位（`../htdocs`）も指定可 | `string`                            | `'dist'`      |
-| `debug`                   | デバッグモード（開発時のみ有効）                                                             | `boolean`                           | `false`       |
-| `server.port`             | 開発サーバーのポート番号                                                                     | `number`                            | `5555`        |
-| `server.host`             | 開発サーバーのホスト                                                                         | `string`                            | `'localhost'` |
-| `server.startPath`        | サーバー起動時に開くパス                                                                     | `string`                            | `'/'`         |
-| `build.clean`             | ビルド前に `outDir` をクリーンするか（`false` にすると他リソースと共存可能）                 | `boolean`                           | `true`        |
-| `build.imageOptimization` | 画像最適化の方式                                                                             | `'webp'` \| `'compress'` \| `false` | `'webp'`      |
-| `build.imageOptions.webp` | WebP変換オプション（[Sharp WebP options](https://sharp.pixelplumbing.com/api-output#webp)）  | `object`                            | -             |
-| `build.imageOptions.jpeg` | JPEG圧縮オプション（[Sharp JPEG options](https://sharp.pixelplumbing.com/api-output#jpeg)）  | `object`                            | -             |
-| `build.imageOptions.png`  | PNG圧縮オプション（[Sharp PNG options](https://sharp.pixelplumbing.com/api-output#png)）     | `object`                            | -             |
+| Option                               | Description                                                                                           | Type / Values                                   | Default       |
+| ------------------------------------ | ----------------------------------------------------------------------------------------------------- | ----------------------------------------------- | ------------- |
+| `siteUrl`                            | サイトのベースURL（`Builder.url` に使用）                                                             | `string`                                        | `''`          |
+| `subdir`                             | サブディレクトリのパス                                                                                | `string`                                        | `''`          |
+| `outDir`                             | ビルド出力先ディレクトリ。相対・絶対パス・ネスト（`htdocs/v2`）・上位（`../htdocs`）も指定可          | `string`                                        | `'dist'`      |
+| `debug`                              | デバッグモード（開発時のみ有効）                                                                      | `boolean`                                       | `false`       |
+| `server.port`                        | 開発サーバーのポート番号                                                                              | `number`                                        | `5555`        |
+| `server.host`                        | 開発サーバーのホスト                                                                                  | `string`                                        | `'localhost'` |
+| `server.startPath`                   | サーバー起動時に開くパス                                                                              | `string`                                        | `'/'`         |
+| `build.clean`                        | ビルド前に `outDir` をクリーンするか（`false` にすると他リソースと共存可能）                          | `boolean`                                       | `true`        |
+| `build.imageOptimization`            | 画像最適化の方式                                                                                      | `'avif'` \| `'webp'` \| `'compress'` \| `false` | `'webp'`      |
+| `build.imageOptions.avif`            | AVIF変換オプション（[Sharp AVIF options](https://sharp.pixelplumbing.com/api-output#avif)）           | `object`                                        | -             |
+| `build.imageOptions.webp`            | WebP変換オプション（[Sharp WebP options](https://sharp.pixelplumbing.com/api-output#webp)）           | `object`                                        | -             |
+| `build.imageOptions.jpeg`            | JPEG圧縮オプション（[Sharp JPEG options](https://sharp.pixelplumbing.com/api-output#jpeg)）           | `object`                                        | -             |
+| `build.imageOptions.png`             | PNG圧縮オプション（[Sharp PNG options](https://sharp.pixelplumbing.com/api-output#png)）              | `object`                                        | -             |
+| `build.imageInfo.artDirectionSuffix` | アートディレクション用画像のサフィックス（`_sp`, `_tb`, `_pc` など）                                  | `string`                                        | `'_sp'`       |
+| `build.imageOverrides`               | 特定画像に個別のSharpオプションを適用（グローバルオプションに上書きマージ）                           | `Record<string, object>`                        | `{}`          |
+| `build.html`                         | HTML整形オプション（[js-beautify html options](https://github.com/beautify-web/js-beautify#options)） | `object`                                        | see below     |
+| `benchmark.image.threshold`          | `pugkit bench` で警告を出すファイルサイズ上限                                                         | `string` (`'200KB'` / `'1MB'` など)             | `'300KB'`     |
+| `benchmark.image.qualityMin`         | シミュレーションの quality 最小値                                                                     | `number`                                        | `40`          |
+| `benchmark.image.qualityMax`         | シミュレーションの quality 最大値                                                                     | `number`                                        | `90`          |
+| `benchmark.image.qualityStep`        | シミュレーションの quality ステップ幅                                                                 | `number`                                        | `10`          |
 
 ## Features
 
@@ -128,22 +142,31 @@ meta(property='og:url', content=Builder.url.href)
 
 #### imageInfo()
 
-`src/` 配下の画像のメタデータを取得します。`imageOptimization` の設定に応じて `src` が最適化後のパスに変換され、`@2x`/`_sp` 画像が存在する場合も自動的に解決されます。
+`src/` 配下の画像のメタデータを取得します。`imageOptimization` の設定に応じて `src` が最適化後のパスに変換され、retina / アートディレクション画像が存在する場合も自動的に解決されます。
 
 ```pug
 - const info = imageInfo('/assets/img/hero.jpg')
 img(src=info.src width=info.width height=info.height alt='')
 ```
 
-| Property | Type                             | Description                                           |
-| -------- | -------------------------------- | ----------------------------------------------------- |
-| `src`    | `string`                         | 最適化設定に応じたパス（webpモード時は `.webp` パス） |
-| `width`  | `number \| undefined`            | 画像の幅（px）                                        |
-| `height` | `number \| undefined`            | 画像の高さ（px）                                      |
-| `format` | `string \| undefined`            | 画像フォーマット（`'jpg'` / `'png'` / `'svg'` など）  |
-| `isSvg`  | `boolean`                        | SVG かどうか                                          |
-| `retina` | `{ src: string } \| null`        | `@2x` 画像が存在する場合に自動検出                    |
-| `sp`     | `{ src, width, height } \| null` | `_sp` 画像が存在する場合に自動検出                    |
+| Property  | Type                                                     | Description                                                                   |
+| --------- | -------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| `src`     | `string`                                                 | 最適化設定に応じたパス（avifモード時は `.avif`、webpモード時は `.webp` パス） |
+| `width`   | `number \| undefined`                                    | 画像の幅（px）                                                                |
+| `height`  | `number \| undefined`                                    | 画像の高さ（px）                                                              |
+| `format`  | `string \| undefined`                                    | 画像フォーマット（`'jpg'` / `'png'` / `'svg'` など）                          |
+| `isSvg`   | `boolean`                                                | SVG かどうか                                                                  |
+| `retina`  | `{ src: string, width: number, height: number } \| null` | `@2x` 画像が存在する場合に自動検出                                            |
+| `variant` | `{ src: string, width: number, height: number } \| null` | `imageInfo.artDirectionSuffix` に応じて検出したアートディレクション画像       |
+
+```pug
+- const info = imageInfo('/assets/img/hero.jpg')
+//- retina srcset
+- const srcset = info.retina ? `${info.src} 1x, ${info.retina.src} 2x` : undefined
+//- アートディレクション
+if info.variant
+  source(media='(max-width: 767px)' srcset=info.variant.src width=info.variant.width height=info.variant.height)
+```
 
 > `imageInfo()` は `src/` 配下の画像のみ対応しています。`public/` 配下の画像は非対応です。
 
@@ -197,10 +220,95 @@ npm install --save-dev typescript
 
 ビルド時に `src/` 配下の画像（JPEG・PNG）を自動的に最適化します。
 
+- `'avif'` - PNG/JPEGをAVIFに変換
 - `'webp'` - PNG/JPEGをWebPに変換
 - `'compress'` - 元の形式を維持したまま圧縮
 - `false` - 最適化を無効化
 
+#### 特定画像の個別オプション指定
+
+`build.imageOverrides` で特定の画像にのみ別の圧縮オプションを適用できます。キーは `src/` からの相対パス、値はグローバル設定に上書きマージされる [Sharp](https://sharp.pixelplumbing.com/api-output) オプションオブジェクトです。
+
+```js
+build: {
+  imageOptimization: 'webp',
+  imageOverrides: {
+    // 品質を上げたい画像
+    'assets/img/bg-hero.jpg': { quality: 100 },
+  }
+}
+```
+
+### Image Benchmark
+
+`pugkit bench` は `src/` 配下の画像を現在の `imageOptimization` 設定でシミュレートし、`benchmark.image.threshold` を超えるファイルを検出・報告します。ビルドは行わずメモリ上で処理するため、実ファイルへの影響はありません。
+
+```sh
+# src/ 全体をスキャン
+pugkit bench
+
+# ディレクトリ指定
+pugkit bench src/assets/img/top/
+
+# 単一ファイル指定
+pugkit bench src/assets/img/hero.jpg
+```
+
+閾値を超えた画像に対して、qualityを変化させたシミュレーション結果と、閾値以内で品質を最大限維持できるqualityの推奨値を表示します。
+
+```
+⚠ 1 image(s) exceed threshold (300KB) with current config
+──────────────────────────┬─────────┬──────────
+ file                     │ format  │     size
+──────────────────────────┼─────────┼──────────
+ assets/img/top/kv@2x.jpg │ webp    │   490 KB
+──────────────────────────┴─────────┴──────────
+
+Simulation: assets/img/top/kv@2x.jpg  (original: 2.62 MB  2800×1576)
+ format: webp  (effort / other options follow config)
+─────────┬───────────┬───────────┬────────
+ quality │      size │     ratio │ budget
+─────────┼───────────┼───────────┼────────
+      90 │    490 KB │      -82% │ ⚠  ← current
+      40 │    132 KB │      -95% │ ✔
+      80 │    268 KB │      -90% │ ✔
+─────────┴───────────┴───────────┴────────
+★ Recommended: quality 80  →  268 KB (-90%)
+```
+
+`pugkit.config.mjs` で閾値やシミュレーション範囲を設定できます。
+
+```js
+export default defineConfig({
+  benchmark: {
+    image: {
+      threshold: '300KB', // 警告を出す上限サイズ
+      qualityMin: 50, // シミュレーション quality の最小値
+      qualityMax: 90, // シミュレーション quality の最大値
+      qualityStep: 10 // quality のステップ幅
+    }
+  }
+})
+```
+
+### HTML Formatting
+
+ビルド時にPugから生成されたHTMLを[js-beautify](https://github.com/beautify-web/js-beautify)で整形します。`build.html` で js-beautify の設定をそのまま渡せます。
+
+```js
+build: {
+  html: {
+    indent_size: 2,
+    indent_with_tabs: false,
+    wrap_line_length: 0,
+    inline: [],
+    content_unformatted: ['script', 'style', 'pre']
+  }
+}
+```
+
+利用可能なオプションは [js-beautify のドキュメント](https://github.com/beautify-web/js-beautify#options)を参照してください。
+
 ### SVG Optimization
 
 `icons/`以外に配置した SVG ファイルはSVGOで自動最適化されて出力されます。

package/cli/bench.mjs

@@ -0,0 +1,371 @@
+import { glob } from 'glob'
+import { stat, readFile } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { resolve, extname, relative } from 'node:path'
+import sharp from 'sharp'
+import { logger } from '../utils/logger.mjs'
+import { loadConfig } from '../config/index.mjs'
+
+// ──────────────────────────────────────────────
+// Helpers
+// ──────────────────────────────────────────────
+
+/**
+ * '400KB' / '1.5MB' / '102400' などをバイト数に変換
+ */
+function parseThreshold(value) {
+  if (typeof value === 'number') return value
+  const str = String(value).trim().toUpperCase()
+  const match = str.match(/^([\d.]+)\s*(KB|MB|B)?$/)
+  if (!match) throw new Error(`Invalid threshold value: "${value}"`)
+  const num = parseFloat(match[1])
+  const unit = match[2] || 'B'
+  if (unit === 'MB') return Math.round(num * 1024 * 1024)
+  if (unit === 'KB') return Math.round(num * 1024)
+  return Math.round(num)
+}
+
+function formatBytes(bytes) {
+  if (bytes >= 1024 * 1024) return `${(bytes / 1024 / 1024).toFixed(2)} MB`
+  if (bytes >= 1024) return `${Math.round(bytes / 1024)} KB`
+  return `${bytes} B`
+}
+
+function formatRatio(original, compressed) {
+  const pct = ((original - compressed) / original) * 100
+  return `-${pct.toFixed(0)}%`
+}
+
+function pad(str, len) {
+  return String(str).padEnd(len)
+}
+
+function padL(str, len) {
+  return String(str).padStart(len)
+}
+
+/** ANSIカラー */
+const c = {
+  reset: '\x1b[0m',
+  dim: '\x1b[2m',
+  cyan: '\x1b[36m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  red: '\x1b[31m',
+  bold: '\x1b[1m'
+}
+
+// ──────────────────────────────────────────────
+// Sharp シミュレーション
+// ──────────────────────────────────────────────
+
+/**
+ * 画像を1回だけデコードして raw ピクセルデータとメタ情報を返す
+ * 以降のシミュレーションはこれを使い回す（ディスク再読み込みなし）
+ */
+async function decodeImage(filePath) {
+  const fileBuffer = await readFile(filePath)
+  const { data, info } = await sharp(fileBuffer).raw().toBuffer({ resolveWithObject: true })
+  return { fileBuffer, rawData: data, info }
+}
+
+/**
+ * raw ピクセルデータから sharp インスタンスを生成
+ */
+function fromRaw(rawData, info) {
+  return sharp(rawData, {
+    raw: { width: info.width, height: info.height, channels: info.channels }
+  })
+}
+
+/**
+ * 現在の config 設定でシミュレートしたバイト数を返す（rawData 使い回し）
+ */
+async function getCurrentSimulatedSize(rawData, info, ext, config) {
+  const optimization = config.build.imageOptimization
+  const opts = config.build.imageOptions
+  const image = fromRaw(rawData, info)
+
+  if (optimization === 'webp') {
+    return (await image.webp(opts.webp).toBuffer()).length
+  }
+  if (optimization === 'avif') {
+    return (await image.avif(opts.avif).toBuffer()).length
+  }
+  if (ext === '.jpg' || ext === '.jpeg') {
+    return (await image.jpeg(opts.jpeg).toBuffer()).length
+  }
+  if (ext === '.png') {
+    return (await image.png(opts.png).toBuffer()).length
+  }
+  return null // GIF 等は非対応
+}
+
+/**
+ * 指定フォーマット・品質でシミュレートしたバイト数を返す（rawData 使い回し）
+ */
+async function simulateFormat(rawData, info, format, quality, imageOptions) {
+  const image = fromRaw(rawData, info)
+  if (format === 'webp') {
+    return (await image.webp({ ...imageOptions.webp, quality }).toBuffer()).length
+  }
+  if (format === 'avif') {
+    return (await image.avif({ ...imageOptions.avif, quality }).toBuffer()).length
+  }
+  if (format === 'jpeg') {
+    return (await image.jpeg({ ...imageOptions.jpeg, quality }).toBuffer()).length
+  }
+  if (format === 'png') {
+    return (await image.png(imageOptions.png).toBuffer()).length
+  }
+  throw new Error(`Unknown format: ${format}`)
+}
+
+/**
+ * 現在の config から "current format" と "current quality" を取得
+ */
+function getCurrentFormatInfo(filePath, config) {
+  const optimization = config.build.imageOptimization
+  if (optimization === 'webp') {
+    return { format: 'webp', quality: config.build.imageOptions.webp.quality }
+  }
+  if (optimization === 'avif') {
+    return { format: 'avif', quality: config.build.imageOptions.avif.quality }
+  }
+  const ext = extname(filePath).toLowerCase().replace('.', '')
+  const format = ext === 'jpg' ? 'jpeg' : ext
+  const quality = config.build.imageOptions[format]?.quality ?? null
+  return { format, quality }
+}
+
+// ──────────────────────────────────────────────
+// ファイル収集
+// ──────────────────────────────────────────────
+
+async function collectImages(root, target) {
+  const srcDir = resolve(root, 'src')
+
+  if (!target) {
+    // デフォルト: src/ 以下全体
+    return await glob('**/*.{jpg,jpeg,png}', {
+      cwd: srcDir,
+      absolute: true,
+      ignore: ['**/_*/**']
+    })
+  }
+
+  const targetPath = resolve(root, target)
+
+  if (!existsSync(targetPath)) {
+    throw new Error(`Target not found: ${targetPath}`)
+  }
+
+  const s = await stat(targetPath)
+  if (s.isDirectory()) {
+    return await glob('**/*.{jpg,jpeg,png}', {
+      cwd: targetPath,
+      absolute: true,
+      ignore: ['**/_*/**']
+    })
+  }
+
+  // 単一ファイル
+  const ext = extname(targetPath).toLowerCase()
+  if (!/\.(jpg|jpeg|png)$/.test(ext)) {
+    throw new Error(`Unsupported file type: ${targetPath}`)
+  }
+  return [targetPath]
+}
+
+// ──────────────────────────────────────────────
+// テーブル表示
+// ──────────────────────────────────────────────
+
+function printWarningTable(rows, thresholdStr) {
+  const W_FILE = Math.max(30, ...rows.map(r => r.rel.length))
+  const FMT_W = 7 // format 列幅
+  const SZ_W = 9 // size 列幅
+  // 各セル幅: col1=W_FILE+1, col2=FMT_W+2, col3=SZ_W+1
+  const sep = `${'─'.repeat(W_FILE + 1)}┬${'─'.repeat(FMT_W + 2)}┬${'─'.repeat(SZ_W + 1)}`
+
+  console.log()
+  console.log(`${c.yellow}⚠ ${rows.length} image(s) exceed threshold (${thresholdStr}) with current config${c.reset}`)
+  console.log(sep)
+  console.log(` ${pad('file', W_FILE)}│ ${pad('format', FMT_W)} │ ${padL('size', SZ_W)}`)
+  console.log(sep)
+  for (const r of rows) {
+    const sizeStr = formatBytes(r.simulatedSize) // ← simulatedSize を使用
+    console.log(` ${pad(r.rel, W_FILE)}│ ${pad(r.format, FMT_W)} │ ${c.yellow}${padL(sizeStr, SZ_W)}${c.reset}`)
+  }
+  console.log(sep)
+}
+
+function printSimulationTable(rows, originalSize, currentQuality) {
+  const Q_W = 7 // quality 列幅
+  const S_W = 9 // size 列幅
+  const R_W = 9 // ratio 列幅
+  // 各セル幅: col1=Q_W+2, col2=S_W+2, col3=R_W+2, col4=8
+  const sep = `${'─'.repeat(Q_W + 2)}┬${'─'.repeat(S_W + 2)}┬${'─'.repeat(R_W + 2)}┬${'─'.repeat(8)}`
+
+  console.log(sep)
+  console.log(` ${padL('quality', Q_W)} │ ${padL('size', S_W)} │ ${padL('ratio', R_W)} │ budget`)
+  console.log(sep)
+
+  for (const row of rows) {
+    const sizeStr = formatBytes(row.size)
+    const ratioStr = formatRatio(originalSize, row.size)
+    const budgetStr = row.ok ? `${c.green}✔${c.reset}` : `${c.yellow}⚠${c.reset}`
+    const isCurrent = row.quality === currentQuality
+    const currentMark = isCurrent ? `${c.dim} ← current${c.reset}` : ''
+
+    console.log(
+      ` ${padL(row.quality ?? '-', Q_W)} │ ${padL(sizeStr, S_W)} │ ${padL(ratioStr, R_W)} │ ${budgetStr}${currentMark}`
+    )
+  }
+  console.log(sep)
+}
+
+// ──────────────────────────────────────────────
+// メイン
+// ──────────────────────────────────────────────
+
+export async function benchImage(options = {}) {
+  const { root = process.cwd(), target } = options
+
+  const config = await loadConfig(root)
+  const benchCfg = config.benchmark?.image ?? {}
+
+  // オプションは config のみで解決
+  const thresholdStr = benchCfg.threshold ?? '400KB'
+  const threshold = parseThreshold(String(thresholdStr))
+  const qualityMin = parseInt(benchCfg.qualityMin ?? 40)
+  const qualityMax = parseInt(benchCfg.qualityMax ?? 90)
+  const qualityStep = parseInt(benchCfg.qualityStep ?? 10)
+
+  // ファイル収集
+  let images
+  try {
+    images = await collectImages(root, target)
+  } catch (err) {
+    logger.error('bench', err.message)
+    process.exit(1)
+  }
+
+  if (images.length === 0) {
+    logger.skip('bench', 'No images found')
+    return
+  }
+
+  const srcDir = resolve(root, 'src')
+  logger.info('bench', `Scanning ${images.length} image(s)  (threshold: ${thresholdStr})`)
+
+  // ── Step 1: 現在の config でシミュレート → 閾値超えを検出 ──
+  // 1枚ずつ順番に処理（大量画像でのメモリスパイクを防ぐ）
+  const overThreshold = []
+
+  for (const filePath of images) {
+    const ext = extname(filePath).toLowerCase()
+    const s = await stat(filePath)
+
+    // GIF 等はスキップ
+    if (!/\.(jpg|jpeg|png)$/.test(ext)) continue
+
+    // 1回だけデコード（このスコープを抜けると GC 対象）
+    const { rawData, info } = await decodeImage(filePath)
+    const simulatedSize = await getCurrentSimulatedSize(rawData, info, ext, config)
+
+    if (simulatedSize !== null && simulatedSize > threshold) {
+      const { format } = getCurrentFormatInfo(filePath, config)
+      overThreshold.push({
+        filePath,
+        rel: relative(srcDir, filePath),
+        originalSize: s.size,
+        simulatedSize,
+        format,
+        rawData, // Step 2 で使い回す
+        info
+      })
+    }
+    // rawData を overThreshold に入れない場合はここで GC される
+  }
+
+  if (overThreshold.length === 0) {
+    logger.success('bench', `All images are within threshold (${thresholdStr})`)
+    return
+  }
+
+  // 警告テーブル
+  printWarningTable(overThreshold, thresholdStr)
+
+  // imageOverrides サジェスト収集
+  const suggestions = []
+
+  // ── Step 2: 閾値超え画像ごとにシミュレーション ──
+  for (const item of overThreshold) {
+    const { filePath, rel, originalSize, rawData, info } = item
+    const { format: currentFormat, quality: currentQuality } = getCurrentFormatInfo(filePath, config)
+
+    // メタ情報は Step 1 で取得済みの info を使う（再読み込みなし）
+    const dim = info.width && info.height ? `  ${info.width}×${info.height}` : ''
+
+    console.log()
+    console.log(
+      `${c.bold}Simulation: ${rel}${c.reset}  ${c.dim}(original: ${formatBytes(originalSize)}${dim})${c.reset}`
+    )
+
+    const rows = []
+
+    // 現在の設定を先頭に
+    rows.push({
+      format: currentFormat,
+      quality: currentQuality,
+      size: item.simulatedSize,
+      ok: item.simulatedSize <= threshold
+    })
+
+    // 現在のフォーマット固定で quality のみ変化（既存の imageOptions の他設定は維持）
+    for (let q = qualityMin; q <= qualityMax; q += qualityStep) {
+      if (q === currentQuality) continue
+      const size = await simulateFormat(rawData, info, currentFormat, q, config.build.imageOptions)
+      rows.push({ format: currentFormat, quality: q, size, ok: size <= threshold })
+    }
+
+    // quality 昇順ソート（current は固定で先頭）
+    const [current, ...rest] = rows
+    rest.sort((a, b) => a.quality - b.quality)
+
+    console.log(`${c.dim} format: ${currentFormat}  (effort / other options follow config)${c.reset}`)
+    printSimulationTable([current, ...rest], originalSize, currentQuality)
+
+    // 推奨サジェスト：閾値以内で最も高い quality（品質を最大限残す）
+    const passing = rest.filter(r => r.ok)
+    if (passing.length > 0) {
+      const best = passing[passing.length - 1] // quality 昇順の末尾 = 最高品質
+      console.log(
+        `${c.green}★ Recommended: quality ${best.quality}  →  ${formatBytes(best.size)} (${formatRatio(originalSize, best.size)})${c.reset}`
+      )
+      suggestions.push({ rel, quality: best.quality })
+    } else {
+      console.log(`${c.yellow}  No quality within threshold. Consider resizing the source image.${c.reset}`)
+    }
+  }
+
+  // ── imageOverrides スニペット出力 ──
+  if (suggestions.length > 0) {
+    console.log()
+    console.log(`${c.cyan}💡 Apply to pugkit.config.mjs:${c.reset}`)
+    console.log(`${c.dim}   build: {${c.reset}`)
+    console.log(`${c.dim}     imageOverrides: {${c.reset}`)
+    for (const s of suggestions) {
+      console.log(`${c.dim}       '${s.rel}': { quality: ${s.quality} },${c.reset}`)
+    }
+    console.log(`${c.dim}     }${c.reset}`)
+    console.log(`${c.dim}   }${c.reset}`)
+  }
+
+  console.log()
+}
+
+export async function bench(options = {}) {
+  await benchImage(options)
+}

package/cli/index.mjs

@@ -7,6 +7,7 @@ import { cac } from 'cac'
 import { develop } from './develop.mjs'
 import { build } from './build.mjs'
 import { sprite } from './sprite.mjs'
+import { benchImage } from './bench.mjs'
 
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = path.dirname(__filename)
@@ -50,6 +51,15 @@ cli.command('sprite [root]', 'Generate SVG sprite').action(async root => {
   }
 })
 
+cli.command('bench [target]', 'Benchmark images in src/ against pugkit.config.mjs').action(async target => {
+  try {
+    await benchImage({ root: process.cwd(), target })
+  } catch (err) {
+    console.error(err)
+    process.exit(1)
+  }
+})
+
 cli.help()
 cli.version(pkgVersion())
 cli.parse()

package/config/defaults.mjs

@@ -11,13 +11,26 @@ export const defaultConfig = {
   build: {
     clean: true,
     imageOptimization: 'webp',
+    imageInfo: {
+      artDirectionSuffix: '_sp'
+    },
+    imageOverrides: {},
+    html: {
+      indent_size: 2,
+      indent_with_tabs: false,
+      max_preserve_newlines: 1,
+      preserve_newlines: false,
+      end_with_newline: true,
+      extra_liners: [],
+      wrap_line_length: 0,
+      inline: [],
+      content_unformatted: ['script', 'style', 'pre']
+    },
     imageOptions: {
       webp: {
-        quality: 90,
-        effort: 6,
+        quality: 80,
+        effort: 4,
         smartSubsample: true,
-        method: 6,
-        reductionEffort: 6,
         alphaQuality: 100,
         lossless: false
       },
@@ -31,7 +44,21 @@ export const defaultConfig = {
         compressionLevel: 6,
         adaptiveFiltering: true,
         palette: true
+      },
+      avif: {
+        quality: 70,
+        lossless: false,
+        effort: 4,
+        chromaSubsampling: '4:4:4'
       }
     }
+  },
+  benchmark: {
+    image: {
+      threshold: '300KB',
+      qualityMin: 40,
+      qualityMax: 90,
+      qualityStep: 10
+    }
   }
 }

package/config/main.mjs

@@ -30,7 +30,26 @@ function mergeConfig(defaults, user) {
       imageOptions: {
         webp: { ...defaults.build.imageOptions.webp, ...(user.build?.imageOptions?.webp || {}) },
         jpeg: { ...defaults.build.imageOptions.jpeg, ...(user.build?.imageOptions?.jpeg || {}) },
-        png: { ...defaults.build.imageOptions.png, ...(user.build?.imageOptions?.png || {}) }
+        png: { ...defaults.build.imageOptions.png, ...(user.build?.imageOptions?.png || {}) },
+        avif: { ...defaults.build.imageOptions.avif, ...(user.build?.imageOptions?.avif || {}) }
+      },
+      imageInfo: {
+        ...defaults.build.imageInfo,
+        ...(user.build?.imageInfo || {})
+      },
+      imageOverrides: {
+        ...defaults.build.imageOverrides,
+        ...(user.build?.imageOverrides || {})
+      },
+      html: {
+        ...defaults.build.html,
+        ...(user.build?.html || {})
+      }
+    },
+    benchmark: {
+      image: {
+        ...defaults.benchmark.image,
+        ...(user.benchmark?.image || {})
       }
     }
   }
@@ -41,7 +60,6 @@ function validateConfig(config) {
   const outDir = config.outDir
   const resolvedOutDir = isAbsolute(outDir) ? outDir : resolve(root, outDir)
 
-  // Vite同様、outDirがrootと同一またはrootの親ディレクトリの場合に警告
   // relative() を使うことでWindows（バックスラッシュ）でも正しく動作する
   const isSameAsRoot = resolvedOutDir === root
   const relToRoot = relative(resolvedOutDir, root)

package/core/context.mjs

@@ -11,6 +11,7 @@ export class BuildContext {
     this.graph = new DependencyGraph()
     this.sassGraph = new DependencyGraph()
     this.scriptGraph = new DependencyGraph()
+    this.imageGraph = new DependencyGraph() // Pug -> 画像ファイルの依存グラフ（dev時に構築）
 
     const outDir = config.outDir ?? 'dist'
     const resolvedOutDir = isAbsolute(outDir) ? outDir : resolve(config.root, outDir)

package/core/watcher.mjs

@@ -2,6 +2,7 @@ import chokidar from 'chokidar'
 import { rm } from 'node:fs/promises'
 import { relative, resolve, basename, extname } from 'node:path'
 import { logger } from '../utils/logger.mjs'
+import { clearImageSizeCache } from '../transform/image-size.mjs'
 
 /**
  * ファイル監視タスク
@@ -43,7 +44,7 @@ class FileWatcher {
         ignoreInitial: true,
         ignored: [/(^|[\/\\])\./, /node_modules/, /\.git/],
         persistent: true,
-        awaitWriteFinish: { stabilityThreshold: 100, pollInterval: 50 }
+        awaitWriteFinish: { stabilityThreshold: 100, pollInterval: 100 }
       })
       .on('change', filePath => this.handleChange(filePath))
       .on('add', filePath => this.handleAdd(filePath))
@@ -116,10 +117,11 @@ class FileWatcher {
   }
 
   async onPugUnlink(filePath) {
-    const { paths, cache, graph } = this.context
+    const { paths, cache, graph, imageGraph } = this.context
     const relPath = relative(paths.src, filePath)
     cache.invalidatePugTemplate(filePath)
     graph.clearDependencies(filePath)
+    imageGraph.clearDependencies(filePath)
     if (basename(filePath).startsWith('_')) {
       logger.info('unlink', relPath)
       return
@@ -202,12 +204,19 @@ class FileWatcher {
   // ---- Image ----
 
   async onImageChange(filePath, event) {
+    clearImageSizeCache()
     const relPath = relative(this.context.paths.src, filePath)
     logger.info(event, `image: ${relPath}`)
     try {
       if (this.context.taskRegistry?.image) {
         await this.context.taskRegistry.image(this.context, { files: [filePath] })
       }
+      // imageGraph から影響を受ける Pug ファイルのみ再ビルド
+      // グラフ未構築（初回 dev 起動直後など）の場合は全 Pug を再ビルド
+      if (this.context.taskRegistry?.pug) {
+        const affected = this.context.imageGraph.getAffectedParents(filePath)
+        await this.context.taskRegistry.pug(this.context, { files: affected.length > 0 ? affected : undefined })
+      }
       this.reload()
     } catch (error) {
       logger.error('watch', `Image processing failed: ${error.message}`)
@@ -215,13 +224,24 @@ class FileWatcher {
   }
 
   async onImageUnlink(filePath) {
+    clearImageSizeCache()
     const { paths, config } = this.context
     const relPath = relative(paths.src, filePath)
-    const useWebp = config.build.imageOptimization === 'webp'
+    const optimization = config.build.imageOptimization
     const ext = extname(filePath)
-    const destRelPath = useWebp ? relPath.replace(new RegExp(`\\${ext}$`, 'i'), '.webp') : relPath
+    const newExt = optimization === 'avif' || optimization === 'webp' ? `.${optimization}` : ext
+    const destRelPath = relPath.replace(new RegExp(`\\${ext}$`, 'i'), newExt)
     const distPath = resolve(paths.dist, destRelPath)
     await this.deleteDistFile(distPath, relPath)
+    // imageGraph から影響を受ける Pug ファイルのみ再ビルド
+    if (this.context.taskRegistry?.pug) {
+      const affected = this.context.imageGraph.getAffectedParents(filePath)
+      this.context.imageGraph.clearDependencies(filePath)
+      if (affected.length > 0) {
+        await this.context.taskRegistry.pug(this.context, { files: affected })
+        this.reload()
+      }
+    }
   }
 
   // ---- Public ----

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pugkit",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "description": "A build tool for Pug-based projects",
   "type": "module",
   "license": "MIT",

package/tasks/image.mjs

@@ -1,15 +1,19 @@
 import { glob } from 'glob'
 import { readFile, writeFile } from 'node:fs/promises'
-import { relative, resolve, dirname, extname } from 'node:path'
+import { relative, resolve, extname } from 'node:path'
 import sharp from 'sharp'
 import { logger } from '../utils/logger.mjs'
 import { ensureFileDir } from '../utils/file.mjs'
 
+// libvips の内部キャッシュを制限してメモリ消費を抑える
+sharp.cache({ memory: 50, files: 20, items: 200 })
+sharp.concurrency(1)
+
 /**
  * 画像最適化タスク
  */
 export async function imageTask(context, options = {}) {
-  const { paths, config, isProduction, cache } = context
+  const { paths, config, isProduction } = context
 
   const optimization = config.build.imageOptimization
 
@@ -40,6 +44,19 @@ export async function imageTask(context, options = {}) {
 
   logger.info('image', `Processing ${images.length} image(s)`)
 
+  if (optimization === 'avif' || optimization === 'webp') {
+    const outputMap = new Map()
+    for (const file of images) {
+      const rel = relative(paths.src, file)
+      const outPath = rel.replace(/\.(jpg|jpeg|png|gif)$/i, `.${optimization}`)
+      if (outputMap.has(outPath)) {
+        logger.warn('image', `Output conflict: "${outputMap.get(outPath)}" and "${rel}" both map to "${outPath}"`)
+      } else {
+        outputMap.set(outPath, rel)
+      }
+    }
+  }
+
   // 並列処理
   await Promise.all(images.map(file => processImage(file, context, optimization, isProduction)))
 
@@ -49,30 +66,35 @@ export async function imageTask(context, options = {}) {
 /**
  * 画像を処理（最適化）
  */
-async function processImage(filePath, context, optimization, isProduction) {
+async function processImage(filePath, context, optimization, isProduction, retries = 3, retryDelay = 200) {
   const { paths, config } = context
   const ext = extname(filePath).toLowerCase()
   const relativePath = relative(paths.src, filePath)
+  const overrideKey = relativePath.replace(/\\/g, '/')
+  const overrides = config.build.imageOverrides?.[overrideKey] ?? {}
 
   try {
     const image = sharp(filePath)
-    const metadata = await image.metadata()
 
     let outputPath
     let outputImage
 
-    if (optimization === 'webp') {
+    if (optimization === 'avif') {
+      // AVIF変換
+      outputPath = resolve(paths.dist, relativePath.replace(/\.(jpg|jpeg|png|gif)$/i, '.avif'))
+      outputImage = image.avif({ ...config.build.imageOptions.avif, ...overrides })
+    } else if (optimization === 'webp') {
       // WebP変換
       outputPath = resolve(paths.dist, relativePath.replace(/\.(jpg|jpeg|png|gif)$/i, '.webp'))
-      outputImage = image.webp(config.build.imageOptions.webp)
+      outputImage = image.webp({ ...config.build.imageOptions.webp, ...overrides })
     } else {
       // 元の形式で圧縮
       outputPath = resolve(paths.dist, relativePath)
 
       if (ext === '.jpg' || ext === '.jpeg') {
-        outputImage = image.jpeg(config.build.imageOptions.jpeg)
+        outputImage = image.jpeg({ ...config.build.imageOptions.jpeg, ...overrides })
       } else if (ext === '.png') {
-        outputImage = image.png(config.build.imageOptions.png)
+        outputImage = image.png({ ...config.build.imageOptions.png, ...overrides })
       } else {
         // GIFなどはそのままコピー
         const buffer = await readFile(filePath)
@@ -86,6 +108,10 @@ async function processImage(filePath, context, optimization, isProduction) {
     await ensureFileDir(outputPath)
     await outputImage.toFile(outputPath)
   } catch (error) {
+    if (retries > 0 && error.message.includes('unsupported image format')) {
+      await new Promise(resolve => setTimeout(resolve, retryDelay))
+      return processImage(filePath, context, optimization, isProduction, retries - 1, retryDelay * 2)
+    }
     logger.error('image', `Failed to process ${relativePath}: ${error.message}`)
   }
 }

package/tasks/pug.mjs

@@ -24,7 +24,7 @@ export async function pugTask(context, options = {}) {
   }
 
   logger.info('pug', `Building ${changed.length} file(s)`)
-  await Promise.all(changed.map(file => processFile(file, context)))
+  await runWithConcurrency(changed, 8, file => processFile(file, context))
   logger.success('pug', `Built ${changed.length} file(s)`)
 }
 
@@ -48,8 +48,18 @@ async function resolveChangedFiles(files, targetFiles, cache, isProduction) {
   return files
 }
 
+async function runWithConcurrency(items, concurrency, fn) {
+  let i = 0
+  const workers = Array.from({ length: Math.min(concurrency, items.length) }, async () => {
+    while (i < items.length) {
+      await fn(items[i++])
+    }
+  })
+  await Promise.all(workers)
+}
+
 async function processFile(filePath, context) {
-  const { paths, config, cache, graph } = context
+  const { paths, config, cache, graph, imageGraph } = context
 
   try {
     let template = cache.getPugTemplate(filePath)
@@ -65,11 +75,21 @@ async function processFile(filePath, context) {
     }
 
     const builderVars = createBuilderVars(filePath, paths, config)
-    const imageSize = createImageSizeHelper(filePath, paths, logger)
-    const imageInfo = createImageInfoHelper(filePath, paths, logger, config)
+
+    // dev 時のみ: imageGraph に Pug->画像 の依存を記録して画像変更時の最小再ビルドに使う
+    const accessedImages = new Set()
+    const onAccess = context.isDevelopment ? imgPath => accessedImages.add(imgPath) : undefined
+    const imageSize = createImageSizeHelper(filePath, paths, logger, { onAccess })
+    const imageInfo = createImageInfoHelper(filePath, paths, logger, config, { onAccess })
 
     const html = template({ Builder: builderVars, imageSize, imageInfo })
-    const formatted = formatHtml(html)
+
+    if (context.isDevelopment && imageGraph) {
+      imageGraph.clearDependencies(filePath)
+      accessedImages.forEach(imgPath => imageGraph.addDependency(filePath, imgPath))
+    }
+
+    const formatted = formatHtml(html, config.build.html)
     await generatePage(filePath, formatted, paths)
   } catch (error) {
     logger.error('pug', `Failed: ${basename(filePath)} - ${error.message}`)

package/transform/html.mjs

@@ -3,16 +3,5 @@ const { html: beautifyHtml } = pkg
 
 export function formatHtml(html, options = {}) {
   const cleaned = html.replace(/[\u200B-\u200D\uFEFF]/g, '')
-
-  return beautifyHtml(cleaned, {
-    indent_size: options.tabWidth || 2,
-    indent_with_tabs: options.useTabs || false,
-    max_preserve_newlines: 1,
-    preserve_newlines: false,
-    end_with_newline: true,
-    extra_liners: [],
-    wrap_line_length: 0,
-    inline: [],
-    content_unformatted: ['script', 'style', 'pre']
-  })
+  return beautifyHtml(cleaned, options)
 }

package/transform/image-size.mjs

@@ -1,8 +1,22 @@
 import { readFileSync, existsSync } from 'node:fs'
-import { resolve, dirname, basename, extname } from 'node:path'
+import { resolve, relative, dirname, basename, extname } from 'node:path'
 import sizeOf from 'image-size'
 
-export function createImageSizeHelper(filePath, paths, logger) {
+// ビルドセッション内で画像ファイルの内容をキャッシュし、同じファイルの重複読み込みを防ぐ
+const _imageBufferCache = new Map()
+
+function readImageCached(filePath) {
+  if (_imageBufferCache.has(filePath)) return _imageBufferCache.get(filePath)
+  const buf = readFileSync(filePath)
+  _imageBufferCache.set(filePath, buf)
+  return buf
+}
+
+export function clearImageSizeCache() {
+  _imageBufferCache.clear()
+}
+
+export function createImageSizeHelper(filePath, paths, logger, { onAccess } = {}) {
   return src => {
     const resolveImagePath = (imageSrc, baseDir) => {
       if (imageSrc.startsWith('/')) {
@@ -24,21 +38,25 @@ export function createImageSizeHelper(filePath, paths, logger) {
       const foundPath = findImageFile(resolvedPath)
 
       if (foundPath) {
-        const buffer = readFileSync(foundPath)
+        onAccess?.(foundPath)
+        const buffer = readImageCached(foundPath)
         return sizeOf(buffer)
       }
 
-      logger?.warn('pug', `Image not found: ${basename(resolvedPath)}`)
+      logger?.warn('pug', `Image not found "${src}" in ${relative(paths.src, filePath)}`)
       return { width: undefined, height: undefined }
     } catch {
-      logger?.warn('pug', `Failed to get image size: ${basename(src)}`)
+      logger?.warn('pug', `Failed to read "${src}" in ${relative(paths.src, filePath)}`)
       return { width: undefined, height: undefined }
     }
   }
 }
 
-export function createImageInfoHelper(filePath, paths, logger, config) {
-  const useWebp = config?.build?.imageOptimization === 'webp'
+export function createImageInfoHelper(filePath, paths, logger, config, { onAccess } = {}) {
+  const optimization = config?.build?.imageOptimization
+  const newExt = optimization === 'avif' || optimization === 'webp' ? `.${optimization}` : null
+  const artDirectionSuffix = config?.build?.imageInfo?.artDirectionSuffix ?? '_sp'
+
   return src => {
     const resolveImagePath = (imageSrc, baseDir) => {
       if (imageSrc.startsWith('/')) {
@@ -59,7 +77,7 @@ export function createImageInfoHelper(filePath, paths, logger, config) {
       format: undefined,
       isSvg: false,
       retina: null,
-      sp: null
+      variant: null
     }
 
     try {
@@ -68,50 +86,59 @@ export function createImageInfoHelper(filePath, paths, logger, config) {
       const foundPath = findImageFile(resolvedPath)
 
       if (!foundPath) {
-        logger?.warn('pug', `Image not found: ${basename(resolvedPath)}`)
+        logger?.warn('pug', `Image not found "${src}" in ${relative(paths.src, filePath)}`)
         return fallback
       }
 
-      const buffer = readFileSync(foundPath)
+      const buffer = readImageCached(foundPath)
+      onAccess?.(foundPath)
       const { width, height, type: format } = sizeOf(buffer)
 
       const ext = extname(src)
       const isSvg = ext.toLowerCase() === '.svg'
       const base = src.slice(0, -ext.length)
-      // webp モード時は src 自体を .webp パスに変換（SVG は除外）
-      const resolvedSrc = useWebp && !isSvg ? `${base}.webp` : src
+      // avif/webp モード時は src 自体を変換後のパスに変換（SVG は除外）
+      const resolvedSrc = !isSvg && newExt ? `${base}${newExt}` : src
 
-      // 2x retina 画像の自動検出
+      // @2x retina 画像の自動検出
       let retina = null
       if (!isSvg) {
         const retinaSrc = `${base}@2x${ext}`
         const retinaResolvedPath = resolveImagePath(retinaSrc, pageDir)
         const retinaFoundPath = findImageFile(retinaResolvedPath)
         if (retinaFoundPath) {
-          retina = { src: useWebp ? `${base}@2x.webp` : retinaSrc }
+          const retinaBuffer = readImageCached(retinaFoundPath)
+          onAccess?.(retinaFoundPath)
+          const { width: rWidth, height: rHeight } = sizeOf(retinaBuffer)
+          retina = {
+            src: newExt ? `${base}@2x${newExt}` : retinaSrc,
+            width: rWidth,
+            height: rHeight
+          }
         }
       }
 
-      // SP 画像の自動検出
-      let sp = null
+      // アートディレクション画像の自動検出
+      let variant = null
       if (!isSvg) {
-        const spSrc = `${base}_sp${ext}`
-        const spResolvedPath = resolveImagePath(spSrc, pageDir)
-        const spFoundPath = findImageFile(spResolvedPath)
-        if (spFoundPath) {
-          const spBuffer = readFileSync(spFoundPath)
-          const { width: spWidth, height: spHeight } = sizeOf(spBuffer)
-          sp = {
-            src: useWebp ? `${base}_sp.webp` : spSrc,
-            width: spWidth,
-            height: spHeight
+        const variantSrc = `${base}${artDirectionSuffix}${ext}`
+        const variantResolvedPath = resolveImagePath(variantSrc, pageDir)
+        const variantFoundPath = findImageFile(variantResolvedPath)
+        if (variantFoundPath) {
+          const variantBuffer = readImageCached(variantFoundPath)
+          onAccess?.(variantFoundPath)
+          const { width: vWidth, height: vHeight } = sizeOf(variantBuffer)
+          variant = {
+            src: newExt ? `${base}${artDirectionSuffix}${newExt}` : variantSrc,
+            width: vWidth,
+            height: vHeight
           }
         }
       }
 
-      return { src: resolvedSrc, width, height, format, isSvg, retina, sp }
+      return { src: resolvedSrc, width, height, format, isSvg, retina, variant }
     } catch {
-      logger?.warn('pug', `Failed to get image info: ${basename(src)}`)
+      logger?.warn('pug', `Failed to read "${src}" in ${relative(paths.src, filePath)}`)
       return fallback
     }
   }