トラブルシューティング

まずログを見ます

claude --debug-file ~/mod-debug.log

画面の描画が拒否されると、ログに次のような行が残ります。原因はかっこの中にそのまま書かれています。

ui.render (Pane): a hook returned a tree that does not validate (…); drawing the engine's own

ホットリロード中のセッションでは、同じ内容が会話画面にも薄い 1 行で表示されます。

よくある落とし穴

症状	原因	解決
修正したのに画面が変わらない	/reload-skills は Mod を再読み込みしない	/reload-plugins
ペインが空、または止まったように見える	描画ツリーが検証に失敗し、エンジンがペインを拒否した	デバッグログの does not validate の理由を直す
Image が拒否される	source.generation に小数（ファイルの更新時刻など）を入れた	整数にする（Math.floor）
Image が拒否される	source.png のバイト列に PNG シグネチャ・IHDR がない	渡す前にヘッダーを検査する
検証が $ is passed to ... imported from と出す	別ファイルの関数に $ を渡した	$ を使うコードは 1 ファイルにまとめ、純粋関数だけを分離する
検証が registered twice without a matcher と出す	session.start などのイベントを 2 回登録した	1 つのフックから複数の処理を呼ぶ
$.process.run で呼んだスクリプトが出力なしで終わる	リンクされたフォルダでは argv[1] と import.meta.url が異なり、「直接実行」の判定が偽になる	両方を realpath で解決して比較する
描画中に呼んだプロセスの出力が途切れる	描画がやり直されて、実行中の処理が中断される	時間のかかる処理は $.clock.after で描画の外に出す
セッションを開き直したら、修正した Mod が反映されない	セッション ID が変わり、開発用の Mod フォルダも変わる	固定フォルダ + --plugin-dir、またはローカルマーケットプレイス
デスクトップアプリで Svg が表示されない	131,072 文字の制限を超えた	繰り返される属性をスタイルにまとめるか、画像を小さくする

画像が表示されません

• Image は、kitty グラフィックスプロトコルを使うターミナル（kitty、Ghostty、Ghostty ベースのターミナル）でのみ描画されます。macOS 標準のターミナルや iTerm2 では、alt の文字だけが表示されます。
• デスクトップアプリには Image がないので、Svg を使います。

テストでよくつまずく点

• テストキットは、相対パスを Mod フォルダ基準で解決します。偽のファイルシステムは絶対パスで作ってください。
• $ 呼び出しイベント（fs.read など）の偽の応答は { value: … } で包みます。tool.call は { result: … } です。
• テストキットは、ペインにスクロールやキーイベントを送れません。スクロールの動作は実際の画面で確認してください。