mdv-live 0.5.13 → 0.5.15

package/CHANGELOG.md

@@ -5,6 +5,80 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.15] - 2026-05-09
+
+### Refactored
+
+- **PDF 生成ロジックを `src/services/pdf.js` に集約**:
+  - サーバー HTTP route (`src/api/pdf.js`) と CLI (`bin/mdv.js convert`) の
+    両方が **同じ実装** を共有
+  - bug fix・security check (realpath/symlink)・hoist 対応・stdin pipe ハング
+    対応・workspace 汚染回避 (temp copy) が 1 箇所に集約。今後どちらの経路
+    でも同じ品質を保つ
+- **CLI から `npx` を完全排除**:
+  - 旧: `execFileSync('npx', ['md-to-pdf', ...])` / `npx @marp-team/marp-cli`
+  - 新: `services/pdf.js` の `exportMarpPdf` / `exportMarkdownPdf` を直接呼ぶ
+  - 効果: registry 不通でも動く、バージョン揺れ防止、サーバー側と整合
+
+### Changed (breaking-ish)
+
+- **`md-to-pdf` を `optionalDependencies` に降格** (旧 `dependencies`):
+  - デフォルト `npm install mdv-live` で puppeteer/chromium DL がほぼ消滅
+    し、install 大幅軽量化 (Marp 使わない人は完全 skip)
+  - `@marp-team/marp-cli` も同じく optional (従来通り)
+  - PDF 機能 (Plain Markdown / Marp 両方) を使う場合は `--include=optional`
+    か通常 `npm install` (default で optional も入る)。CI で `--omit=optional`
+    してると `PDF_TOOL_UNAVAILABLE` になり 503 / exit 1 + 案内
+  - **既存ユーザー影響**: `npm install --omit=optional` していた人は要再 install
+
+### Tests
+
+- 247 → **249 件 (+2)**:
+  - `src/services/pdf.js` の import が throw しない
+  - `bin/mdv.js` が `npx` を呼んでいない (regression guard)
+
+### Chore
+
+- `tests/fixtures/html-preview/` `tests/fixtures/marp-notes/` を `.gitignore`
+  に追加 (test-html-preview.js が runtime に書き出す artifact)
+- `CODEX.md` を git 管理に追加 (codex review の Project ルール)
+
+### Docs
+
+- README に **依存パッケージは optional 扱い** であることと install 方法を明記
+
+## [0.5.14] - 2026-05-09
+
+### Changed — Style PDF dispatch をリファイン
+
+`PdfStyleManager` の dispatch 判定を **「PDF options JSON の有無」** に変更
+(これまでは「CSS or JSON のいずれか」で server PDF 経路に切り替わっていた)。
+
+| CSS | PDF options | PDF ボタン押下で |
+|---|---|---|
+| 空 | 空 | 印刷ダイアログ |
+| 入れる | 空 | **印刷ダイアログ** (preview CSS が styled DOM で print engine に渡る) |
+| 入れる/空 | 入れる | サーバー md-to-pdf で styled PDF 自動 DL |
+
+JSON は margin/format/printBackground 等の細かい制御用。CSS だけ当てて
+PDF にしたい普通のケースは印刷ダイアログで十分なので、md-to-pdf 経路に
+無闇に流さない。`shouldUseServerPdf()` メソッドに rename。
+
+### UX improvements
+
+- **Style パネルの placeholder/tooltip** を rootDir 相対パス前提のヒント
+  に変更 (`report.css (rootDir からの相対パス)` 等)。Claude Code 等で
+  ファイル生成して入力する人が迷わないように
+- **失敗時のステータスメッセージ詳細化**: 旧「Style failed」→ 新
+  「Style failed: CSS not found: <path>」のように原因を出す。表示時間
+  も 2.5s → 4.5s に延長 (読み切る時間)
+- **PDF export 失敗時** もサーバーから返されたエラーメッセージを
+  ステータスバーに表示
+
+### Docs
+
+- README の `Web UI` 節を全面改訂: dispatch テーブル + Claude Code 連携手順
+
 ## [0.5.13] - 2026-05-09
 
 ### Restored

package/README.md

@@ -78,6 +78,14 @@ mdv -v
 
 Markdown ファイルは CLI または Web UI から PDF に変換できます。
 
+> **依存パッケージは optional 扱い** — `@marp-team/marp-cli` (Marp 用) と `md-to-pdf` (Plain Markdown 用) は `optionalDependencies`。デフォルト `npm install` でも入りますが、CI 等で `--omit=optional` 指定すると入りません。**PDF 機能を使うなら**:
+> ```bash
+> npm install -g mdv-live  # 通常はこれで OK (optional も入る)
+> # CI などで --omit=optional する場合:
+> npm install --include=optional
+> ```
+> 不在のまま PDF 生成すると、サーバーは 503 + 案内、CLI は exit 1 + `npm install --include=optional` 提案を返します。
+
 ### CLI
 
 ```bash
@@ -107,12 +115,34 @@ mdv convert \
 
 ### Web UI
 
-ビューア上部の `Style` から以下を指定できます。
+ビューア上部の `Style` ボタンを押すとパネルが開き、以下を指定できます。
+
+- **CSS** — サーバー起動時の `rootDir` からの相対パス (例: `report.css`、`subdir/style.css`)
+- **PDF options** — `rootDir` からの相対パス (例: `pdf-options.json`)。省略可
+
+`Apply` を押すと CSS は Markdown プレビューにも反映されます。`Clear` で解除。
+
+#### PDF ボタン押下時の挙動 (Markdown ファイル)
+
+| CSS | PDF options | PDF ボタン押下で |
+|---|---|---|
+| 空 | 空 | OS の **印刷ダイアログ** (`window.print()`) |
+| 入れる | 空 | OS の印刷ダイアログ。preview の CSS が styled DOM として print engine に渡る |
+| 入れる/空 | **入れる** | サーバー側 `md-to-pdf` で **styled PDF を自動 DL** (`@page` で margin/format を JSON 制御したいときの本格モード) |
 
-- CSS ファイルパス
-- PDF options JSON ファイルパス
+`PDF options` を入れない限り印刷ダイアログ経由になるので、ふだんは CSS だけ指定すれば OK。
+
+#### Claude Code との連携
+
+CSS を Claude Code に生成させるとき、**サーバーの `rootDir` 配下** に保存して相対パスを Style パネルに入力してください。例:
+
+```
+$ mdv ~/notes        # rootDir = ~/notes
+# Claude Code で ~/notes/report.css を生成
+# Style パネル CSS 欄に "report.css" を入力 → Apply
+```
 
-CSS は Markdown プレビューにも反映されます。指定を解除する場合は `Clear` を押してください。
+ファイルが見つからない場合 `Style failed: CSS not found: <path>` がステータスバーに出ます。
 
 ### ポート自動増分
 

package/bin/mdv.js

@@ -5,7 +5,7 @@
  * Compatible with the original Python mdv-live CLI
  */
 
-import { execFileSync, execSync } from 'node:child_process';
+import { execSync } from 'node:child_process';
 import { readFileSync } from 'node:fs';
 import fs from 'node:fs/promises';
 import { createServer as createNetServer } from 'node:net';
@@ -17,6 +17,7 @@ import open from 'open';
 
 import { createMdvServer } from '../src/server.js';
 import { resolvePdfOptions, resolveStyle } from '../src/styles/index.js';
+import { exportMarpPdf, exportMarkdownPdf } from '../src/services/pdf.js';
 
 const DEFAULT_PORT = 8642;
 const MARP_FRONTMATTER_PATTERN = /^---\s*\n[\s\S]*?marp:\s*true[\s\S]*?\n---/;
@@ -287,27 +288,41 @@ async function convertToPdf(inputPath, outputPath, styleArg, pdfOptionsPath) {
 }
 
 /**
- * Convert Marp presentation to PDF using marp-cli
+ * Format a PDF tool error for CLI output.
+ * @param {Error} err
+ * @returns {string} Error message including install hint when applicable.
+ */
+function formatPdfToolError(err) {
+  if (err.code === 'PDF_TOOL_UNAVAILABLE') {
+    return `Error: ${err.message}\n  Run: npm install --include=optional`;
+  }
+  if (err.stderr) {
+    return `Error: PDF conversion failed\n${err.stderr}`;
+  }
+  return `Error: PDF conversion failed\n${err.message || err}`;
+}
+
+/**
+ * Convert Marp presentation to PDF using the shared service.
+ *
  * @param {string} inputPath - Resolved input file path
  * @param {string} outputPath - Resolved output file path
  * @returns {Promise<number>} Exit code
  */
 async function convertMarpToPdf(inputPath, outputPath) {
   try {
-    execFileSync('npx', ['@marp-team/marp-cli', '--no-stdin', inputPath, '--pdf', '--html', '--allow-local-files', '-o', outputPath], {
-      encoding: 'utf-8',
-      stdio: 'inherit'
-    });
+    await exportMarpPdf(inputPath, outputPath);
     console.log(`PDF saved: ${outputPath}`);
     return 0;
-  } catch {
-    console.error('Error: PDF conversion failed');
+  } catch (err) {
+    console.error(formatPdfToolError(err));
     return 1;
   }
 }
 
 /**
- * Convert regular markdown to PDF using md-to-pdf
+ * Convert regular markdown to PDF using the shared service.
+ *
  * @param {string} inputPath - Resolved input file path
  * @param {string} outputPath - Resolved output file path
  * @param {import('../src/styles/index.js').StyleConfig} styleConfig - Style preset
@@ -315,40 +330,12 @@ async function convertMarpToPdf(inputPath, outputPath) {
  */
 async function convertMarkdownToPdf(inputPath, outputPath, styleConfig) {
   console.log('Converting as document (A4 portrait)...');
-
   try {
-    const args = ['md-to-pdf', inputPath, '--pdf-options', JSON.stringify(styleConfig.pdfOptions)];
-    const stylesheetPaths = styleConfig.stylesheets ?? (styleConfig.stylesheet ? [styleConfig.stylesheet] : []);
-
-    for (const stylesheetPath of stylesheetPaths) {
-      args.push('--stylesheet', stylesheetPath);
-    }
-
-    if (styleConfig.highlightStyle) {
-      args.push('--highlight-style', styleConfig.highlightStyle);
-    }
-
-    if (styleConfig.css) {
-      args.push('--css', styleConfig.css);
-    }
-
-    execFileSync('npx', args, {
-      encoding: 'utf-8',
-      stdio: 'inherit',
-      cwd: path.dirname(inputPath),
-    });
-
-    // md-to-pdf outputs to same directory with .pdf extension
-    const generatedPdf = inputPath.replace(/\.(md|markdown)$/i, '.pdf');
-    if (generatedPdf !== outputPath) {
-      await fs.rename(generatedPdf, outputPath);
-    }
-
+    await exportMarkdownPdf(inputPath, outputPath, { styleConfig });
     console.log(`PDF saved: ${outputPath}`);
     return 0;
-  } catch {
-    console.error('Error: PDF conversion failed');
-    console.error('Make sure md-to-pdf is available (npx md-to-pdf)');
+  } catch (err) {
+    console.error(formatPdfToolError(err));
     return 1;
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mdv-live",
-  "version": "0.5.13",
+  "version": "0.5.15",
   "description": "Markdown Viewer - File tree + Live preview + Marp support + Hot reload",
   "main": "src/server.js",
   "bin": {
@@ -51,13 +51,13 @@
     "highlight.js": "^11.10.0",
     "markdown-it": "^14.1.0",
     "markdown-it-task-lists": "^2.1.1",
-    "md-to-pdf": "^5.2.5",
     "mime-types": "^2.1.35",
     "multer": "^1.4.5-lts.1",
     "open": "^10.1.0",
     "ws": "^8.18.0"
   },
   "optionalDependencies": {
-    "@marp-team/marp-cli": "^4.0.3"
+    "@marp-team/marp-cli": "^4.0.3",
+    "md-to-pdf": "^5.2.5"
   }
 }

package/src/api/pdf.js

@@ -1,94 +1,13 @@
-import { spawn } from 'child_process';
 import fs from 'fs/promises';
 import path from 'path';
 import os from 'os';
-import { createRequire } from 'module';
 import { isMarp } from '../rendering/markdown.js';
 import { validatePath, validatePathReal } from '../utils/path.js';
-import { resolvePdfOptions } from '../styles/index.js';
-
-const require = createRequire(import.meta.url);
-const highlightStylesheet = path.resolve(path.dirname(require.resolve('highlight.js')), '..', 'styles', 'atom-one-dark.css');
-const PDF_EXPORT_TIMEOUT_MS = 180000;
-
-/**
- * Lazily resolve a package's bin script via require.resolve.
- *
- * 0.5.10〜0.5.12 の hoist 罠 + optionalDependencies 欠如対応:
- * - npm hoisting で実体パスが top-level / nested いずれにもなる
- * - optionalDep が欠ける環境 (--omit=optional) では import 時に throw すると
- *   サーバー起動が壊れる → request 時に lazy で解決し、欠ければ 503
- *
- * @param {string} pkgName - npm package name (e.g. '@marp-team/marp-cli')
- * @param {string} binName - bin entry key (matches package.json bin)
- * @returns {string} Absolute path to the bin script
- * @throws {Error} `code === 'PDF_TOOL_UNAVAILABLE'` if package missing
- */
-function resolvePkgBin(pkgName, binName) {
-  let pkgPath;
-  try {
-    pkgPath = require.resolve(`${pkgName}/package.json`);
-  } catch (err) {
-    const e = new Error(`${pkgName} is not installed.`);
-    e.code = 'PDF_TOOL_UNAVAILABLE';
-    e.cause = err;
-    throw e;
-  }
-  const pkg = require(`${pkgName}/package.json`);
-  const bin = pkg.bin;
-  const binRel = typeof bin === 'string' ? bin : bin?.[binName];
-  if (!binRel) {
-    const e = new Error(`${pkgName} does not declare a "${binName}" bin entry.`);
-    e.code = 'PDF_TOOL_UNAVAILABLE';
-    throw e;
-  }
-  return path.join(path.dirname(pkgPath), binRel);
-}
-
-/**
- * Spawn a PDF tool with stdin closed.
- *
- * 注意: execFile は stdio オプションを受け付けない (Node 仕様)。md-to-pdf は
- * 内部で get-stdin を呼ぶため、stdin が pipe のままだと EOF を永遠に待ち続けて
- * ハングする。spawn で stdin を 'ignore' (= /dev/null) に明示的に縛る。
- */
-function runPdfTool(bin, args, { cwd } = {}) {
-  return new Promise((resolve, reject) => {
-    const child = spawn(process.execPath, [bin, ...args], {
-      cwd,
-      stdio: ['ignore', 'pipe', 'pipe'],
-    });
-    let stdout = '';
-    let stderr = '';
-    child.stdout.on('data', (chunk) => { stdout += chunk.toString(); });
-    child.stderr.on('data', (chunk) => { stderr += chunk.toString(); });
-
-    const timer = setTimeout(() => {
-      child.kill('SIGTERM');
-    }, PDF_EXPORT_TIMEOUT_MS);
-
-    child.on('error', (err) => {
-      clearTimeout(timer);
-      reject(err);
-    });
-    child.on('close', (code, signal) => {
-      clearTimeout(timer);
-      if (code === 0) {
-        resolve({ stdout, stderr });
-      } else {
-        const err = new Error(`${path.basename(bin)} exited with code=${code} signal=${signal}`);
-        err.code = code;
-        err.signal = signal;
-        err.stdout = stdout;
-        err.stderr = stderr;
-        reject(err);
-      }
-    });
-  });
-}
+import { exportMarpPdf, exportMarkdownPdf } from '../services/pdf.js';
 
 /**
  * Resolve an optional user-selected file path under the server root.
+ *
  * @param {string | undefined} relativePath - Path supplied by the web UI.
  * @param {string} rootDir - Server root directory.
  * @returns {Promise<string | null>} Absolute path or null.
@@ -106,65 +25,15 @@ async function resolveOptionalUserFile(relativePath, rootDir) {
   return fullPath;
 }
 
-/**
- * Export a regular markdown document with md-to-pdf.
- *
- * 注意 1: md-to-pdf CLI は出力ファイルを **ソース隣に同名 .pdf で書く** 仕様
- * (例: foo.md → foo.pdf next to source)。既存の foo.pdf があると上書き
- * してから temp に rename = ユーザーのワークスペース汚染 + 読み取り専用
- * dir で失敗。これを避けるためソースを **temp dir にコピー** してそこで
- * md-to-pdf を実行し、生成 PDF だけを最終 outputPath に rename する。
- *
- * 注意 2: JS API (mdToPdf()) を使う方法もあるが、puppeteer プロセスが
- * 残って Node test runner が event loop drain 待ちで cancel される。
- * spawn 経由なら子プロセスが exit するので確実に cleanup される。
- *
- * 注意 3: temp copy なので markdown 内の **相対パス画像/CSS** は壊れる。
- * Style 機能は CSS で見た目を整える用途を想定しており、相対パス画像を
- * 多用する markdown は対象外として割り切る。
- */
-async function exportMarkdownPdf(inputPath, outputPath, stylesheetPath, pdfOptionsPath) {
-  const mdToPdfBin = resolvePkgBin('md-to-pdf', 'md-to-pdf');
-  const pdfOptions = await resolvePdfOptions(pdfOptionsPath || undefined);
-
-  const tempSourceDir = await fs.mkdtemp(path.join(os.tmpdir(), 'mdv-md-'));
-  try {
-    const tempSourcePath = path.join(tempSourceDir, path.basename(inputPath));
-    await fs.copyFile(inputPath, tempSourcePath);
-
-    const args = [tempSourcePath, '--pdf-options', JSON.stringify(pdfOptions)];
-    if (stylesheetPath) {
-      args.push('--stylesheet', highlightStylesheet);
-      args.push('--stylesheet', stylesheetPath);
-      args.push('--highlight-style', 'atom-one-dark');
-    }
-
-    await runPdfTool(mdToPdfBin, args, { cwd: tempSourceDir });
-
-    const generatedPdf = tempSourcePath.replace(/\.(md|markdown)$/i, '.pdf');
-    await fs.rename(generatedPdf, outputPath);
-  } finally {
-    await fs.rm(tempSourceDir, { recursive: true, force: true });
-  }
-}
-
-/**
- * Export a Marp slide deck with marp-cli.
- *
- * `@marp-team/marp-cli` is an optionalDependency. When missing the route
- * returns a 503; that is surfaced by the caller.
- */
-async function exportMarpPdf(inputPath, outputPath) {
-  const marpBin = resolvePkgBin('@marp-team/marp-cli', 'marp');
-  await runPdfTool(marpBin, [inputPath, '-o', outputPath, '--html', '--allow-local-files', '--no-stdin']);
-}
-
 /**
  * Setup PDF export routes.
  *
  * - Marp files → `marp-cli` (slide PDF, landscape, themed)
  * - Plain Markdown → `md-to-pdf` (document PDF, optional CSS / PDF options)
  *
+ * 実装は `src/services/pdf.js` に集約。CLI (`bin/mdv.js convert`) も同じ
+ * service を使う。
+ *
  * @param {Express} app - Express application
  * @returns {void}
  */
@@ -210,7 +79,10 @@ export function setupPdfRoutes(app) {
           resolveOptionalUserFile(stylePath, rootDir),
           resolveOptionalUserFile(pdfOptionsPath, rootDir),
         ]);
-        await exportMarkdownPdf(fullPath, outputPath, stylesheetPath, resolvedPdfOptionsPath);
+        await exportMarkdownPdf(fullPath, outputPath, {
+          stylesheetPath,
+          pdfOptionsPath: resolvedPdfOptionsPath,
+        });
       }
 
       res.download(outputPath, outputFileName, async (err) => {
@@ -224,7 +96,7 @@ export function setupPdfRoutes(app) {
       try { await fs.unlink(outputPath); } catch { /* ignore */ }
       if (err.code === 'PDF_TOOL_UNAVAILABLE') {
         return res.status(503).json({
-          error: `PDF tool unavailable: ${err.message} Run \`npm install\` (without --omit=optional) and retry.`,
+          error: `PDF tool unavailable: ${err.message} Run \`npm install --include=optional\` and retry.`,
         });
       }
       res.status(500).json({ error: 'PDF export failed' });

package/src/services/pdf.js

@@ -0,0 +1,206 @@
+/**
+ * PDF generation service.
+ *
+ * 中央集約された PDF 化ロジック:
+ * - サーバー HTTP route (`src/api/pdf.js`) と CLI (`bin/mdv.js convert`) の
+ *   両方が同じ実装を共有することで、bug fix・security check・hoist 対応・
+ *   stdin pipe ハング対応・workspace 汚染回避ロジックを 1 箇所に集める
+ * - Marp は `@marp-team/marp-cli` (optionalDependency)
+ * - Plain markdown は `md-to-pdf` (optionalDependency: 0.5.15 で降格)
+ * - どちらも欠如時は `PDF_TOOL_UNAVAILABLE` code を投げ、caller 側で
+ *   ユーザー向けメッセージに変換 (HTTP 503 / CLI exit 1)
+ */
+
+import { spawn } from 'child_process';
+import { randomUUID } from 'crypto';
+import fs from 'fs/promises';
+import path from 'path';
+import os from 'os';
+import { createRequire } from 'module';
+import { resolvePdfOptions } from '../styles/index.js';
+
+const require = createRequire(import.meta.url);
+
+const highlightStylesheet = path.resolve(
+  path.dirname(require.resolve('highlight.js')),
+  '..',
+  'styles',
+  'atom-one-dark.css',
+);
+
+const PDF_EXPORT_TIMEOUT_MS = 180000;
+
+/**
+ * Lazily resolve a package's bin script via require.resolve.
+ *
+ * 0.5.10〜0.5.12 の hoist 罠 + optionalDependencies 欠如対応:
+ * - npm hoisting で実体パスが top-level / nested いずれにもなる
+ * - optionalDep が欠ける環境 (--omit=optional) では import 時に throw すると
+ *   サーバー起動が壊れる → request 時に lazy で解決し、欠ければ 503 / exit 1
+ *
+ * @param {string} pkgName - npm package name (e.g. '@marp-team/marp-cli')
+ * @param {string} binName - bin entry key (matches package.json bin)
+ * @returns {string} Absolute path to the bin script
+ * @throws {Error} `code === 'PDF_TOOL_UNAVAILABLE'` if package missing
+ */
+export function resolvePkgBin(pkgName, binName) {
+  let pkgPath;
+  try {
+    pkgPath = require.resolve(`${pkgName}/package.json`);
+  } catch (err) {
+    const e = new Error(`${pkgName} is not installed.`);
+    e.code = 'PDF_TOOL_UNAVAILABLE';
+    e.cause = err;
+    throw e;
+  }
+  const pkg = require(`${pkgName}/package.json`);
+  const bin = pkg.bin;
+  const binRel = typeof bin === 'string' ? bin : bin?.[binName];
+  if (!binRel) {
+    const e = new Error(`${pkgName} does not declare a "${binName}" bin entry.`);
+    e.code = 'PDF_TOOL_UNAVAILABLE';
+    throw e;
+  }
+  return path.join(path.dirname(pkgPath), binRel);
+}
+
+/**
+ * Spawn a PDF tool with stdin closed.
+ *
+ * 注意: execFile は stdio オプションを受け付けない (Node 仕様)。md-to-pdf は
+ * 内部で get-stdin を呼ぶため、stdin が pipe のままだと EOF を永遠に待ち続けて
+ * ハングする。spawn で stdin を 'ignore' (= /dev/null) に明示的に縛る。
+ */
+function runPdfTool(bin, args, { cwd } = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, [bin, ...args], {
+      cwd,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (chunk) => { stdout += chunk.toString(); });
+    child.stderr.on('data', (chunk) => { stderr += chunk.toString(); });
+
+    const timer = setTimeout(() => {
+      child.kill('SIGTERM');
+    }, PDF_EXPORT_TIMEOUT_MS);
+
+    child.on('error', (err) => {
+      clearTimeout(timer);
+      reject(err);
+    });
+    child.on('close', (code, signal) => {
+      clearTimeout(timer);
+      if (code === 0) {
+        resolve({ stdout, stderr });
+      } else {
+        const err = new Error(`${path.basename(bin)} exited with code=${code} signal=${signal}`);
+        err.code = code;
+        err.signal = signal;
+        err.stdout = stdout;
+        err.stderr = stderr;
+        reject(err);
+      }
+    });
+  });
+}
+
+/**
+ * Export a regular markdown document with md-to-pdf.
+ *
+ * 課題:
+ *  - md-to-pdf CLI は出力ファイルを **ソース隣に同名 .pdf で書く** 仕様
+ *    (例: foo.md → foo.pdf next to source)。既存の foo.pdf を上書きしないこと
+ *  - 同時に、`![logo](images/logo.png)` のような **相対 asset 参照** を解決
+ *    するためには md-to-pdf を **source dir で実行** する必要がある
+ *    (`--basedir` を別dir にすると md-to-pdf が input path から URL を逆算
+ *    して basedir 外と判定し asset がロードされない、codex round 2 P2)
+ *
+ * 解決:
+ *  - source dir 内に **隠し一意名 (`.mdv-pdf-tmp.<stamp>.md`)** で copy 配置
+ *  - md-to-pdf を source dir で実行 → 隠しPDFが source dir に生まれる
+ *  - その隠し PDF を outputPath に rename
+ *  - finally で隠し md / 隠し pdf を確実に削除 (source dir 残留物ゼロ)
+ *
+ * 副作用 / 制約:
+ *  - source dir に書き込み権が必要 (read-only dir では fs.copyFile が
+ *    EACCES/EROFS で throw → caller 側で 503/exit 1 を返す扱いに任せる)
+ *  - 一意名 + mdv prefix なので既存ファイル衝突なし
+ *
+ * @param {string} inputPath - Source markdown file (absolute).
+ * @param {string} outputPath - Destination PDF file (absolute).
+ * @param {object} [options]
+ * @param {string|null} [options.stylesheetPath] - Custom CSS file path.
+ * @param {string|null} [options.pdfOptionsPath] - PDF options JSON path.
+ * @param {object} [options.styleConfig] - Pre-resolved style config (CLI use).
+ *   When supplied, supersedes stylesheetPath / pdfOptionsPath.
+ * @returns {Promise<void>}
+ */
+export async function exportMarkdownPdf(inputPath, outputPath, options = {}) {
+  const { stylesheetPath = null, pdfOptionsPath = null, styleConfig = null } = options;
+
+  const mdToPdfBin = resolvePkgBin('md-to-pdf', 'md-to-pdf');
+  const pdfOptions = styleConfig?.pdfOptions
+    ?? await resolvePdfOptions(pdfOptionsPath || undefined);
+
+  const sourceDir = path.dirname(inputPath);
+  const ext = path.extname(inputPath); // .md / .markdown
+  // randomUUID で temp 名を一意に。process.pid + Date.now() だと同一 ms の
+  // concurrent 呼出 (例: 並行 /api/pdf/export) で衝突して別リクエストの
+  // 入力/出力を上書きする race があった (codex round 3 P2)
+  const stamp = `${process.pid}-${randomUUID()}`;
+  const tempSourcePath = path.join(sourceDir, `.mdv-pdf-tmp.${stamp}${ext}`);
+  const tempPdfPath = tempSourcePath.replace(/\.(md|markdown)$/i, '.pdf');
+
+  try {
+    await fs.copyFile(inputPath, tempSourcePath);
+
+    const args = [tempSourcePath, '--pdf-options', JSON.stringify(pdfOptions)];
+
+    // CLI 経路: styleConfig (resolveStyle 済み) を優先
+    if (styleConfig) {
+      const stylesheetPaths = styleConfig.stylesheets
+        ?? (styleConfig.stylesheet ? [styleConfig.stylesheet] : []);
+      for (const ssPath of stylesheetPaths) {
+        args.push('--stylesheet', ssPath);
+      }
+      if (styleConfig.highlightStyle) {
+        args.push('--highlight-style', styleConfig.highlightStyle);
+      }
+      if (styleConfig.css) {
+        args.push('--css', styleConfig.css);
+      }
+    } else if (stylesheetPath) {
+      // Web UI 経路: 単一 CSS path + デフォルト highlight
+      args.push('--stylesheet', highlightStylesheet);
+      args.push('--stylesheet', stylesheetPath);
+      args.push('--highlight-style', 'atom-one-dark');
+    }
+
+    await runPdfTool(mdToPdfBin, args, { cwd: sourceDir });
+    await fs.rename(tempPdfPath, outputPath);
+  } finally {
+    // 隠し md / 隠し pdf を確実に削除 (例外発生時も cleanup)
+    await fs.unlink(tempSourcePath).catch(() => {});
+    await fs.unlink(tempPdfPath).catch(() => {});
+  }
+}
+
+/**
+ * Export a Marp slide deck with marp-cli.
+ *
+ * @param {string} inputPath - Source Marp markdown file (absolute).
+ * @param {string} outputPath - Destination PDF file (absolute).
+ * @returns {Promise<void>}
+ */
+export async function exportMarpPdf(inputPath, outputPath) {
+  const marpBin = resolvePkgBin('@marp-team/marp-cli', 'marp');
+  await runPdfTool(marpBin, [
+    inputPath,
+    '-o', outputPath,
+    '--html',
+    '--allow-local-files',
+    '--no-stdin',
+  ]);
+}

package/src/static/app.js

@@ -273,9 +273,12 @@
             this.loadPreviewCss();
         },
 
-        // Style 設定があるか (PDF dispatch を server vs print dialog で切り替えるため)
-        hasStyle() {
-            return !!(normalizeUserPath(state.pdfStylePath) || normalizeUserPath(state.pdfOptionsPath));
+        // PDF dispatch 切替: PDF options JSON が指定されている時だけサーバー
+        // md-to-pdf を使う。CSS のみ (or 何もなし) の場合は印刷ダイアログ経由
+        // で OS のページ設定を活かしつつ、preview に当たっている CSS が
+        // そのまま print engine に渡って styled PDF が出る。
+        shouldUseServerPdf() {
+            return !!normalizeUserPath(state.pdfOptionsPath);
         },
 
         getExportOptions() {
@@ -317,7 +320,12 @@
 
             try {
                 const response = await fetch(`/raw/${state.pdfStylePath}`);
-                if (!response.ok) throw new Error('CSS file not found');
+                if (!response.ok) {
+                    if (response.status === 404) {
+                        throw new Error(`CSS not found: ${state.pdfStylePath}`);
+                    }
+                    throw new Error(`CSS load error (HTTP ${response.status}): ${state.pdfStylePath}`);
+                }
                 const cssText = await response.text();
                 const style = document.createElement('style');
                 style.id = this.scopedCssId;
@@ -327,8 +335,10 @@
                 setTimeout(() => { elements.statusText.textContent = 'Connected'; }, 1600);
             } catch (error) {
                 console.error('PDF style preview error:', error);
-                elements.statusText.textContent = 'PDF style failed';
-                setTimeout(() => { elements.statusText.textContent = 'Connected'; }, 2500);
+                // エラー詳細を status に出す (Claude Code 連携時の自己解決を助ける)
+                const detail = (error.message || 'unknown error').slice(0, 100);
+                elements.statusText.textContent = `Style failed: ${detail}`;
+                setTimeout(() => { elements.statusText.textContent = 'Connected'; }, 4500);
             }
         },
 
@@ -1714,10 +1724,10 @@
                 await this.exportPdf(tab.path);
             } else if (this.isHtmlPreview()) {
                 this.printHtmlPreview(tab.name);
-            } else if (tab.fileType === 'markdown' && PdfStyleManager.hasStyle()) {
-                // Style パネルで CSS / PDF options が設定されている場合のみ
-                // サーバー側 md-to-pdf で styled PDF を生成 (Watanabe 設計)。
-                // 設定がなければデフォルトの印刷ダイアログ経路に落とす。
+            } else if (tab.fileType === 'markdown' && PdfStyleManager.shouldUseServerPdf()) {
+                // PDF options JSON が指定されている時のみサーバー md-to-pdf。
+                // CSS だけ / 何もなしの場合は printDialog で OS にページ制御
+                // を委ね、preview の CSS injection が styled PDF を作る。
                 await this.exportPdf(tab.path);
             } else {
                 this.browserPrint(tab.name);
@@ -1772,10 +1782,13 @@
                 }, 2000);
             } catch (error) {
                 console.error('PDF export error:', error);
-                statusText.textContent = 'PDF export failed';
+                // サーバーが返したエラーメッセージを status に表示
+                // (Claude Code 連携などで「何が悪いか分からない」を防ぐ)
+                const detail = (error.message || 'unknown error').slice(0, 100);
+                statusText.textContent = `PDF export failed: ${detail}`;
                 setTimeout(() => {
                     statusText.textContent = originalStatus;
-                }, 3000);
+                }, 4500);
             }
         },
 

package/src/static/index.html

@@ -120,11 +120,11 @@
             <div class="pdf-style-panel hidden" id="pdfStylePanel">
                 <label>
                     <span>CSS</span>
-                    <input type="text" id="pdfStylePath" placeholder="src/styles/report.example.css">
+                    <input type="text" id="pdfStylePath" placeholder="report.css (rootDir からの相対パス)" title="rootDir 配下の .css ファイルパス。例: report.css または subdir/style.css">
                 </label>
                 <label>
                     <span>PDF options</span>
-                    <input type="text" id="pdfOptionsPath" placeholder="src/styles/report.pdf-options.example.json">
+                    <input type="text" id="pdfOptionsPath" placeholder="pdf-options.json (省略可。空なら印刷ダイアログ)" title="rootDir 配下の .json ファイルパス。指定すると md-to-pdf が margin/format を適用してサーバー PDF 自動 DL。空なら印刷ダイアログ経路。">
                 </label>
                 <button class="toolbar-btn" id="pdfStyleApply">Apply</button>
                 <button class="toolbar-btn" id="pdfStyleClear">Clear</button>

package/src/static/styles.css

@@ -808,7 +808,7 @@ body {
         padding: 0 !important;
     }
 
-    .sidebar, .resize-handle, .toolbar, .tab-bar { display: none !important; }
+    .sidebar, .resize-handle, .toolbar, .tab-bar, .pdf-style-panel { display: none !important; }
 
     body {
         height: auto !important;