@kubohiroya/turbowarp-extension-security-dialog 0.1.0 → 0.3.0

package/NOTICE.md

@@ -30,3 +30,11 @@ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 ## Public Editor screenshots
 
 `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

@@ -1,21 +1,103 @@
 # turbowarp-extension-security-dialog
 
-[English](./README.md) | **日本語**
+[English](README.md) | 日本語
 
 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のメタデータを直ちに表示し、「詳細」を開いたときだけソースを文字列として取得します。
+取得に失敗してもカタログのメタデータと選択は利用できます。
+実行許可確認には `ExtensionSecurityDialog context="catalog"` を使用でき、キャンセル文言が選択一覧へ戻る案内になります。
+既定の `context="project"` はプロジェクト読み込み用の文言を維持します。
+ホストは確定された実行モードと独自のセキュリティ方針を尊重して読み込んでください。
+
+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`・`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を拒否します。
+`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.3・Asset Cache 0.3.1・Bubble 0.13.4を開いた実画面です。
+[英語版](./README.md)と日本語版は、同じダイアログの表示言語を切り替え、ラベルと拡張の説明文を各言語で表示しています。
+全件必須時の自動選択と一括選択欄の非表示に対応した[公開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を開いた実画面です。
 
-![3拡張の日本語確認画面。サンドボックスありは非対応で無効、サンドボックスなしは動作に必要。サンドボックス内では動作しない理由を表示](https://raw.githubusercontent.com/kubohiroya/turbowarp-extension-security-dialog/main/assets/screenshots/required-modes-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 +107,7 @@ Camera Source 0.19.3・Asset Cache 0.3.1・Bubble 0.13.4を開いた実画面で
 | Bubble | ホストの実行環境と描画機能へ直接アクセスして、ステージ上に重ねた吹き出しや立ち絵を描画・更新します。 |
 
 画像はダイアログ部分をブラウザーで直接撮影したもので、加工していません。
-取得元の版・Editor build・画像hashは[撮影台帳](./assets/screenshots/capture-20261025.json)に記録しています。
+取得元の版・Editor build・画像hashは[撮影台帳](./assets/screenshots/hidden-bulk-required-20261028.json)に記録しています。
 
 ## 連動するパッケージ
 
@@ -186,17 +268,36 @@ HTTP/HTTPSの出所URLは完全なURLを表示し、別タブで開きます。
 プレビュー枠内をスクロールして確認できます。ポインターを外すかEscapeで閉じ、選択や詳細状態を保持します。
 メタデータの非同期取得中も実行方法を選べます。ソースの一覧内表示は引き続き「詳細」を押したときだけです。
 
+### 機能拡張の説明文の言語
+
+拡張コードを実行せず、任意の言語別ヘッダーコメントを読み取ります。
+
+```js
+// Description: Share one camera stream between extensions.
+// Description[ja]: 1つのカメラ映像を複数の機能拡張で共有します。
+// Description[ja-JP]: 日本語の説明（日本向け）。
+```
+
+言語タグの大文字・小文字は区別しません。Editorの言語の完全一致、基底言語、従来の`Description`の順で説明文を選びます。表示中に言語を変えると、ソースを再取得せず説明が切り替わり、許可の選択状態は保たれます。翻訳がない既存の拡張も従来どおり表示できます。
+
+同梱メンバーのnoticeにある説明は親バンドルへ混ぜません。HTMLに見える説明も文字列として表示します。独自の`loadInfo`を使う場合は、任意の`ExtensionMetadata.descriptions`へ小文字の言語タグをキーとした説明を渡せます。`getExtensionDescription(metadata, locale)`でも同じ選択処理を利用できます。
+
+上の画像は、日本語説明へ対応した公開Editorと公開済みの3拡張を使用しています。英語版では各拡張の従来の`Description`、日本語版では`Description[ja]`を表示します。対応する翻訳がない拡張は元の説明を表示します。説明の言語が変わっても、必要な実行モードや許可の選択は変わりません。パッケージを更新しても、既存SB3に埋め込まれたコードは自動で差し替わりません。
+
 ## 実行モードの選択
 
 個別選択・一括選択・一覧の見出しは、禁止アイコンの「拒否」、盾の「サンドボックスあり」、
 警告の「サンドボックスなし」の順です。アイコンと色は文字ラベルを補助し、安全性の認定には使いません。
 
-先頭の宣言コメントに `// Unsandboxed: required` があれば、「サンドボックスあり」を無効化して
-動作しない理由を表示し、「サンドボックスなし」に「動作に必要」を付けます。拒否は選択できます。
+先頭の宣言コメントに `// Unsandboxed: required` があれば、「拒否」と「サンドボックスあり」を無効化して
+理由を表示し、選択できる唯一のモード「サンドボックスなし」に「動作に必要」を付けます。
+選択したモードを「OK」で承認するか、「キャンセル」でプロジェクトの読み込みを中止します。
 この宣言は作者の自己申告であり、未宣言・取得失敗から必須モードを推測しません。
 
-実行する選択の確定はメタデータ取得の完了または失敗後です。遅れて取得した宣言に対応しない選択は、
-保存済みの復元値も含めて解除し、選び直しを案内します。権限の広いモードへ自動で変更しません。
+「拒否」を含む選択の確定はメタデータ取得の完了または失敗後です。全拡張の取得が成功し、すべてが
+この必須モードを宣言していれば、非対応の保存済み選択も含めて「サンドボックスなし」を選択済みにします。
+「OK」を押すまで拡張は実行せず、「キャンセル」で中止できます。取得中・未宣言・任意指定・取得失敗が
+1件でもあれば、この一括初期選択は行いません。混在する一覧では、非対応の選択を解除して選び直しを案内します。
 一括選択は対応する拡張だけに適用し、全件が非対応の一括ボタンは無効化します。
 
 ## 接続例
@@ -238,8 +339,8 @@ scratch-guiは既定OFFの起動時フラグで導入し、ホスト独自のセ
 ## 開発と検証
 
 ```sh
-npm install
-npm test
+pnpm install
+pnpm test
 ```
 
 GUIとの統合では、実VMでの拒否後の表示・保存、エディター初期画面への遷移、

package/README.md

@@ -1,6 +1,6 @@
 # turbowarp-extension-security-dialog
 
-**English** | [日本語](./README.ja.md)
+English | [日本語](README.ja.md)
 
 A shared package that reviews every custom extension a TurboWarp project is about to load
 in **one single list**, instead of one prompt per extension.
@@ -9,17 +9,18 @@ Related tasks and acceptance criteria are tracked in
 
 ## Screenshots from the public Editor
 
-[English](./README.md) and [Japanese](./README.ja.md) use the same dialog with localized labels.
-This capture shows Camera Source 0.19.3, Asset Cache 0.3.1 and Bubble 0.13.4 in the
+[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 extension review: 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/required-modes-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/capture-20261025.json).
+hashes are recorded in [the capture manifest](./assets/screenshots/hidden-bulk-required-20261028.json).
 
 ## How it fits together
 
@@ -193,21 +194,48 @@ or a file timestamp.
 
 Run modes remain selectable while metadata is still loading.
 
+### Localized extension descriptions
+
+The dialog reads optional language-tagged header comments, without evaluating extension code:
+
+```js
+// Description: Share one camera stream between extensions.
+// Description[ja]: 1つのカメラ映像を複数の機能拡張で共有します。
+// Description[ja-JP]: 日本語の説明（日本向け）。
+```
+
+Tags are case-insensitive. Display selection uses the exact Editor locale, then its base
+language, then the original `Description`. A locale change updates the text without refetching
+source or changing permission choices. Missing translations keep existing extensions compatible.
+Only the enclosing header is used; bundled member notices cannot supply its translation.
+HTML-looking text is rendered as text. The optional `ExtensionMetadata.descriptions` record uses
+lowercase keys, and `getExtensionDescription(metadata, locale)` exposes the same lookup.
+
+The public Editor and the three published bundles shown above support localized descriptions.
+The English capture uses each original `Description`; the Japanese capture uses `Description[ja]`.
+Extensions without a matching translation retain their original description. The selected language
+does not change required modes or permission choices. Updating a package does not replace code
+already embedded in an existing SB3.
+
 ## Choosing a run mode
 
 Per-row choices, the bulk choices and the list heading are ordered: **Deny** (prohibition
 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
 
@@ -228,6 +256,107 @@ 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, metadata and Details view,
+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 or source controls. 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`.
+
+The selection list never loads or runs extension code. Catalog metadata renders immediately;
+only Details fetches the source as text. Source failures leave catalog metadata and selection
+usable. `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.
+
+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.
@@ -252,8 +381,8 @@ own security policy take precedence.
 ## Development and verification
 
 ```sh
-npm install
-npm test
+pnpm install
+pnpm test
 ```
 
 GUI integration additionally verifies display and storage after a real-VM denial, the