pugkit 1.2.0 → 1.4.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
 
@@ -55,7 +56,7 @@ project-root/
 
 ### File Naming Rules
 
-`_`（アンダースコア）で始まるファイル・ディレクトリはビルド対象外です。それ以外のファイルは `src/` 配下のディレクトリ構成を維持したまま `dist/` に出力されます。
+`_`（アンダースコア）で始まるファイル・ディレクトリはビルド対象外です。それ以外のファイルは `src/` 配下のディレクトリ構成を維持したまま `outDir`（デフォルト: `dist/`）に出力されます。
 
 ```
 src/foo/style.scss →  dist/foo/style.css
@@ -73,6 +74,7 @@ import { defineConfig } from 'pugkit'
 export default defineConfig({
   siteUrl: 'https://example.com/',
   subdir: '',
+  outDir: 'dist',
   debug: false,
   server: {
     port: 5555,
@@ -80,24 +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`                            | `''`          |
-| `debug`                   | デバッグモード（開発時のみ有効）                                                            | `boolean`                           | `false`       |
-| `server.port`             | 開発サーバーのポート番号                                                                    | `number`                            | `5555`        |
-| `server.host`             | 開発サーバーのホスト                                                                        | `string`                            | `'localhost'` |
-| `server.startPath`        | サーバー起動時に開くパス                                                                    | `string`                            | `'/'`         |
-| `build.clean`             | ビルド前に `dist/` をクリーンするか（`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
 
@@ -126,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/` 配下の画像は非対応です。
 
@@ -195,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で自動最適化されて出力されます。
@@ -208,7 +318,7 @@ npm install --save-dev typescript
 `src/`配下の`icons/`ディレクトリに配置したSVGを1つのスプライトファイルにまとめます。
 
 ```
-src/assets/icons/arrow.svg  →  dist/assets/icons.svg#arrow
+`src/assets/icons/arrow.svg  →  <outDir>/assets/icons.svg#arrow`
 ```
 
 ```html
@@ -220,7 +330,7 @@ src/assets/icons/arrow.svg  →  dist/assets/icons.svg#arrow
 
 ### Public Directory
 
-`public/` に置いたファイルはそのまま `dist/` のルートにコピーされます。faviconやOGP画像など最適化不要なファイルの置き場として使用します。
+`public/` に置いたファイルはそのまま `outDir` のルートにコピーされます。faviconやOGP画像など最適化不要なファイルの置き場として使用します。
 
 ### Debug Mode
 

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

@@ -1,6 +1,7 @@
 export const defaultConfig = {
   siteUrl: '',
   subdir: '',
+  outDir: 'dist',
   debug: false,
   server: {
     port: 5555,
@@ -10,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
       },
@@ -30,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

@@ -1,4 +1,4 @@
-import { resolve } from 'node:path'
+import { resolve, isAbsolute, relative } from 'node:path'
 import { existsSync } from 'node:fs'
 import { defaultConfig } from './defaults.mjs'
 
@@ -20,6 +20,7 @@ function mergeConfig(defaults, user) {
   return {
     siteUrl: user.siteUrl || defaults.siteUrl,
     subdir: user.subdir || defaults.subdir,
+    outDir: user.outDir !== undefined ? user.outDir : defaults.outDir,
     debug: user.debug !== undefined ? user.debug : defaults.debug,
     server: { ...defaults.server, ...(user.server || {}) },
     build: {
@@ -29,16 +30,56 @@ 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 || {})
       }
     }
   }
 }
 
+function validateConfig(config) {
+  const root = config.root
+  const outDir = config.outDir
+  const resolvedOutDir = isAbsolute(outDir) ? outDir : resolve(root, outDir)
+
+  // relative() を使うことでWindows（バックスラッシュ）でも正しく動作する
+  const isSameAsRoot = resolvedOutDir === root
+  const relToRoot = relative(resolvedOutDir, root)
+  const isParentOfRoot = relToRoot !== '' && !relToRoot.startsWith('..')
+
+  if (isSameAsRoot || isParentOfRoot) {
+    console.warn(
+      `[pugkit] outDir "${outDir}" はプロジェクトルートと同じか親ディレクトリです。` +
+        `ソースファイルが上書きされる可能性があるため、別のディレクトリを指定してください。`
+    )
+  }
+
+  return config
+}
+
 export async function loadConfig(root = process.cwd()) {
   const userConfig = await loadUserConfig(root)
   const config = mergeConfig(defaultConfig, userConfig)
   config.root = root
+  validateConfig(config)
   return config
 }
 

package/core/context.mjs

@@ -1,4 +1,4 @@
-import { resolve } from 'node:path'
+import { resolve, isAbsolute } from 'node:path'
 import { CacheManager } from './cache.mjs'
 import { DependencyGraph } from './graph.mjs'
 import { createGlobPatterns } from '../config/index.mjs'
@@ -12,10 +12,14 @@ export class BuildContext {
     this.sassGraph = new DependencyGraph()
     this.scriptGraph = new DependencyGraph()
 
+    const outDir = config.outDir ?? 'dist'
+    const resolvedOutDir = isAbsolute(outDir) ? outDir : resolve(config.root, outDir)
+
     this.paths = {
       root: config.root,
       src: resolve(config.root, 'src'),
-      dist: resolve(config.root, 'dist', config.subdir || ''),
+      outDir: resolvedOutDir,
+      dist: config.subdir ? resolve(resolvedOutDir, config.subdir) : resolvedOutDir,
       public: resolve(config.root, 'public')
     }
 

package/core/server.mjs

@@ -50,7 +50,7 @@ export async function serverTask(context, options = {}) {
   const startPath = (config.server?.startPath || '/').replace(/^\//, '')
   const fullStartPath = subdir ? `${subdir}/${startPath}` : `/${startPath}`
 
-  const serveRoot = path.resolve(config.root, 'dist')
+  const serveRoot = paths.outDir
 
   const clients = new Set()
 

package/core/watcher.mjs

@@ -217,9 +217,10 @@ class FileWatcher {
   async onImageUnlink(filePath) {
     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)
   }

package/package.json

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

package/tasks/image.mjs

@@ -1,6 +1,6 @@
 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'
@@ -9,7 +9,7 @@ import { ensureFileDir } from '../utils/file.mjs'
  * 画像最適化タスク
  */
 export async function imageTask(context, options = {}) {
-  const { paths, config, isProduction, cache } = context
+  const { paths, config, isProduction } = context
 
   const optimization = config.build.imageOptimization
 
@@ -40,6 +40,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)))
 
@@ -53,26 +66,31 @@ async function processImage(filePath, context, optimization, isProduction) {
   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)

package/tasks/pug.mjs

@@ -69,7 +69,7 @@ async function processFile(filePath, context) {
     const imageInfo = createImageInfoHelper(filePath, paths, logger, config)
 
     const html = template({ Builder: builderVars, imageSize, imageInfo })
-    const formatted = formatHtml(html)
+    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,5 +1,5 @@
 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) {
@@ -28,17 +28,20 @@ export function createImageSizeHelper(filePath, paths, logger) {
         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'
+  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 +62,7 @@ export function createImageInfoHelper(filePath, paths, logger, config) {
       format: undefined,
       isSvg: false,
       retina: null,
-      sp: null
+      variant: null
     }
 
     try {
@@ -68,7 +71,7 @@ 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
       }
 
@@ -78,40 +81,46 @@ export function createImageInfoHelper(filePath, paths, logger, config) {
       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 = readFileSync(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 = readFileSync(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
     }
   }