mdv-live 0.5.4 → 0.5.8

package/CHANGELOG.md

@@ -5,6 +5,133 @@ 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.8] - 2026-05-08
+
+### Fixed
+
+- **Symlink TOCTOU on note auto-save** (codex-loop で 4 round 連鎖修正):
+  - 旧コードの TOCTOU guard が `earlyDeck.realPath` (lock 取得前) と比較
+    していた → 進入後 swap、戻し、書き込みで別ファイル読み出しが original
+    path に書ける race を塞ぐため `deck.realPath` (in-lock) と比較に修正
+  - in-lock で realpath が変わったら mutex 範囲外の書込みになる →
+    detection を入れて再 lock 取得
+  - 再 lock 取得を server-side 自動 retry で実装 (client は STALE 以外を
+    terminal 扱いするため)
+  - retarget retry の入れ子 lock が opposite retarget で deadlock し得る
+    → trampoline で **outer lock 解放後に新 realpath を取得**
+
+### Added
+
+- TOCTOU 正常系の API regression test
+- SaveQueue coalesce/serialize/dropPath/例外耐性 5 件
+- Sec-Fetch-Site=same-origin の B 受理パス + cross-site 拒否
+
+### Architecture (refactor)
+
+- `src/api/marpNote.js` orchestration を 38 行に。実装は `src/api/marpNote/`
+  配下の `guards.js` / `readDeck.js` / `handleGet.js` / `handlePut.js` に分割
+- `src/static/lib/saveQueue.js` (per-deck queue + per-slide coalesce、純 JS)
+- `src/static/lib/tabRegistry.js` (tab close hook → メモリリーク解消)
+- `src/static/lib/apiClient.js` を deck/file/tree/info/pdf 用に拡張、
+  app.js の fetch 直叩きを 13 → 2 (WebSocket / /raw/ のみ残存)
+- `src/concurrency/pathLock.js`: promise-chain ベースの正しい mutex
+  (旧 naive Map 実装の thundering-herd race を排除)
+- `src/utils/errors.js`: mkError + ERROR_STATUS テーブル + sendError SSOT
+- `src/utils/etag.js`: ETag 計算 SSOT
+- placeholder を CSS pseudo-element 化 (`:empty::before`) で
+  contenteditable に placeholder text が混入する罠を構造的に解消
+- STALE 通知時に編集テキストを localStorage に自動退避
+
+### Tests
+
+- 222 → **236 件 (+14)**、全 PASS
+
+## [0.5.7] - 2026-05-08
+
+### Added
+
+- **Presenter View** (Marp スピーカーノート別ウィンドウ表示・編集)
+  - P キー (Cmd/Ctrl 修飾なし) または Marp ナビボタンで起動
+  - Current / Next スライド + Speaker Notes + 経過タイマーを並列表示
+  - パネルサイズはドラッグハンドルで変更可能 (localStorage 永続化)
+  - BroadcastChannel `mdv-marp-presenter` でメイン⇄presenter 双方向同期
+- **スピーカーノートの自動保存**: presenter ノートパネルをクリック→編集→
+  800ms デバウンスでサーバへ PUT。ソース markdown の HTML コメントを書き換え
+- **`/api/marp/decks/:path` エンドポイント** (GET/PUT/OPTIONS)
+  - **ETag 楽観ロック** (`sha256:`) で外部編集との衝突検出
+  - **per-path 非同期 mutex** で同時 PUT を直列化
+  - **Multi-note Guard**: 1 slide に複数ノートがある場合は read-only
+  - **CSRF**: Origin + Sec-Fetch-Site + Content-Type 厳密検証
+  - **PNA preflight 拒否** (localhost 同一オリジン要求)
+  - **128KB body limit + 専用 413 ハンドラ** で情報漏洩防止
+
+### Architecture
+
+- Marp スライド範囲・ノート位置の特定を **Marpit token** に委譲する
+  `marpitAdapter` を新設。regex 再実装の脆弱性を構造的に解消
+- `validatePathReal` + `O_NOFOLLOW` + realpath 二重解決で symlink swap
+  best-effort 防御
+- `atomicWrite` で `O_EXCL` temp + chmod EPERM 限定 + EXDEV 二段 rename +
+  uid+mtime sweep
+- BOM/CRLF/CR/UTF-8 surrogate pair 安全な行↔バイト変換ヘルパに集約
+- 共通 error コード/HTTP status マッピングを `utils/errors.js` に SSOT 化
+- promise-chain ベースの正しい mutex (`concurrency/pathLock.js`) で
+  thundering-herd race を排除
+- HTTP client / BroadcastChannel 名 / message schema を専用ライブラリに分離
+- セキュリティ脆弱性 5 件 (basic-ftp / ip-address / postcss) を `npm audit fix`
+
+### Tests
+
+- 既存 119 → **228 件 (+109)** すべて PASS
+- 性能: 500 slides / 155 KiB ファイルで parseDeck+rewrite 86ms
+
+## [0.5.6] - 2026-04-27
+
+### Added
+
+- Markdown PDF変換用の `mdv convert` サブコマンドを追加
+- `-s <css-file>` によるPDF変換用CSS指定を追加
+- `--pdf-options <json-file>` によるPuppeteer PDF options指定を追加
+- Web UIのStyleパネルを追加
+  - CSSファイルパスを指定可能
+  - PDF options JSONファイルパスを指定可能
+  - 指定CSSをMarkdownプレビューに反映
+  - `Clear` でスタイル指定を解除可能
+- 通常MarkdownのWeb UI PDF exportを `md-to-pdf` に対応
+- PDFスタイル指定のサンプルを追加
+  - `src/styles/report.example.css`
+  - `src/styles/report.pdf-options.example.json`
+
+### Changed
+
+- PDF出力設定をCSSとPDF options JSONに分離
+- Marp PDF出力は従来どおりMarp CLIを使用し、通常Markdown PDF出力のみ `md-to-pdf` を使用
+
+## [0.5.5] - 2026-04-05
+
+### Fixed
+
+- タスクリストのインライン要素（太字・リンク・コード）が二重表示されるバグを修正
+  - markdown-it-task-lists の labelAfter オプション誤用が原因
+- Mermaidプレースホルダがユーザーコンテンツと衝突する問題を修正（nonce付与）
+- 空frontmatter（`---\n\n---`）で空のyamlコードブロックが生成される問題を修正
+
+### Removed
+
+- 未使用の `src/rendering/slides.js` を削除（marp.jsに統合済み）
+
+### Added
+
+- WebSocketテスト7件（接続追跡・watch・broadcast・通知・cleanup・不正入力耐性）
+- レンダリングテスト10件（strikethrough・CJK emphasis・linkify・breaks・mermaid edge cases）
+- テスト総数: 92 → 109
+
+## [0.5.4] - 2026-04-04
+
+### Fixed
+
+- 4件の依存関係脆弱性を修正
+
 ## [0.5.3] - 2026-03-29
 
 ### Fixed

package/README.md

@@ -10,16 +10,18 @@
 - 📁 左側にフォルダツリー表示（遅延読み込み対応）
 - 📄 Markdownをリアルタイムレンダリング
 - 🎬 **Marp完全対応**（公式テーマ・ディレクティブ・数式）
+- 🎤 **Presenter View**（スピーカーノート別ウィンドウ・自動保存・タイマー） — `P` キーで起動
 - 🔄 ファイル更新時に自動リロード（WebSocket）
 - 🎨 シンタックスハイライト（highlight.js）
 - 📊 Mermaid図のレンダリング
 - 🌙 ダーク/ライトテーマ切り替え
 - ✏️ インラインエディタ（Cmd+E）
 - ✅ タスクリスト（チェックボックス）対応
-- 📥 PDF出力（Cmd+P）
+- 📥 PDF出力（Cmd+P / CLI convert）
+- 🎛️ PDF用CSS・PDF options指定（CLI / Web UI）
 - 🎬 動画/音声ストリーミング再生（Range Request対応）
 - 📤 ファイルアップロード（ドラッグ&ドロップ）
-- 🔒 セキュリティ強化（パストラバーサル防止）
+- 🔒 セキュリティ強化（パストラバーサル防止 + ETag 楽観ロック + CSRF 防御）
 
 ## Installation
 
@@ -59,13 +61,59 @@ mdv -k 12345
 mdv -k -a
 
 # PDFに変換
-mdv --pdf slide.md
-mdv --pdf slide.md -o output.pdf
+mdv convert -i report.md -o report.pdf
+
+# PDFに変換（CSSとPDF optionsを指定）
+mdv convert \
+  -i report.md \
+  -o report.pdf \
+  -s ./src/styles/report.example.css \
+  --pdf-options ./src/styles/report.pdf-options.example.json
 
 # バージョン表示
 mdv -v
 ```
 
+## PDF Export
+
+Markdown ファイルは CLI または Web UI から PDF に変換できます。
+
+### CLI
+
+```bash
+mdv convert -i input.md -o output.pdf
+```
+
+CSS を指定する場合は `-s` に CSS ファイルパスを渡します。
+
+```bash
+mdv convert \
+  -i input.md \
+  -o output.pdf \
+  -s ./src/styles/report.example.css
+```
+
+`printBackground` や余白などの PDF 生成オプションは、CSS と分離して JSON ファイルで指定できます。
+
+```bash
+mdv convert \
+  -i input.md \
+  -o output.pdf \
+  -s ./src/styles/report.example.css \
+  --pdf-options ./src/styles/report.pdf-options.example.json
+```
+
+`src/styles/report.example.css` と `src/styles/report.pdf-options.example.json` はサンプルです。必要に応じて任意の CSS / JSON ファイルを指定してください。
+
+### Web UI
+
+ビューア上部の `Style` から以下を指定できます。
+
+- CSS ファイルパス
+- PDF options JSON ファイルパス
+
+CSS は Markdown プレビューにも反映されます。指定を解除する場合は `Clear` を押してください。
+
 ### ポート自動増分
 
 ポートが使用中の場合、自動的に次のポート番号を試します。
@@ -118,6 +166,8 @@ paginate: true
 
 内容...
 
+<!-- スピーカーノート (Presenter View で表示・編集できます) -->
+
 ---
 
 # 次のスライド
@@ -129,9 +179,55 @@ paginate: true
 ### サポートされるMarp機能
 
 - **テーマ**: default, gaia, uncover
-- **ディレクティブ**: paginate, header, footer, backgroundColor, etc.
+- **ディレクティブ**: paginate, header, footer, backgroundColor, lang, headingDivider, etc.
+- **headingDivider**: scalar (`headingDivider: 2`) / inline-array (`[1, 2]`) / block-array 全形式
+- **スライド区切り**: `---` / `***` / `___` (CommonMark thematic break 全形式)
 - **画像構文**: `![bg]`, `![w:100px]`, `![bg left]`
 - **数式**: KaTeX対応（インライン `$...$`、ブロック `$$...$$`）
+- **スピーカーノート**: HTML コメント (`<!-- ... -->`) で記述
+
+## Presenter View
+
+Marp ファイルを開いた状態で **`P` キー** を押すと、別ウィンドウで登壇者ビューが起動します。
+
+### 機能
+
+- **3 ペインレイアウト**: 現在のスライド (大) / 次のスライド (小) / スピーカーノート
+- **経過タイマー**: 上部に MM:SS 表示、Reset ボタンで 0 にリセット
+- **ノート編集 → 自動保存**: ノートパネルをクリックして編集 → 800ms デバウンスで markdown ソースのコメントを書き戻し
+- **キーボードナビ**: ← / → でスライド移動、メイン画面と双方向同期
+- **レイアウト調整**: ペイン境界をドラッグで自由に変更、ダブルクリックでデフォルト復元 (localStorage 永続化)
+- **Multi-note Guard**: 1 スライドに複数のノートコメントがある場合は自動保存を無効化（先頭ノート消失防止）
+- **STALE 検出**: 外部エディタによる変更を ETag 楽観ロックで検出、編集中テキストを localStorage に自動退避
+
+### スピーカーノートの書き方
+
+```markdown
+# スライドタイトル
+
+スライドの本文
+
+<!-- ここがスピーカーノート。Presenter View で編集すると
+     このコメントが書き換わります。 -->
+```
+
+複数行のノートも OK:
+
+```markdown
+<!--
+- ポイント 1: 〜を強調する
+- ポイント 2: ここで質問を投げかける
+- 想定時間: 2 分
+-->
+```
+
+### Presenter View ショートカット
+
+| キー | 動作 |
+|---|---|
+| `← / →` | スライド移動 |
+| `Space / PageDown` | 次のスライド |
+| `Home / End` | 最初 / 最後のスライド |
 
 ## Keyboard Shortcuts
 
@@ -143,6 +239,10 @@ paginate: true
 | Cmd/Ctrl + P | PDF出力 |
 | Cmd/Ctrl + W | タブを閉じる |
 | ← / → | スライド移動（Marp時） |
+| F | フルスクリーン切替（Marp時） |
+| N | ナビバー表示切替（Marp時） |
+| **P** | **Presenter View 起動（Marp時）** |
+| Esc | フルスクリーン解除 |
 | F2 | ファイル名変更 |
 | Delete | ファイル削除 |
 
@@ -150,7 +250,7 @@ paginate: true
 
 | Endpoint | Method | Description |
 |----------|--------|-------------|
-| `/api/file` | GET | ファイル内容取得 |
+| `/api/file` | GET | ファイル内容取得 (Marp 時は etag/notes/notesMultiplicity も同梱) |
 | `/api/file` | POST | ファイル保存 |
 | `/api/file` | DELETE | ファイル/ディレクトリ削除 |
 | `/api/tree` | GET | ファイルツリー取得 |
@@ -159,7 +259,12 @@ paginate: true
 | `/api/move` | POST | ファイル移動/リネーム |
 | `/api/download` | GET | ファイルダウンロード |
 | `/api/upload` | POST | ファイルアップロード |
+| `/api/pdf/export` | POST | PDF出力 |
 | `/api/info` | GET | サーバー情報 |
+| `/api/marp/decks/:path` | GET | Marp デッキ情報取得 (etag, notes, notesMultiplicity) |
+| `/api/marp/decks/:path/slides/:N/note` | PUT | スピーカーノート更新 (`If-Match` 必須、ETag 楽観ロック) |
+
+`/api/marp/decks/*` は Origin / Sec-Fetch-Site / Content-Type を厳密に検証し、cross-origin / cross-site / non-JSON リクエストは `403 ORIGIN_REJECTED` または `415 UNSUPPORTED_MEDIA_TYPE` で拒否します（CSRF / DNS rebinding 防御）。
 
 ## Tech Stack
 
@@ -192,28 +297,54 @@ npm test
 
 ```
 mdv/
-├── bin/mdv.js           # CLI entry point
+├── bin/mdv.js                    # CLI entry point
 ├── src/
-│   ├── server.js        # Express server setup
-│   ├── watcher.js       # File watching (chokidar)
+│   ├── server.js                 # Express server setup
+│   ├── watcher.js                # File watching (chokidar)
+│   ├── websocket.js              # WebSocket setup
 │   ├── api/
-│   │   ├── file.js      # File operations API
-│   │   ├── tree.js      # File tree API
-│   │   └── upload.js    # Upload API
+│   │   ├── file.js               # File operations API
+│   │   ├── pdf.js                # PDF export API
+│   │   ├── tree.js               # File tree API
+│   │   ├── upload.js             # Upload API
+│   │   ├── marpNote.js           # Marp note autosave routes (orchestration)
+│   │   └── marpNote/
+│   │       ├── guards.js         # Origin / Host / Content-Type / If-Match guards
+│   │       ├── readDeck.js       # Path-safe deck reader (O_NOFOLLOW + realpath)
+│   │       ├── handleGet.js      # GET /api/marp/decks/:path
+│   │       └── handlePut.js      # PUT /api/marp/decks/:path/slides/:N/note
 │   ├── rendering/
-│   │   ├── index.js     # Rendering entry
-│   │   ├── markdown.js  # Markdown rendering
-│   │   └── marp.js      # Marp rendering
+│   │   ├── index.js              # Rendering entry
+│   │   ├── markdown.js           # Markdown rendering
+│   │   ├── marp.js               # Marp rendering (delegates to adapter)
+│   │   ├── marpitAdapter.js      # Marpit token adapter (SSOT)
+│   │   └── marpNoteWriter.js     # Pure-function note splice
+│   ├── concurrency/
+│   │   └── pathLock.js           # Promise-chain mutex (per-path serialization)
 │   ├── utils/
-│   │   ├── fileTypes.js # File type detection
-│   │   └── path.js      # Path security utilities
-│   └── static/          # Frontend files
-│       ├── index.html
-│       ├── app.js
-│       └── styles.css
+│   │   ├── errors.js             # Error codes / status mapping (SSOT)
+│   │   ├── etag.js               # sha256 ETag (SSOT)
+│   │   ├── lineMath.js           # BOM / CRLF / line ↔ byte conversion
+│   │   ├── atomicWrite.js        # Atomic file write (O_EXCL + EXDEV fallback)
+│   │   ├── fileTypes.js          # File type detection
+│   │   └── path.js               # Path security (validatePath / validatePathReal)
+│   ├── static/                   # Frontend files
+│   │   ├── index.html
+│   │   ├── app.js
+│   │   ├── presenter.html        # Presenter View (3-pane + autosave)
+│   │   ├── styles.css
+│   │   └── lib/
+│   │       ├── apiClient.js      # HTTP client wrapper
+│   │       ├── presenterChannel.js # BroadcastChannel SSOT
+│   │       ├── saveQueue.js      # Per-deck save queue + per-slide coalesce
+│   │       └── tabRegistry.js    # Tab life-cycle hooks
+│   └── styles/
+│       ├── index.js
+│       ├── report.example.css
+│       └── report.pdf-options.example.json
 ├── scripts/
-│   └── setup-macos-app.sh  # macOS app setup
-└── tests/               # Test files
+│   └── setup-macos-app.sh        # macOS app setup
+└── tests/                        # Test files (236 件、全 PASS)
 ```
 
 ## Requirements