--- name: dist-renderer-chunked-deps-deploy-protocol description: vite が dynamic-import で chunk file を /dist-renderer/assets/ に大量 emit する dependency (mermaid / wavedrom / katex 等) を入れた時、 .gitignore exception パターンが追いつかず chunk が CF Pages に届かず site blank-screen化する。 STEP 1146 emergency fix で確立した protocol metadata: node_type: memory type: feedback originSessionId: afeeb7e7-fd4f-40a6-92be-a8a4a193cd0e --- ★ STEP 1146 (2026-05-15) emergency site outage を trigger に確立した永続原則. ## Rule **vite が dynamic-import で chunk file を emit する new dependency (mermaid / wavedrom / katex / qiskit / pyodide-local 等) を入れた時、 `.gitignore` の `dist-renderer/assets/` exception を一緒に拡張し、 dev:build 後の **全 chunk file** が commit されているか必ず verify する**. **Why**: STEP 1146 で観測した failure mode: STEP 1143 で `npm install mermaid wavedrom` 後、 vite が `mermaid.core-*.js` / `katex-*.js` / `wavedrom-*.js` / `rough.esm-*.js` / `chunk-*-*.js` 等を `/dist-renderer/assets/` に emit. 但し `.gitignore` で ``` dist-renderer/assets/* !dist-renderer/assets/app-*.js !dist-renderer/assets/app-*.css !dist-renderer/assets/KaTeX_*.woff ``` のみ exception されていたため、 これらの chunk が untracked → CF Pages 未 deploy → fetch で SPA index.html (1896 bytes) を返却 → `import { c as e } from './katex-*.js'` 等が HTML を parse しようとして JS runtime error → **真っ白画面**. site は HTTP 200 を返す (index.html 配信は OK) ため、 curl で root のみ確認すると問題が見えない. **chunk file の content size verify が必須**. **How to apply**: ### 新 dependency 追加時 protocol 1. `npm install ` で package 追加 2. `npm run dev:build` で vite 実行 3. `ls dist-renderer/assets/ | wc -l` で **local chunk file count** を記録 4. `git ls-files dist-renderer/assets/ | wc -l` で **git tracked count** を確認 5. **差分 > 1 (app-*.js 以外に新 chunk あり)** の場合: - `.gitignore` の `dist-renderer/assets/` exception を更新 (新 dep の chunk pattern を `!` 追加) - または **全 .js / .css / .woff / .woff2 / .ttf / .svg を generic に exception** (STEP 1146 で採用した path) 6. `git add dist-renderer/assets/` で 全 chunk stage 7. commit + push 8. **CF Pages deploy 反映後**, `curl chunk URL` で content size 確認 (≥10000 bytes = 真の JS, ≈1896 bytes = HTML fallback failure) ### Verify command ```bash # 真の deploy success の signature curl -sSL "https://rei-aios.pages.dev/assets/.js" | head -c 200 # → "const __vite__mapDeps=…" や "import…" で始まれば OK # → "" で始まれば FAILURE (SPA fallback, chunk が deploy されていない) ``` ### chunk-file size による detection | File size | 状態 | |---|---| | ~1896 bytes | ❌ SPA fallback HTML (index.html サイズ) = chunk 未 deploy | | ~10 KB – 数 MB | ✅ 真の chunk (mermaid.core / katex 等は数百 KB) | ## STEP 1146 で採用した修正 ```diff - dist-renderer/assets/* - !dist-renderer/assets/app-*.js - !dist-renderer/assets/app-*.css - !dist-renderer/assets/KaTeX_*.woff - !dist-renderer/assets/KaTeX_*.woff2 - !dist-renderer/assets/KaTeX_*.ttf + dist-renderer/assets/* + !dist-renderer/assets/*.js + !dist-renderer/assets/*.css + !dist-renderer/assets/*.woff + !dist-renderer/assets/*.woff2 + !dist-renderer/assets/*.ttf + !dist-renderer/assets/*.svg dist-renderer/*.zip ``` = 個別 chunk pattern を列挙する代わりに **拡張子ベース** で generic に exception. 新 dependency 追加時に再 update 不要 (release .zip は依然 block). ## Anti-pattern: 「pre-commit hook で chunk file 重複防止」 過剰最適化 **reject 候補**: pre-commit hook で chunk file の入れ替わりを stage しないように block する案. 理由: - chunk file 名は vite content hash で変化する (mermaid.core-CQXhb0nZ.js → 次 build で mermaid.core-XYZABC.js) - 旧 chunk file を block すると新 chunk が deploy されない - = STEP 1146 と同 outage を生む 正しい protocol: **新 chunk 全部 commit + 古い chunk も commit (garbage collection は別 hooks)** ## 関連 memory - [[feedback_dist_renderer_index_html_deploy_protocol]] (STEP 1072 確立, root URL は dist-renderer/index.html serve) - [[feedback_site_coverage_map_protocol]] (STEP 1055 確立, SITE_COVERAGE_MAP audit) - [[feedback_site_activity_log_protocol]] (STEP 1056 確立, activity-log fetch) - [[project_2026-05-15_step1142_1143_hodge_correction_diagram_tools]] (STEP 1143 で mermaid + wavedrom 導入 = outage trigger) - [[project_hardware_gallery_theory_to_circuit_scaffold_2026-05-15]] (STEP 1138 起源) ## 検証 protocol additions to dev:build chain 将来 dev:build 後 `scripts/verify-chunk-deploy.sh` 等で ```bash git status --short dist-renderer/assets/ | grep -E "^?? " && echo "WARN untracked chunks" ``` = untracked chunk file を post-build で警告する helper 候補 (STEP 1146+α retain).