@kubohiroya/turbowarp-extension-security-dialog 0.2.0 → 0.3.1

package/NOTICE.md

@@ -32,3 +32,9 @@ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 `assets/screenshots/required-modes-{en,ja}-20261025.png` are unmodified browser captures of the public Editor on 25 October 2026, showing Camera Source 0.19.3, Asset Cache 0.3.1 and Bubble 0.13.4. Their origin, Editor revisions and hashes are recorded in `assets/screenshots/capture-20261025.json`. The captured UI, icons and banners retain their respective rights holders and applicable licenses; this package does not relicense those elements.
 
 `assets/screenshots/localized-descriptions-{en,ja}-20261025.png` are unmodified captures of the updated public Editor on 25 October 2026, showing localized descriptions for Camera Source 0.19.4, Asset Cache 0.3.2 and Bubble 0.13.5. Their origin, revisions and hashes are recorded in `assets/screenshots/localized-descriptions-20261025.json`. The captured UI, icons and banners retain their respective rights holders and applicable licenses.
+
+`assets/screenshots/required-approval-{en,ja}-20261028.png` are unmodified captures of the public Editor on 28 October 2026 after the required-mode approval update, showing Camera Source 0.19.4, Asset Cache 0.3.2 and Bubble 0.13.5 with Deny and With sandbox disabled. Their origin, verified distribution hashes, Editor revisions and image hashes are recorded in `assets/screenshots/required-approval-20261028.json`. The captured UI, icons and banners retain their respective rights holders and applicable licenses.
+
+`assets/screenshots/preselected-required-{en,ja}-20261028.png` are unmodified captures of the public Editor on 28 October 2026 after automatic preselection was added when all listed extensions require unsandboxed execution. Camera Source 0.19.4, Asset Cache 0.3.2 and Bubble 0.13.5 have Without sandbox preselected and still require OK before execution. Origin, verified distribution hashes, Editor revisions and image hashes are recorded in `assets/screenshots/preselected-required-20261028.json`. The captured UI, icons and banners retain their respective rights holders and applicable licenses.
+
+`assets/screenshots/hidden-bulk-required-{en,ja}-20261028.png` are unmodified captures of the public Editor on 28 October 2026 with Without sandbox preselected for all three required extensions and the redundant bulk selection section hidden. Camera Source 0.19.4, Asset Cache 0.3.2 and Bubble 0.13.5 still require OK before execution. Origin, verified distribution hashes, Editor revisions and image hashes are recorded in `assets/screenshots/hidden-bulk-required-20261028.json`. The captured UI, icons and banners retain their respective rights holders and applicable licenses.

package/README.ja.md

@@ -5,17 +5,111 @@
 TurboWarpの複数の機能拡張を、1つの一覧で確認するための共通パッケージです。
 関連タスクと受け入れ基準は [scratch-gui #33](https://github.com/kubohiroya/scratch-gui/issues/33) に記録しています。
 
+## Pagesのカタログから機能拡張を選択する
+
+`ExtensionSelectionList` は既存のバナー・メタデータを共有し、各行の右端へチェックボックスを1つ表示します。
+TurboWarp Plus一覧の対応範囲は [#28](https://github.com/kubohiroya/turbowarp-extension-security-dialog/issues/28) に記録しています。
+ホスト側でGitHub PagesのJSONをHTTPS取得し、このコンポーネントへ渡します。
+
+```jsx
+import {loadExtensionCatalog} from '@kubohiroya/turbowarp-extension-security-dialog';
+import {ExtensionSelectionList} from '@kubohiroya/turbowarp-extension-security-dialog/react';
+
+const controller = new AbortController();
+const entries = await loadExtensionCatalog(
+  'https://kubohiroya.github.io/turbowarp-plus-packages/extensions-v1.json',
+  controller.signal
+);
+
+const list = <ExtensionSelectionList entries={entries} locale="ja"
+  filterQuery={searchText} loadedIds={loadedExtensionIds} busy={loading}
+  onCancel={closeLibrary}
+  onComplete={ordered => host.reviewAndLoadInOrder(ordered)} />;
+```
+
+例の `host.reviewAndLoadInOrder` はホスト側で実装する実行許可確認・VM読み込み処理です。
+`onComplete` は依存先を先に並べた重複のない配列を返し、`loadedIds` は除外します。
+ある拡張を選ぶと推移的な依存先すべてがchecked・disabledになります。
+親を解除すると依存関係を再計算し、ほかの選択やユーザー自身の明示選択が必要としている拡張は選択を保ちます。
+読み込み済みの行はchecked・disabledです。検索と表示言語を切り替えても選択を保ちます。
+`busy` で選択・フッター操作を無効にします。取得失敗・再試行・カタログの取得中止・VMエラーの表示と、
+読み込み成功に応じた `loadedIds` 更新はホスト側の担当です。
+
+各行は「手動で選択」（青）・「依存関係で自動選択」（紫）・「未選択」（中立色）を、背景・左枠・
+アイコン・状態名で区別します。「読み込み済み」も独立した表示です。一覧の上部には凡例を表示します。
+自動選択した行には「Bubble、Sprite に必要」のように、必要としている明示選択元すべてを表示します。
+手動で選んだ拡張がほかの選択元の依存先になった場合も、「手動で選択」を維持し、依存元を併記して
+チェックボックスを解除不可にします。DOMの `data-selection-state` は順に `selected` / `dependency` /
+`unselected` / `loaded` です。
+
+任意のカテゴリ定義がある場合、ダッシュボードと同じ順序でカテゴリ見出し（`h2`）を表示します。
+日本語は `titleJa` があれば使用し、なければ `title` にフォールバックします。
+検索で空になったカテゴリは非表示になりますが、選択状態は維持します。
+カテゴリのない旧JSONは従来の平坦な一覧です。カテゴリ付きと未指定の項目が混在する場合、未指定分は
+末尾の「その他の機能拡張」へ表示します。配色はホストのモーダル背景色・文字色に従います。
+強調色は `--twextsec-manual-accent` / `--twextsec-dependency-accent` /
+`--twextsec-unselected-accent` / `--twextsec-loaded-accent` で調整できます。
+
+一覧の表示・選択だけでは機能拡張のコードを読み込み・実行しません。
+JSONのメタデータを直ちに表示し、選択一覧には「詳細」やJS配布URLを表示しません。
+選択状態と依存元の説明はアイコン画像の下へ表示します。名前の行は「Bubble v0.15.1 (ID: kubohiroyabubble) GitHub/npmアイコン」の順で、名前に続く項目は通常の太さ・名前より2pt小さい書体です。狭い幅では必要に応じて折り返します。
+ドキュメントの `docsURL`（確認済みGitHub Pages）を表示し、GitHubのOctocat・npmのアイコンから
+`repository` と `package` のページを開きます。URLがない項目にリンクを推測して付けることはしません。
+製作者は `author` を表示し、公開版package.jsonの `author.url` を収録した `authorURL` があれば名前をリンクにします。
+各行には「サンドボックスなし：必要／任意／不要／未確認」を表示し、必要な場合は警告アイコンを付けます。
+実行許可確認には `ExtensionSecurityDialog context="catalog"` を使用でき、キャンセル文言が選択一覧へ戻る案内になります。
+既定の `context="project"` はプロジェクト読み込み用の文言を維持します。
+ホストは確定された実行モードと独自のセキュリティ方針を尊重して読み込んでください。
+
+共通化した画像・サービスリンク・実行条件には `entry.metadata` と取得したソースのメタデータを使用します。
+どちらか一方でも `unsandboxed: required` なら必要条件を維持し、バッジ・選択可能なモード・非対応選択の解除・
+一括初期選択で同じ判断をします。セキュリティ確認のOKは、従来どおりソースのメタデータ取得の成功／失敗が確定するまで待ちます。
+それ以外の表示は今回変更せず、セキュリティ確認はソースヘッダーのバージョン・リンクのない製作者名・出所URLを維持し、
+選択一覧はカタログのバージョン・明示された製作者リンク・ドキュメントURLを維持します。
+`entry.category` があれば両画面で同じ順序・日英見出しにし、カテゴリのないプロジェクトでは取得や推測をせず平坦な一覧を維持します。
+
+
+JSON契約は `schemaVersion: 1` と `extensions` 配列です。各要素の必須項目は次のとおりです。
+
+| 項目 | 内容 |
+| --- | --- |
+| `id` | ASCII英数字の機能拡張ID |
+| `name` | 表示名 |
+| `version` | 配布バージョン |
+| `url` | バージョン固定の公開済み機能拡張JSへのHTTPS URL |
+| `dependencies` | 同じJSONに含まれる依存先の機能拡張ID配列。npmパッケージ名ではない |
+
+`package`・`description`・`descriptions`（`ja`等の小文字言語タグをキーとする説明）・`author`・`license`・
+`banner`・`repository`・`docsURL`・`authorURL`・`unsandboxed`（例: `required`）は任意のメタデータです。
+完全なJSON例は[英語版のAPI例](README.md#selecting-extensions-from-a-pages-catalog)を参照してください。
+生成側でパッケージ依存を拡張IDへ変換し、ビルド専用パッケージを除外します。
+
+カテゴリはトップレベルの任意項目 `categories: [{id, title, titleJa?}]` としてダッシュボード順に定義し、
+各 `extensions[].category` にそのIDを指定します。カテゴリIDの重複・不正な定義・未定義IDの参照は拒否します。
+`parseExtensionCatalog` の返り値は従来どおり配列で、カテゴリ参照は各要素の
+`category: {id, title, titleJa?, order}` へ解決します。`order` は定義の配列順です。
+
+`parseExtensionCatalog` は未対応schema、ID/URL重複、存在しない依存先、循環依存、HTTPS以外や認証情報付きのURLを拒否します（製作者の `authorURL` だけはHTTPも許可します）。
+`resolveExtensionSelection(entries, explicitIds, loadedIds)` はReactなしでも同じ選択集合・依存順を計算します。
+返り値の `requiredBy` は依存先IDをキー、必要としている明示選択元IDの集合を値とするMapです。
+推移的依存・共有依存を含め、選択を解除すると依存元の集合も再計算します。
+`loadExtensionCatalog` は任意のAbortSignalを受け付け、認証情報・Refererを送らずに取得し、HTTP失敗や不正なJSON契約を例外として返します。
+
+切り戻しはホストの起動時固定・既定OFFのフラグをOFFにして再読み込みするか、カタログ接続差分をrevertします。
+既存の3つの実行モードを持つセキュリティ確認は、そのまま利用できます。
+
 ## 公開Editorのスクリーンショット
 
 [英語版](./README.md)と日本語版は、同じダイアログの表示言語を切り替え、ラベルと拡張の説明文を各言語で表示しています。
-2026年10月25日の[公開Editor](https://kubohiroya.github.io/turbowarp-extension-data-editor/editor.html?lang=ja)で、
-Camera Source 0.19.4・Asset Cache 0.3.2・Bubble 0.13.5を開いた実画面です。
+全件必須時の自動選択と一括選択欄の非表示に対応した[公開Editor](https://kubohiroya.github.io/turbowarp-extension-data-editor/editor.html?lang=ja)で、
+2026年10月28日にCamera Source 0.19.4・Asset Cache 0.3.2・Bubble 0.13.5を開いた実画面です。
 
-![Camera Source・Asset Cache・Bubbleの説明が日本語で表示された確認画面。サンドボックスありは非対応で無効、サンドボックスなしは動作に必要。サンドボックス内では動作しない理由を表示](https://raw.githubusercontent.com/kubohiroya/turbowarp-extension-security-dialog/main/assets/screenshots/localized-descriptions-ja-20261025.png)
+![Camera Source・Asset Cache・Bubbleの説明が日本語で表示された修正後の確認画面。拒否とサンドボックスありは無効、サンドボックスなしを選択済みで動作に必要と表示。一括選択欄は非表示。OKで読み込むかキャンセルで中止できる](https://raw.githubusercontent.com/kubohiroya/turbowarp-extension-security-dialog/main/assets/screenshots/hidden-bulk-required-ja-20261028.png)
 
-3拡張とも`Unsandboxed: required`を宣言しています。「サンドボックスあり」は無効化され、
-「この拡張はサンドボックス内では動作しません。」と理由が表示されます。
-「サンドボックスなし」には「動作に必要」と表示します。拒否は選択でき、実行には自分での選択とOKが必要です。
+3拡張とも`Unsandboxed: required`を宣言しています。「拒否」と「サンドボックスあり」は無効化され、
+理由が表示されます。「サンドボックスなし」だけが有効で、「動作に必要」と表示します。
+全拡張がこのモードを必要とする場合、全件のメタデータ取得後に選択済みになり、一括選択欄は非表示になります。
+「OK」で続行するか、「キャンセル」でプロジェクトの読み込みを中止します。
 必要なモードの表示は、安全性や配布元の信頼性の認定ではありません。
 
 | 機能拡張 | サンドボックスなしが必要な理由 |
@@ -25,7 +119,7 @@ Camera Source 0.19.4・Asset Cache 0.3.2・Bubble 0.13.5を開いた実画面で
 | Bubble | ホストの実行環境と描画機能へ直接アクセスして、ステージ上に重ねた吹き出しや立ち絵を描画・更新します。 |
 
 画像はダイアログ部分をブラウザーで直接撮影したもので、加工していません。
-取得元の版・Editor build・画像hashは[撮影台帳](./assets/screenshots/localized-descriptions-20261025.json)に記録しています。
+取得元の版・Editor build・画像hashは[撮影台帳](./assets/screenshots/hidden-bulk-required-20261028.json)に記録しています。
 
 ## 連動するパッケージ
 
@@ -79,35 +173,19 @@ flowchart TB
 1回のプロジェクト読み込みにつき1つのダイアログで、読み込み待ちの拡張URLをすべて並べます。
 各行には「拒否」「サンドボックスあり」「サンドボックスなし」の3択があり、一括選択は対応する
 拡張すべてに同じ選択を適用します。見出し・一括選択・OK/キャンセルは常に見えたままで、
-一覧だけがスクロールします。下図では列見出しを「あり」「なし」と省略していますが、
-実際は「サンドボックスあり」「サンドボックスなし」と表示します。
+一覧だけがスクロールします。
 
-```
-+--------------------------------------------------------------------------+
-| 機能拡張セキュリティ                                                     |
-| 実行方法を選んでください（取得中でも選択できます）                       |
-|                                             機能拡張の情報：2/3 件を確認 |
-|                                                                          |
-| 表示中のすべてに適用: [(x) 拒否] [(o) あり] [(!) なし]                   |
-| そのモードに対応する拡張だけに適用します。                               |
-| +----------------------------------------------------------------------+ |
-| | 機能拡張                |   (x) 拒否   |   (o) あり   |   (!) なし   | |  <- この領域だけが
-| +----------------------------------------------------------------------+ |     スクロールする
-| | [バナー] Fetch          |     ( )      |    非対応    |     (*)      | |
-| |   作者 ... | ID: fetch | ライセンス: MIT | 更新日時 ...              | |
-| |   (!) この拡張はサンドボックス内では動作しません。                   | |
-| |       サンドボックスなし: 動作に必要                        [ 詳細 ] | |
-| +----------------------------------------------------------------------+ |
-| | [バナー] Storage        |     (*)      |     ( )      |     ( )      | |
-| |   メタデータを取得中…                                       [ 詳細 ] | |
-| +----------------------------------------------------------------------+ |
-| メタデータは作者の自己申告です。                                         |
-| サンドボックスなしの拡張は、プロジェクトやブラウザーの                   |
-| 情報にアクセスできます。                                                 |
-| 拒否 1 · あり 0 · なし 1 · 未指定 1                                      |
-|                                             [ キャンセル ]    [  OK  ]   |
-+--------------------------------------------------------------------------+
-```
+セキュリティ確認と選択一覧は、内部のパッケージ説明コンポーネントとカテゴリ見出しの処理を共有します。
+画像を元の縦横比のまま切り取らずに表示し、GitHub／npmリンク・実行要件バッジ・渡されたカテゴリ見出しを共通化しています。
+両画面とも「詳細」ボタン・ソースコードの一覧内表示はありません。ラジオボタンとチェックボックスは説明の外側、
+選択状態バッジは共通コンポーネントのスロットに配置します。
+
+セキュリティ確認の上部には次の案内を1回表示し、その下にメタデータ取得状況を表示します。
+
+> ⚠️マークの表示されている拡張を制作者の意図どおりに動作させるためには『サンドボックスなし』を選択してください。
+
+`context="catalog"` の場合だけ、フッター内のボタンより上の独立した行に「『キャンセル』で選択一覧に戻ります。」と表示します。
+プロジェクト読み込みのキャンセル確認は従来の戻り先を維持し、この案内を表示しません。
 
 続いて、2種類の確認ダイアログが出ることがあります。
 
@@ -118,7 +196,7 @@ flowchart TB
   できない可能性があります。続行しますか？」「いいえ」なら一覧に戻り、何も保存しません。
 
 バナーはホバーまたはキーボードフォーカスで原寸プレビューを表示します。画面より大きい画像は
-プレビュー枠内をスクロールして確認できます。ソースコードを一覧内に表示するのは「詳細」だけです。
+プレビュー枠内をスクロールして確認できます。両画面のサムネイルは同じ方法で、画像を切り取らずに表示します。
 
 ```mermaid
 sequenceDiagram
@@ -135,7 +213,7 @@ sequenceDiagram
     A->>A: 保存済みの既定値を読み出す
     V->>A: 包まれた_loadExtensions
     A->>D: 読み込み待ちの全件と復元した選択
-    D-->>U: 1つの一覧、個別と一括の3択、詳細
+    D-->>U: 1つの一覧、個別と一括の3択
     D->>D: メタデータとバナーを非同期に取得
     U->>D: OK
     D-->>U: 拒否があるときだけ続行確認
@@ -161,9 +239,9 @@ sequenceDiagram
 
 ## 責務
 
-- 一覧比較UI、個別・一括の3択、確認ダイアログ、ソースの詳細表示
+- 一覧比較UI、個別・一括の3択、確認ダイアログ
 - コードを実行しないメタデータ取得、実バナー／GitHub画像の候補選択、共通バナーへの切替
-- 画像・メタデータの非同期更新と独立した選択・詳細の状態保持
+- 画像・メタデータの非同期更新と選択状態の保持
 - プロジェクト別のIndexedDB保存と初期選択の復元
 - `./turbowarp` に分離したVM互換アダプター
 
@@ -172,19 +250,20 @@ ReactとReact DOMは任意のpeer dependencyです。React UIの利用時は両
 coreとVMアダプターの利用にReact/React DOMは必要ありません。
 
 ダイアログ全体の高さをビューポート内に制限し、見出し・一括選択・OK/キャンセルを維持したまま、
-一覧（詳細と注意書きを含む）だけをスクロールします。短い画面高では余白を詰めます。
+一覧（注意書きを含む）だけをスクロールします。短い画面高では余白を詰めます。
 
 ## メタデータとプレビュー
 
-HTTP/HTTPSの出所URLは完全なURLを表示し、別タブで開きます。埋め込み拡張や他のスキームはリンクにしません。
+セキュリティ確認ではHTTP/HTTPSの出所URLを別行に完全なURLで表示し、別タブで開きます。
+埋め込み拡張や他のスキームはリンクにしません。選択一覧は従来どおりドキュメントURLを表示し、JS配布URLは表示しません。
 ソース先頭の宣言コメントに `// Updated: 2026-10-19T10:30:00+09:00` などの更新日時がある場合、
 記載値をそのまま表示します。`Updated at` / `Updated-at` / `UpdatedAt` / `Last updated` / `Last-updated` /
 `Last modified` / `Last-modified` も同じ項目です。カスタム `loadInfo` は `metadata.updatedAt` を返せます。
 記載がなければ日時は表示せず、HTTPの取得日時やファイル時刻で補いません。
 
 バナーはホバーまたはキーボードフォーカスで原寸プレビューを表示します。画面より大きい画像は
-プレビュー枠内をスクロールして確認できます。ポインターを外すかEscapeで閉じ、選択や詳細状態を保持します。
-メタデータの非同期取得中も実行方法を選べます。ソースの一覧内表示は引き続き「詳細」を押したときだけです。
+プレビュー枠内をスクロールして確認できます。ポインターを外すかEscapeで閉じ、選択状態を保持します。
+メタデータの非同期取得中も実行方法を選べます。取得処理は宣言コメントの確認に使用し、コードを実行しません。
 
 ### 機能拡張の説明文の言語
 
@@ -207,12 +286,15 @@ HTTP/HTTPSの出所URLは完全なURLを表示し、別タブで開きます。
 個別選択・一括選択・一覧の見出しは、禁止アイコンの「拒否」、盾の「サンドボックスあり」、
 警告の「サンドボックスなし」の順です。アイコンと色は文字ラベルを補助し、安全性の認定には使いません。
 
-先頭の宣言コメントに `// Unsandboxed: required` があれば、「サンドボックスあり」を無効化して
-動作しない理由を表示し、「サンドボックスなし」に「動作に必要」を付けます。拒否は選択できます。
+先頭の宣言コメントに `// Unsandboxed: required` があれば、「拒否」と「サンドボックスあり」を無効化して
+理由を表示し、選択できる唯一のモード「サンドボックスなし」に「動作に必要」を付けます。
+選択したモードを「OK」で承認するか、「キャンセル」でプロジェクトの読み込みを中止します。
 この宣言は作者の自己申告であり、未宣言・取得失敗から必須モードを推測しません。
 
-実行する選択の確定はメタデータ取得の完了または失敗後です。遅れて取得した宣言に対応しない選択は、
-保存済みの復元値も含めて解除し、選び直しを案内します。権限の広いモードへ自動で変更しません。
+「拒否」を含む選択の確定はメタデータ取得の完了または失敗後です。全拡張の取得が成功し、すべてが
+この必須モードを宣言していれば、非対応の保存済み選択も含めて「サンドボックスなし」を選択済みにします。
+「OK」を押すまで拡張は実行せず、「キャンセル」で中止できます。取得中・未宣言・任意指定・取得失敗が
+1件でもあれば、この一括初期選択は行いません。混在する一覧では、非対応の選択を解除して選び直しを案内します。
 一括選択は対応する拡張だけに適用し、全件が非対応の一括ボタンは無効化します。
 
 ## 接続例

package/README.md

@@ -12,14 +12,15 @@ Related tasks and acceptance criteria are tracked in
 [English](./README.md) and [Japanese](./README.ja.md) use the same dialog with localized labels and extension descriptions.
 This capture shows Camera Source 0.19.4, Asset Cache 0.3.2 and Bubble 0.13.5 in the
 [public Editor](https://kubohiroya.github.io/turbowarp-extension-data-editor/editor.html?lang=en)
-on 25 October 2026.
+on 28 October 2026, with **Without sandbox** already selected for all three extensions and the unnecessary bulk selection section hidden.
 
-![English descriptions for Camera Source, Asset Cache and Bubble: With sandbox is disabled as Unsupported for all three extensions; Without sandbox is marked Required to run, with the reason This extension cannot run inside the sandbox.](https://raw.githubusercontent.com/kubohiroya/turbowarp-extension-security-dialog/main/assets/screenshots/localized-descriptions-en-20261025.png)
+![English descriptions for Camera Source, Asset Cache and Bubble: Deny and With sandbox are disabled for all three extensions; Without sandbox is preselected and marked Required to run. The bulk selection section is hidden. Choose OK to load the project or Cancel to stop.](https://raw.githubusercontent.com/kubohiroya/turbowarp-extension-security-dialog/main/assets/screenshots/hidden-bulk-required-en-20261028.png)
 
-All three extensions declare `Unsandboxed: required`. **With sandbox** is disabled, with
-**This extension cannot run inside the sandbox.** shown as the reason. **Without sandbox**
-is marked **Required to run**. Deny remains available, and running still requires an explicit
-choice and OK. These labels describe execution requirements, not a safety certification.
+All three extensions declare `Unsandboxed: required`. **Deny** and **With sandbox** are
+disabled, with the reason shown. **Without sandbox** is enabled and marked **Required to run**.
+When every listed extension requires this mode, it is preselected after all metadata loads, and the bulk selection section is hidden.
+Press OK to continue, or **Cancel** to stop loading the project.
+These labels describe execution requirements, not a safety certification.
 
 | Extension | Why it needs to run without a sandbox |
 | --- | --- |
@@ -28,7 +29,7 @@ choice and OK. These labels describe execution requirements, not a safety certif
 | Bubble | Accesses the host runtime and renderer directly to draw and update layered speech bubbles and portraits on the stage. |
 
 The PNG is an unmodified, modal-only browser capture. Source versions, Editor build and image
-hashes are recorded in [the capture manifest](./assets/screenshots/localized-descriptions-20261025.json).
+hashes are recorded in [the capture manifest](./assets/screenshots/hidden-bulk-required-20261028.json).
 
 ## How it fits together
 
@@ -84,32 +85,17 @@ three choices — **Deny**, **With sandbox**, **Without sandbox** — and a bulk
 one choice to every listed extension that supports it. The heading, the bulk row and the
 OK/Cancel buttons stay visible; only the list scrolls, so the dialog always fits the viewport.
 
-```
-+--------------------------------------------------------------------+
-| Extension Security                                                 |
-| Choose how to run each extension (you can choose while metadata    |
-| loads).                                 Extension information: 2/3 |
-|                                                                    |
-| Apply to all listed: [(x) Deny] [(o) With sandbox] [(!) Without]   |
-| Applies only to extensions that support this mode.                 |
-| +----------------------------------------------------------------+ |
-| | Extension             |  (x) Deny |   (o) With  | (!) Without  | |  <- only this
-| +----------------------------------------------------------------+ |     area scrolls
-| | [banner] Fetch        |    ( )    | Unsupported |     (*)      | |
-| |   Author: ... | ID: fetch | License: MIT | Updated: ...        | |
-| |   (!) This extension cannot run inside the sandbox.            | |
-| |       Without sandbox: Required to run             [ Details ] | |
-| +----------------------------------------------------------------+ |
-| | [banner] Storage      |    (*)    |     ( )     |     ( )      | |
-| |   Getting metadata...                              [ Details ] | |
-| +----------------------------------------------------------------+ |
-| Metadata is provided by the author.                                |
-| Extensions without a sandbox can access your project and browser   |
-| information.                                                       |
-| Deny 1 · With 0 · Without 1 · Unselected 1                         |
-|                                      [ Cancel ]       [  OK  ]     |
-+--------------------------------------------------------------------+
-```
+The security dialog and selection list use the same internal package-description renderer
+and category-section helper. They share uncropped images at their original aspect ratio,
+GitHub/npm service links, execution-requirement badges and supplied category headings.
+Neither view includes a Details button or inline source code. Radio buttons and checkboxes
+remain outside the description; selection-state badges use a slot in the shared renderer.
+
+The security dialog explains the warning badge once above the list: “To make extensions
+marked ⚠️ work as their creators intended, choose Without sandbox.” Metadata progress
+appears below it. With `context="catalog"`, a separate footer row above the buttons says
+“Choose Cancel to return to the selection list.” Project context retains its own cancellation
+confirmation and does not show that destination.
 
 Two confirmation dialogs can follow:
 
@@ -120,8 +106,7 @@ Two confirmation dialogs can follow:
   when it runs. Continue?" Answering *No* returns to the list and saves nothing.
 
 Hovering or keyboard-focusing a banner opens a full-size preview; images larger than the
-screen scroll inside the preview frame. *Details* is the only thing that shows extension
-source code inline.
+screen scroll inside the preview frame. Thumbnails use the same uncropped display in both views.
 
 ```mermaid
 sequenceDiagram
@@ -138,7 +123,7 @@ sequenceDiagram
     A->>A: read saved per-project defaults
     V->>A: wrapped _loadExtensions with ids and urls
     A->>D: all pending entries plus restored choices
-    D-->>U: one list, per-row and bulk choices, Details
+    D-->>U: one list, per-row and bulk choices
     D->>D: metadata and banners arrive asynchronously
     U->>D: OK
     D-->>U: continue-with-denied confirmation, only if anything is denied
@@ -164,10 +149,10 @@ implementation. The author would be glad to see it made redundant by TurboWarp E
 
 ## Responsibilities
 
-- Comparison list UI, per-row and bulk three-way choice, confirmation dialogs, source detail view
+- Comparison list UI, per-row and bulk three-way choice, confirmation dialogs
 - Metadata retrieval that never executes extension code, candidate selection between the real
   banner and GitHub images, fallback to a common banner
-- Asynchronous image and metadata updates that keep selection and detail state independent
+- Asynchronous image and metadata updates that preserve selection
 - Per-project IndexedDB storage and restoration of initial choices
 - A VM compatibility adapter, isolated in `./turbowarp`
 
@@ -176,13 +161,14 @@ after a cancel. React and React DOM are optional peer dependencies; supply both
 the React UI. Neither is needed for the core or the VM adapter.
 
 The dialog's total height is constrained to the viewport. The heading, bulk choice and
-OK/Cancel stay in place while only the list — including details and notices — scrolls.
+OK/Cancel stay in place while only the list — including notices — scrolls.
 Spacing tightens on short viewports.
 
 ## Metadata and previews
 
-HTTP/HTTPS origin URLs are shown in full and open in a new tab. Embedded extensions and other
-schemes are not linked.
+The security dialog retains its HTTP/HTTPS source-origin URL as a separate provenance line,
+opening in a new tab. Embedded extensions and other schemes are not linked. The selection
+list keeps its documentation URL instead; it never displays the JavaScript distribution URL.
 
 If the leading declaration comment in the source carries an update timestamp such as
 `// Updated: 2026-10-19T10:30:00+09:00`, the written value is displayed verbatim.
@@ -222,15 +208,19 @@ Per-row choices, the bulk choices and the list heading are ordered: **Deny** (pr
 icon), **With sandbox** (shield), **Without sandbox** (warning). Icons and colour support the
 text labels; they are not a safety certification.
 
-If the leading declaration comment contains `// Unsandboxed: required`, *With sandbox* is
-disabled with the reason shown, and *Without sandbox* is marked *Required to run*. Deny stays
-selectable. This declaration is the author's own claim; a required mode is never inferred from
+If the leading declaration comment contains `// Unsandboxed: required`, *Deny* and *With sandbox*
+are disabled with the reason shown, and *Without sandbox* is the only available mode, marked
+*Required to run*. Press OK to approve the selected modes, or Cancel to stop loading
+the project. This declaration is the author's own claim; a required mode is never inferred from
 a missing declaration or a failed fetch.
 
-A choice to run is only committed once metadata has loaded or failed. A selection that
-contradicts a late-arriving declaration is cleared — including a restored saved value — and
-the user is asked to choose again. The mode is never silently widened. A bulk choice applies
-only to extensions that support it, and a bulk button is disabled when no listed extension does.
+A choice, including Deny, is only committed once metadata has loaded or failed. When every
+listed extension has loaded metadata declaring this requirement, *Without sandbox* is
+preselected for all entries, including entries with incompatible saved choices. Nothing runs
+until the user presses OK; Cancel still stops loading the project. Pending, missing, optional
+or failed declarations prevent this batch default. In mixed batches, incompatible choices
+are cleared and the user is asked to choose again. A bulk choice applies only to extensions
+that support it, and a bulk button is disabled when no listed extension does.
 
 ## Wiring it up
 
@@ -251,6 +241,124 @@ surfacing as a VM error is identified with `isExtensionSecurityCancelled(error)`
 Under Webpack 4 with CSS Modules, load `webpack4.css` instead of `styles.css`; root-level
 compatibility entries resolve for older Webpack 4 setups that do not read package exports.
 
+## Selecting extensions from a Pages catalog
+
+`ExtensionSelectionList` shares the security dialog's banners and metadata,
+with one checkbox at the right of each row. This API supports the TurboWarp Plus library
+tracked in [#28](https://github.com/kubohiroya/turbowarp-extension-security-dialog/issues/28).
+The host fetches a versioned JSON catalog over HTTPS:
+
+```jsx
+import {loadExtensionCatalog} from '@kubohiroya/turbowarp-extension-security-dialog';
+import {ExtensionSelectionList} from '@kubohiroya/turbowarp-extension-security-dialog/react';
+
+const controller = new AbortController();
+const entries = await loadExtensionCatalog(
+  'https://kubohiroya.github.io/turbowarp-plus-packages/extensions-v1.json',
+  controller.signal
+);
+
+const list = <ExtensionSelectionList entries={entries} locale="en"
+  filterQuery={searchText} loadedIds={loadedExtensionIds} busy={loading}
+  onCancel={closeLibrary}
+  onComplete={ordered => host.reviewAndLoadInOrder(ordered)} />;
+```
+
+`host.reviewAndLoadInOrder` represents the host's permission review and VM loading path.
+The callback receives dependencies before their dependants, each once, excluding
+`loadedIds`. Selecting an extension checks and disables all transitive dependencies.
+Removing its selection recomputes the closure; dependencies remain checked if another
+selection needs them or the user selected them explicitly. Loaded rows are checked and
+disabled. Search and locale changes preserve selection. `busy` disables selection and the
+footer controls. The host owns fetch errors, retry, catalog cancellation, VM errors, and
+updating `loadedIds` after each successful load.
+
+Rows distinguish **Selected by you** (blue), **Selected automatically** (purple), and
+**Not selected** (neutral), using a background, left border, icon and label together.
+Already loaded rows have their own label and accent. A legend explains the states above
+the list. Automatically selected dependencies name every selected root that needs them,
+for example “Required by Bubble, Sprite”. An explicitly selected dependency keeps its
+“Selected by you” state while another root requires it; its checkbox stays disabled and
+the dependency reason is also shown. The row's `data-selection-state` is `selected`,
+`dependency`, `unselected` or `loaded`.
+
+Optional catalog categories render as semantic `h2` sections in dashboard order. Japanese
+uses `titleJa` when available, otherwise `title`; other locales use `title`. Search hides
+empty sections without changing selection. Catalogs without categories
+keep a flat list. If categorized and uncategorized entries are mixed, the latter appear
+under “Other extensions” at the end. Theme colors use the host's modal background and
+foreground; accent overrides are `--twextsec-manual-accent`, `--twextsec-dependency-accent`,
+`--twextsec-unselected-accent`, and `--twextsec-loaded-accent`.
+
+Package selection states and dependency reasons appear below the preview image. The heading places the name, version, parenthesized ID and GitHub/npm icons in that order. Items after the name use regular weight and a font size 2pt smaller than the name, wrapping as needed.
+
+The selection list never loads or runs extension code. Catalog metadata renders immediately.
+It shows the verified GitHub Pages `docsURL`, and GitHub/ npm icon links to the repository
+and package page. Neither screen has a Details control or inline source; the JavaScript
+distribution URL remains confined to the security dialog’s provenance line.
+Creator names use `authorURL` only when explicitly supplied by the published package.json
+`author.url`. Every row discloses its unsandboxed requirement as required, optional, not needed
+or not confirmed; required mode includes a warning icon. `ExtensionSecurityDialog context="catalog"` provides permission review with cancel
+wording that returns to this list; its default `context="project"` retains project wording.
+The host must respect the committed execution modes and its own security policy.
+
+For shared images, service links and execution requirements, optional `entry.metadata`
+complements the fetched source metadata. If either declares `unsandboxed: required`, the
+shared badge, allowed choices, invalidation and batch defaults all honor that requirement.
+Security still waits for source metadata to settle (success or failure) before accepting OK;
+fetching declarations never executes the code. Its source-header version, plain creator
+label and source provenance stay as before. Selection keeps catalog versions, explicit
+creator links and documentation links. Those unrequested presentation differences are not
+changed by the shared renderer. Supplied `entry.category` is rendered in either view;
+category-free project entries stay flat without any catalog lookup or inferred category.
+
+
+The Pages document has the following contract (`schemaVersion: 1`):
+
+```json
+{
+  "schemaVersion": 1,
+  "categories": [{"id": "camera", "title": "Camera", "titleJa": "カメラ"}],
+  "extensions": [
+    {
+      "id": "cameraSource",
+      "name": "Camera Source",
+      "category": "camera",
+      "version": "1.2.3",
+      "package": "@example/camera-source",
+      "url": "https://cdn.jsdelivr.net/npm/@example/camera-source@1.2.3/dist/extension.js",
+      "description": "Share a camera stream.",
+      "descriptions": {"ja": "カメラ映像を共有します。"},
+      "repository": "https://github.com/example/camera-source",
+      "banner": "https://example.com/camera-source.svg",
+      "unsandboxed": "required",
+      "dependencies": []
+    }
+  ]
+}
+```
+
+IDs contain ASCII letters and digits. `name`, `version`, `url`, and `dependencies` are
+required. Dependencies are extension IDs in this document, not npm package names;
+the generator resolves package dependencies to these IDs. `package`, descriptions, author,
+license, banner, repository and execution requirement are optional metadata. The generator
+uses version-pinned, published distribution URLs and excludes build-only packages.
+`parseExtensionCatalog` rejects unsupported schemas, duplicate IDs/URLs, missing dependencies,
+cycles, and non-HTTPS or credential-bearing URLs before the UI or VM receives entries.
+`resolveExtensionSelection(entries, explicitIds, loadedIds)` exposes the same closure and
+load order independently of React. Its `requiredBy` map associates each dependency ID with
+a set of the explicit root IDs that require it, including transitive and shared dependencies.
+Optional `categories: [{id, title, titleJa?}]` are declared once, in dashboard order;
+`extensions[].category` references one of those IDs. Duplicate category IDs, invalid
+definitions and unknown references are rejected. `parseExtensionCatalog` retains its array
+return type and resolves each reference to `entry.category: {id, title, titleJa?, order}`.
+`loadExtensionCatalog` accepts an optional AbortSignal,
+omits credentials/referrers, and rejects failed HTTP responses or invalid JSON contracts.
+
+To roll back catalog integration, turn off the host's startup flag (off by default) and
+reload, or revert the catalog wiring. The existing three-way security dialog remains
+available without the catalog API.
+
 ## Stored preferences
 
 Preferences are saved only when OK was pressed **and** the project then opened successfully.