export-download-debugging

エクスポートのダウンロードに関するデバッグ

エクスポートまたはダウンロードが実行されたように見えるものの、空、欠落、または使用できないファイルが生成される場合に使用してください。ブラウザーのプレビュー、iframe のキャプチャ、Electron のシェル向けに調整されています。

基本ルール

キャプチャと保存を切り分けてください。保存先のパスをデバッグする前に、エクスポートのペイロードに 0 バイトを超えるデータが含まれていることを確認してください。0 KB のファイルは、ネイティブのピッカーまたはホストが保存先ファイルを作成した後、書き込みに失敗したか、ブロックされたことを示す場合がよくあります。

確認すべき情報

• ペイロードの型、MIME タイプ、バイト長、オブジェクト URL またはデータ URL のパス、スローされたエラーの名前とメッセージを記録します。
• showSaveFilePicker、createWritable、<a download>、URL.createObjectURL、URL の無効化に関するブラウザーコンソールの出力とアプリのログを確認します。
• Electron では、will-download のパスを調べます。ファイル名、MIME、ファイル拡張子、保存ダイアログのフィルター、キャンセルの有無、最終的なファイルサイズを確認します。
• 実際にダウンロードされたファイルのディスク上のサイズと、通常の画像ビューアーで開けるかどうかを確認します。

修正の順序

1. まずエクスポートのペイロードを準備して検証し、バイトデータが利用可能になるまで保存を無効にします。
2. ホストにとって最もシンプルで安定した保存方法を優先します。showSaveFilePicker().createWritable() が失敗する、サンドボックスによって制限される、または空のファイルを作成する場合は、<a download> または Electron のダウンロードマネージャーを使用します。
3. ペイロードの準備ができる前にネイティブのピッカーを開かないでください。これにより、後続の書き込みに失敗したときにホストが空の保存先ファイルを作成するのを防げます。
4. PNG のフォールバックでは、Blob URL、無効化のタイミング、CSP、iframe のサンドボックス設定に問題が疑われる場合、検証済みで空ではないデータ URL を優先します。
5. Electron では、エクスポートされる画像の拡張子（.png、.jpg、.jpeg、.webp）に対する「名前を付けて保存」のフィルターを明示的に追加し、ユーザーが実際の画像ファイルの保存先を選べるようにします。
6. UI は簡潔に保ちます。形式の選択、ファイル名またはパスのヒント、明確な処理中およびエラー状態、主要な保存アクションを 1 つ用意します。

検証

• ペイロードが空でないことの準備、フォールバック時の保存動作、ファイル拡張子と MIME の対応、UI の無効状態とエラー状態に関するテストを追加または更新します。
• エクスポートに関する対象を絞ったテストを実行し、その後 pnpm --filter @open-design/web typecheck を実行します。
• Electron のダウンロード処理を変更した場合は、pnpm --filter @open-design/desktop typecheck も実行します。
• 変更を取り込む前に pnpm guard を実行し、ステージされた差分に無関係なファイル、生成された成果物、誤って含めたシークレットがないことを確認します。その後、修正をレビュー用に準備している場合は、リポジトリの PR 品質ゲートのワークフローを使用します。