@kubohiroya/turbowarp-extension-loader 0.2.1 → 0.3.1

package/CHANGELOG.md

@@ -2,6 +2,39 @@
 
 ## Unreleased
 
+## 0.3.1
+
+Released on 2026-11-02. One fix, the one 0.3.0 said would follow here: `./project-catalog` no
+longer leaves behind the archive copy a replaced Embedded or Cached entry kept. No exported API
+and no default changes, so a host needs nothing but the version bump.
+
+- `./project-catalog` releases the archive copy a replaced Embedded or Cached entry kept. Switching
+  an extension to Remote left the old `extensions/…` file in the SB3 although no Manifest entry named
+  it any more. A copy the new entry still uses (Cached ↔ Embedded) stays.
+
+## 0.3.0
+
+Released on 2026-11-02. A bounded retry for Remote fetching, so one transient failure no longer
+ends a whole load. The only change is the retry below; the fix for the copy a replaced Embedded or
+Cached entry keeps is **not** in this release, because that work is still open — it follows in
+0.3.1. New exported API and a changed default make this a minor release: a host that wants the
+previous single attempt passes `{retries: 0}`.
+
+- The fetch port retries a transient Remote failure a bounded number of times instead of failing on
+  the first one. `createFetchPort()` now wraps itself in the new `withFetchRetry(port, options)`, so
+  a host on the default port needs no change; a host that injects its own port can wrap it the same
+  way, and the core cannot impose the behaviour on it. Only a connection that could not be made and
+  an HTTP 408, 425, 429 or 5xx are repeated — `isTransientFetchFailure(error)` is the exported
+  classifier, and a `FETCH_FAILED` carries the HTTP status in its `cause`. `DEFAULT_FETCH_RETRY`
+  allows 2 retries, 400 ms of backoff doubling to a 2 s cap, and a 5 s budget measured from the
+  first attempt; the 30-second fetch and authorization deadline still covers the whole operation, so
+  the worst-case wait does not grow. A backoff wait is interrupted by the `AbortSignal` rather than
+  waited out, and `{retries: 0}` restores the previous single attempt.
+- A load or a catalog preparation that finally fails now aborts its own `AbortSignal` before
+  reporting, so port work the core has stopped waiting for does not keep running unobserved. Every
+  entry is still verified and authorized before registration starts, and a failure still rolls the
+  host transaction back.
+
 ## 0.2.1
 
 Default size limits that fit real extensions. A bundled story runtime of about 7 MiB was rejected in

package/README.ja.md

@@ -15,7 +15,7 @@ npm install @kubohiroya/turbowarp-extension-loader
 - 拡張ごとの Embedded / Remote / Cached 解決、SHA-256 必須固定、UTF-8 検証、コードごと・全体のサイズ上限。
 - SHA-256 キーのキャッシュポート。読み出すたびに exact bytes を再検証し、キャッシュ利用時もホストの認可を要求します。
 - 明示的なホスト認可後、全拡張の検証・認可が揃ってから登録を始めます。登録 ID 不一致・登録失敗はホスト transaction の rollback を要求します。
-- キャンセル、取得・認可のタイムアウト、重複ロード拒否、unload、診断イベント。
+- キャンセル、取得・認可のタイムアウト、Remote の一時的な失敗の有限回の再試行、重複ロード拒否、unload、診断イベント。
 
 標準拡張・汎用カスタム URL・従来の Data URL は読み替えません。Manifest がない作品ではホストポートを呼び出しません。作品内の `execution: "unsandboxed"` は要求値であり権限ではありません。`trusted` などの未知フィールドは拒否します。
 
@@ -67,8 +67,8 @@ await loader.unload();
 - core は JS を評価しません。評価権限と VM 内部 API はホストに限定します。
 - ロールバックはホストの拡張登録状態の保証です。一度評価した特権 JS の DOM / ネットワーク等の副作用を巻き戻すことはできません。安全なコードの承認は別途必要です。
 - 初期版は Remote の HTTP、資格情報付き URL、フラグメント、リダイレクトをすべて拒否します。HTTPS URL の正常取得だけで認可しません。
-- `createFetchPort()` はリダイレクト無効、credentials 不送信、referrer 不送信、ストリームの実サイズ制限を適用します。CORS / CSP / offline の fetch 拒否は `LOAD_FAILED` の `cause` に保持します。ネットワーク層の詳細分類はcauseへ委ね、CORS/CSPはEditor側の実ブラウザーE2Eで検証します。
-- injected fetch ポートは `finalURL` と明示的な空 `redirects` を返す必要があります。ポート自体は信頼済みホストが実装する境界です。
+- `createFetchPort()` はリダイレクト無効、credentials 不送信、referrer 不送信、ストリームの実サイズ制限を適用します。CORS / CSP / offline の fetch 拒否は `LOAD_FAILED` の `cause` に保持し、失敗した HTTP 応答はステータスも同じ `cause` に残します。ネットワーク層の詳細分類はcauseへ委ね、CORS/CSPはEditor側の実ブラウザーE2Eで検証します。
+- injected fetch ポートは `finalURL` と明示的な空 `redirects` を返す必要があります。ポート自体は信頼済みホストが実装する境界であり、再試行もその境界に置いています（後述）。
 - 取得・認可は応答しないポートでもタイムアウトします。登録処理はキャンセル後も完了を待ってから rollback します。遅れて完了する登録と rollback の競合を避けるため、登録ポートが `AbortSignal` に応答しない場合、登録中の有限時間終了は保証できません。
 - キャッシュの容量・失効・永続化・出所ログはホストのポートが担当します。壊れたキャッシュを暗黙に無視して Remote へ切り替えません。
 - `./packager` はEmbedded / Remote変換、明示承認付きData URL移行、lock/license metadata保持、offline SB3準備を提供します。外部依存資源がある拡張は同梱を推測せず拒否します。署名・発行者鍵のpinningはホスト側で追加できる設計で、初期実装は内容・取得元に束縛したセッション承認です。
@@ -76,6 +76,24 @@ await loader.unload();
 
 既定値は最大64拡張、1拡張16 MiB、合計64 MiB、取得・認可30秒です。1拡張と合計の既定値は project codec の1 entry と全展開量の上限に揃えてあり、作品に格納できる拡張ファイルは Loader でも読めます。ホストは loader options で下げられます。データURLやHTTPの開発モード例外はありません。標準 TurboWarp / 非対応エディターが独自 Manifest と ZIP エントリを破棄する可能性があるため、保持対応のないホストでの再保存は移行手段になりません。
 
+### Remote の一時的な失敗の再試行
+
+再試行は fetch ポートに置いています。`createFetchPort()` は自身を `withFetchRetry()` で包むため、既定ポートを使うホストは変更不要です。独自ポートを注入するホストも `withFetchRetry(hostPort)` で同じように包めます。core 自身の解決ループに再試行を置かない理由は2つあります。再試行は転送層の方針である一方、同じループの他の失敗（digest 不一致、壊れたキャッシュ、認可の拒否）は決して繰り返してはならないこと。そして core は任意のポートが投げたものを分類できないため、ここで再試行すると推測するか、既存の全ポートに新しいエラー契約を強いることになること。**その帰結として、core は注入されたポートの挙動を強制できません。** 独自ポートを実装するホストが自分で決めることになり、`./project-catalog` と `./project-authoring` は渡されたポートと同じだけ再試行します。
+
+| 失敗 | 再試行する | 再試行しない |
+| --- | --- | --- |
+| HTTP 応答があった | 408 / 425 / 429 と 5xx 全般 | それ以外の 4xx。404 は「無い」という答え |
+| 応答が無かった | 接続できなかった場合 | `AbortSignal` による中止。タイムアウトも含む |
+| 要求の前 | — | URL・HTTP・資格情報・フラグメントの拒否（`INVALID_SOURCE`） |
+| 応答の後 | — | リダイレクトと最終 URL の不一致（`FETCH_FAILED` / `REDIRECT_DENIED`）、サイズ上限（`INVALID_BYTES`）、digest 不一致、壊れたキャッシュ、認可の拒否 |
+| キャッシュヒット | — | ハッシュ固定のエントリは CDN に接触しないため対象外 |
+
+分類は `isTransientFetchFailure(error)` として公開し、`createFetchPort()` が出す `FETCH_FAILED` は HTTP ステータスを `cause` に保持するので、包む側から読めます。ただし分類できない事象が1つあります。ブラウザーの `fetch()` は、接続できなかった場合・DNS 失敗・オフライン・CORS / CSP による拒否のいずれでも同一の `TypeError` を返します。仕様が意図して区別させていません。したがって CORS / CSP による拒否も、本来の対象である接続失敗と一緒に再試行されます。これが許容できるのは待ち時間の上限が小さいからであり、上限を小さくした理由でもあります。
+
+**待ち時間は二重に制限されます。** `DEFAULT_FETCH_RETRY` は再試行2回、400 ms → 800 ms のバックオフで、最初の試行から5秒を超えて新しい試行を始めません。この上限はバックオフの待機も含むため、1回目が遅ければそれだけで使い切ります。その上に、取得・認可の既定タイムアウト30秒が操作全体を覆います。これは fetch 1件ごとのタイマーではなく、全拡張の取得・認可・登録を1つのタイマーで覆うものです。よって再試行でタイムアウトが倍になることはありません。30秒は本変更の前から最悪値であり、後も最悪値のままです。上限が決めるのは、その30秒のうち1つの URL が問い直しに使える分だけです。バックオフ待機は signal で中断され、待ち切ることはないので、キャンセルは即時のままです。`createFetchPort(fetchImpl, {retries: 0})` で従来の1回だけの挙動に戻せます。`onRetry` が各待機を通知するので、ホストは進捗を表示できます。
+
+あきらめたら最後です。登録は全エントリの検証・認可が揃ってから始まるため、再試行を使い切ったエントリが1件あれば操作全体が失敗します。エントリは1件ずつ解決するので、その後のエントリは取得されません。操作の `AbortSignal` も中止するので、core がもう待っていないポートの処理は停止します。ホスト transaction は rollback し、元の作品が復元されます。そこから先は待っている人が再試行機構であり、ホストは作品を開き直すか拡張の追加をやり直すよう求めます。誰も見ていないため再試行で失敗を吸収しなければならないビルド時のカタログ生成とは、意図して方針を逆にしています。
+
 ## IndexedDB 永続キャッシュ（ブラウザホスト用）
 
 固定された npm `name@exact-version` のCDN配信を想定し、**cache first** とします。ハッシュで固定されたキャッシュがあればオンライン・オフラインを問わずCDNへ問い合わせません。キャッシュミス時のみ既存Remote Fetch Portが取得します。URLに `latest`、semver範囲、バージョン省略等の可変指定を使わないことをホスト側で保証してください。キャッシュの保持にはTTLを設けず、容量超過時のLRU、明示消去、ブラウザのストレージ削除のみで削除します。gzip展開後のSHA-256照合とunsandboxed実行認可は毎回必要です。
@@ -137,6 +155,7 @@ npm run check
 - `isAuthorizedCode(value)` はコアが発行し現在登録中の認可証跡だけを識別します。コピー・作品データによる偽造を拒否し、transaction終了時に失効します。
 - `./session-trust` の `createSessionTrustProvider` はid/digest/source/version/publisher/capabilities/dependenciesへ束縛した承認を保持します。明示された外部ホストのURL/execution方針をUI前に毎回適用し、判定できないEmbedded要求は拒否します。
 - `./memory-cache` の `createMemoryContentCache` はコピー・容量（既定32 MiB、既定最大サイズの拡張2件分）・TTL・LRUを提供し、コアはヒット時にも内容を再検証します。
+- `withFetchRetry(port, options)` は任意の fetch ポートを上記の有限回の再試行で包み、`isTransientFetchFailure(error)` はその分類器、`DEFAULT_FETCH_RETRY` は既定値（再試行2回、400 ms から倍々で上限2秒、合計5秒）です。
 - `./webpack4` はGUI/Packager用の同一コアをwebpack 4でビルドするための構成補助です。
 
 実GUI、実Packager 3.14.0の生成HTML、Desktop 1.17.0の互換性はEditor側のE2Eが担当します。標準Desktopや標準WebへLoaderを無断インストールしません。標準Desktopの保存は独自Manifest/ZIPエントリを破棄することを実測しているため、保持対応エディターで保存してください。

package/README.md

@@ -15,7 +15,7 @@ npm install @kubohiroya/turbowarp-extension-loader
 - Per-extension Embedded / Remote / Cached resolution, a mandatory pinned SHA-256, UTF-8 validation, and per-code and total size limits.
 - A SHA-256-keyed cache port. Every read re-verifies the exact bytes, and a cache hit still requires host authorization.
 - Registration starts only after explicit host authorization and only once every extension has been verified and authorized. A registration ID mismatch or a registration failure requires the host transaction to roll back.
-- Cancellation, fetch and authorization timeouts, duplicate load rejection, unload, and diagnostic events.
+- Cancellation, fetch and authorization timeouts, a bounded retry of transient Remote failures, duplicate load rejection, unload, and diagnostic events.
 
 Standard extensions, generic custom URLs and legacy Data URLs are not reinterpreted. For a project without a Manifest, no host port is called. `execution: "unsandboxed"` inside a project is a request, not a permission. Unknown fields such as `trusted` are rejected.
 
@@ -67,8 +67,8 @@ The real VM adapter is owned by `scratch-gui/src/lib/tw-plus-extension-registrar
 - The core does not evaluate JS. Evaluation privileges and VM internal APIs stay with the host.
 - Rollback is a guarantee about the host's extension registration state. It cannot undo DOM, network or other side effects of privileged JS that has already been evaluated. Approving that the code is safe remains a separate decision.
 - The initial version rejects HTTP for Remote, URLs carrying credentials, fragments and redirects. A successful HTTPS fetch alone does not authorize anything.
-- `createFetchPort()` disables redirects, sends no credentials, sends no referrer, and enforces the real size limit on the stream. A fetch refused by CORS / CSP / offline conditions is preserved in the `cause` of `LOAD_FAILED`. Detailed classification of network-layer failures is left to `cause`; CORS and CSP are verified by real-browser E2E tests on the Editor side.
-- An injected fetch port must return `finalURL` and an explicitly empty `redirects`. The port itself is a boundary implemented by the trusted host.
+- `createFetchPort()` disables redirects, sends no credentials, sends no referrer, and enforces the real size limit on the stream. A fetch refused by CORS / CSP / offline conditions is preserved in the `cause` of `LOAD_FAILED`, and a failed HTTP response keeps its status there. Detailed classification of network-layer failures is left to `cause`; CORS and CSP are verified by real-browser E2E tests on the Editor side.
+- An injected fetch port must return `finalURL` and an explicitly empty `redirects`. The port itself is a boundary implemented by the trusted host, which is where retrying lives as well; see below.
 - Fetching and authorization time out even against a port that never responds. Registration waits for completion before rolling back, even after cancellation. To avoid a race between a late-completing registration and a rollback, a registration port that does not respond to `AbortSignal` cannot guarantee that an in-flight registration finishes in bounded time.
 - Cache capacity, invalidation, persistence and provenance logging belong to the host's port. A corrupted cache is never silently ignored in favour of switching to Remote.
 - `./packager` provides Embedded / Remote conversion, Data URL migration with explicit approval, lock and license metadata preservation, and offline SB3 preparation. An extension with external dependent resources is rejected rather than guessed into a bundle. Signature and publisher key pinning can be added by the host; the initial implementation is session approval bound to content and source.
@@ -76,6 +76,24 @@ The real VM adapter is owned by `scratch-gui/src/lib/tw-plus-extension-registrar
 
 The defaults are at most 64 extensions, 16 MiB per extension, 64 MiB in total, and 30 seconds for fetching and authorization. The per-extension and total defaults equal the project codec's per-entry and expansion limits, so any extension file a project can carry is also one the Loader reads; a host can lower them through its loader options. There is no development-mode exception for Data URLs or HTTP. Because standard TurboWarp and unsupported editors may discard the non-standard Manifest and ZIP entries, re-saving in a host without preservation support is not a migration path.
 
+### Retrying a transient Remote failure
+
+Retrying lives at the fetch port. `createFetchPort()` wraps itself in `withFetchRetry()`, so a host on the default port needs no change, and a host that injects its own port can wrap it the same way with `withFetchRetry(hostPort)`. The core does not retry inside its own resolution loop, for two reasons: retrying is a transport policy, while the other failures in that loop — a digest mismatch, a corrupt cache entry, a trust refusal — must never be repeated; and the core cannot classify what an arbitrary port throws, so retrying there would either guess or force every existing port into a new error contract. **The consequence is that the core cannot impose this on an injected port.** A host that implements its own port decides for itself, and `./project-catalog` and `./project-authoring` retry exactly as much as the port they are handed does.
+
+| Failure | Retried | Not retried |
+| --- | --- | --- |
+| An HTTP response | 408, 425, 429 and every 5xx | every other 4xx, 404 among them: the answer is that it is not there |
+| No response at all | a connection that could not be made | an `AbortSignal` abort, the deadline included |
+| Before the request | — | a rejected URL, HTTP, credentials or a fragment (`INVALID_SOURCE`) |
+| After the response | — | a redirect or an unproven final URL (`FETCH_FAILED`, `REDIRECT_DENIED`), the byte limit (`INVALID_BYTES`), a digest mismatch, a corrupt cache entry, a trust refusal |
+| A cache hit | — | a hash-pinned entry never contacts the CDN, so there is nothing to retry |
+
+`isTransientFetchFailure(error)` is the exported classifier, and a `FETCH_FAILED` from `createFetchPort()` keeps the HTTP status in its `cause` so a wrapper can read it. One case cannot be classified: in a browser, `fetch()` rejects with the same `TypeError` whether the connection could not be made, DNS failed, the browser is offline, or CORS or CSP refused the request. That is deliberate in the specification. A CORS or CSP refusal is therefore retried along with the connection failure this was written for, which is affordable only because the budget is small — and is why it is small.
+
+**The wait is bounded twice.** `DEFAULT_FETCH_RETRY` allows 2 retries, backing off 400 ms and then 800 ms, and starts no attempt more than 5 seconds after the first one; the budget covers the backoff, so a slow first attempt spends it. Above that, the 30-second fetch and authorization deadline still covers the whole operation — every extension's fetch, authorization and registration under one timer, not one timer per fetch. Retrying therefore does not multiply the deadline: 30 seconds was the worst case before this and remains the worst case after it, and the budget only decides how much of those 30 seconds one URL may spend asking again. A backoff wait is interrupted by the signal rather than waited out, so cancelling stays immediate. `createFetchPort(fetchImpl, {retries: 0})` restores the previous single attempt, and `onRetry` reports every wait so a host can show progress.
+
+Giving up is final. Registration starts only once every entry is verified and authorized, so one entry whose retries are spent ends the whole operation: the entries after it are never fetched, because entries are resolved one at a time; the operation's `AbortSignal` is aborted so port work it no longer waits for stops; the host transaction rolls back and the original project is restored. From there the person waiting is the retry mechanism, and the host asks them to open the project or add the extension again. The asymmetry with build-time catalog generation, where nobody is watching and a retry has to absorb the failure, is deliberate.
+
 ## IndexedDB persistent cache (for browser hosts)
 
 The design assumes CDN delivery of a pinned npm `name@exact-version`, and is **cache first**. When a hash-pinned cache entry exists, the CDN is not contacted whether online or offline. Only a cache miss goes through the existing Remote fetch port. The host must guarantee that URLs never use a mutable specifier such as `latest`, a semver range, or an omitted version. Cached content has no TTL: it is removed only by LRU eviction on quota overflow, by explicit clearing, or by the browser deleting site storage. SHA-256 verification after gzip decompression and authorization for unsandboxed execution are still required every time.
@@ -135,6 +153,7 @@ Unsupported formats are ZIP64, multidisk, encryption, compression other than STO
 - `isAuthorizedCode(value)` identifies only an authorization trail issued by the core and currently being registered. Copies and forgeries from project data are rejected, and the trail expires when the transaction ends.
 - `createSessionTrustProvider` in `./session-trust` keeps approval bound to id, digest, source, version, publisher, capabilities and dependencies. It applies the explicit external host URL / execution policy before the UI every time, and rejects an Embedded request it cannot decide.
 - `createMemoryContentCache` in `./memory-cache` provides copying, capacity (32 MiB by default, two extensions of the largest default size), TTL and LRU, and the core re-verifies the content even on a hit.
+- `withFetchRetry(port, options)` wraps any fetch port in the bounded retry described above, `isTransientFetchFailure(error)` is the classifier it applies, and `DEFAULT_FETCH_RETRY` holds the defaults (2 retries, 400 ms of backoff doubling to a 2 s cap, a 5 s budget).
 - `./webpack4` is a configuration helper for building the same core with webpack 4 for the GUI and Packager.
 
 Compatibility with the real GUI, with the HTML generated by the real Packager 3.14.0, and with Desktop 1.17.0 is covered by E2E tests on the Editor side. Do not install the Loader into standard Desktop or standard Web without permission. Saving in standard Desktop has been measured to discard the non-standard Manifest and ZIP entries, so save in an editor that preserves them.

package/dist/index.d.ts

@@ -65,6 +65,20 @@ export interface FetchResult {
 export interface FetchPort {
     fetch(url: string, options: ReadOptions): Promise<FetchResult>;
 }
+export interface FetchRetryOptions {
+    /** Attempts after the first one; 0 turns retrying off. */
+    retries?: number;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+    /** Wall clock since the first attempt; no further attempt starts once it is spent. */
+    budgetMs?: number;
+    onRetry?: (attempt: Readonly<{
+        url: string;
+        attempt: number;
+        delayMs: number;
+        error: unknown;
+    }>) => void;
+}
 export interface RegistrationTransaction {
     register(code: AuthorizedCode, options: {
         signal: AbortSignal;
@@ -141,7 +155,54 @@ export declare class LoaderError extends Error {
 export declare function validateManifest(input: unknown, options?: Pick<LoaderOptions, 'maxExtensions'>): Manifest;
 export declare function discoverManifest(project: unknown, options?: Pick<LoaderOptions, 'maxExtensions'>): Manifest | null;
 export declare const parseManifest: typeof validateManifest;
-/** Browser fetch port rejects redirects and streams with a byte limit. */
-export declare function createFetchPort(fetchImpl?: typeof fetch): FetchPort;
+/**
+ * The bounded retry the default fetch port applies.
+ *
+ * A load already has one deadline (`timeoutMs`, 30 seconds by default) covering every extension's
+ * fetch, authorization and registration, so retrying can never extend the wait a person already
+ * faces. This budget is the separate, tighter ceiling on how long retrying one URL may go on:
+ * 400 ms then 800 ms of backoff, and no attempt begins more than 5 seconds after the first one.
+ */
+export declare const DEFAULT_FETCH_RETRY: Readonly<{
+    retries: 2;
+    baseDelayMs: 400;
+    maxDelayMs: 2000;
+    budgetMs: 5000;
+}>;
+/**
+ * Whether asking again could plausibly answer differently.
+ *
+ * A `FETCH_FAILED` carrying an HTTP status is an answer from the server, and only a request
+ * timeout, a too-early retry, a rate limit and a server-side error are worth repeating; 404 is the
+ * answer that it is not there. Every other `LoaderError` is a policy or validation refusal — a
+ * redirect, a byte limit, a rejected URL, a cancellation — and repeating it returns the refusal.
+ *
+ * A rejection that is not a `LoaderError` is a transport failure with no response at all. In a
+ * browser one `TypeError` covers a connection that could not be made, DNS failure and being
+ * offline, but also a CORS or CSP refusal: fetch deliberately makes them indistinguishable, so a
+ * permanent refusal is retried along with the connection failure this was written for. That is
+ * affordable only because the budget is small, and it is why the budget is small.
+ */
+export declare function isTransientFetchFailure(error: unknown): boolean;
+/**
+ * Retry a transient Remote failure a bounded number of times, then give the failure up.
+ *
+ * Retrying belongs to the fetch port and not to the loader's own loop: it is a transport policy,
+ * while the loop's other failures — a digest mismatch, a corrupt cache entry, a trust refusal —
+ * must never be repeated, and the core cannot classify what an arbitrary port throws. So the core
+ * cannot impose this on an injected port: a host that implements its own port keeps full control
+ * and gets no retry unless it asks, either by wrapping its port in this helper or by retrying
+ * inside it. `createFetchPort()` wraps itself, so a host on the default port needs no change.
+ *
+ * Giving up is final here. One entry that finally fails ends the whole operation, because
+ * registration starts only once every entry is verified and authorized; the person waiting is the
+ * retry mechanism from that point on, and the host asks them to try again.
+ */
+export declare function withFetchRetry(port: FetchPort, options?: FetchRetryOptions): FetchPort;
+/**
+ * Browser fetch port rejects redirects and streams with a byte limit, and retries a transient
+ * failure within `DEFAULT_FETCH_RETRY`. Pass `{retries: 0}` for a single attempt.
+ */
+export declare function createFetchPort(fetchImpl?: typeof fetch, retry?: FetchRetryOptions): FetchPort;
 /** The host owns all ports, especially trust decisions and privileged execution. */
 export declare function createExtensionLoader(ports: LoaderPorts, options?: LoaderOptions): ExtensionLoader;

package/dist/index.js

@@ -161,13 +161,114 @@ async function guarded(task, signal) {
         signal.removeEventListener('abort', abort);
     }
 }
-/** Browser fetch port rejects redirects and streams with a byte limit. */
-export function createFetchPort(fetchImpl = globalThis.fetch) {
+/** A backoff wait the signal interrupts, so a cancelled load never sits out its remaining delay. */
+function delay(ms, signal) {
+    checkSignal(signal);
+    return new Promise((resolve, reject) => {
+        let timer;
+        const abort = () => {
+            clearTimeout(timer);
+            try {
+                checkSignal(signal);
+            }
+            catch (error) {
+                reject(error);
+            }
+        };
+        timer = setTimeout(() => { signal.removeEventListener('abort', abort); resolve(); }, ms);
+        signal.addEventListener('abort', abort, { once: true });
+    });
+}
+/**
+ * The bounded retry the default fetch port applies.
+ *
+ * A load already has one deadline (`timeoutMs`, 30 seconds by default) covering every extension's
+ * fetch, authorization and registration, so retrying can never extend the wait a person already
+ * faces. This budget is the separate, tighter ceiling on how long retrying one URL may go on:
+ * 400 ms then 800 ms of backoff, and no attempt begins more than 5 seconds after the first one.
+ */
+export const DEFAULT_FETCH_RETRY = Object.freeze({ retries: 2, baseDelayMs: 400, maxDelayMs: 2000, budgetMs: 5000 });
+const transientStatus = (status) => status === 408 || status === 425 || status === 429 || status >= 500;
+/**
+ * Whether asking again could plausibly answer differently.
+ *
+ * A `FETCH_FAILED` carrying an HTTP status is an answer from the server, and only a request
+ * timeout, a too-early retry, a rate limit and a server-side error are worth repeating; 404 is the
+ * answer that it is not there. Every other `LoaderError` is a policy or validation refusal — a
+ * redirect, a byte limit, a rejected URL, a cancellation — and repeating it returns the refusal.
+ *
+ * A rejection that is not a `LoaderError` is a transport failure with no response at all. In a
+ * browser one `TypeError` covers a connection that could not be made, DNS failure and being
+ * offline, but also a CORS or CSP refusal: fetch deliberately makes them indistinguishable, so a
+ * permanent refusal is retried along with the connection failure this was written for. That is
+ * affordable only because the budget is small, and it is why the budget is small.
+ */
+export function isTransientFetchFailure(error) {
+    if (error instanceof LoaderError) {
+        const status = error.cause?.status;
+        return error.code === 'FETCH_FAILED' && typeof status === 'number' && transientStatus(status);
+    }
+    // An abort is the host's own decision or the deadline's, never something to ask again.
+    return !(error instanceof Error && (error.name === 'AbortError' || error.name === 'TimeoutError'));
+}
+/**
+ * Retry a transient Remote failure a bounded number of times, then give the failure up.
+ *
+ * Retrying belongs to the fetch port and not to the loader's own loop: it is a transport policy,
+ * while the loop's other failures — a digest mismatch, a corrupt cache entry, a trust refusal —
+ * must never be repeated, and the core cannot classify what an arbitrary port throws. So the core
+ * cannot impose this on an injected port: a host that implements its own port keeps full control
+ * and gets no retry unless it asks, either by wrapping its port in this helper or by retrying
+ * inside it. `createFetchPort()` wraps itself, so a host on the default port needs no change.
+ *
+ * Giving up is final here. One entry that finally fails ends the whole operation, because
+ * registration starts only once every entry is verified and authorized; the person waiting is the
+ * retry mechanism from that point on, and the host asks them to try again.
+ */
+export function withFetchRetry(port, options = {}) {
+    if (typeof port?.fetch !== 'function')
+        fail('INVALID_PORT', 'A fetch port is required to retry');
+    const { retries, baseDelayMs, maxDelayMs, budgetMs } = { ...DEFAULT_FETCH_RETRY, ...options };
+    for (const [key, value] of Object.entries({ retries, baseDelayMs, maxDelayMs, budgetMs })) {
+        if (!Number.isSafeInteger(value) || value < 0)
+            fail('INVALID_OPTIONS', `Invalid ${key}`);
+    }
     return Object.freeze({
+        async fetch(url, readOptions) {
+            const started = Date.now();
+            for (let attempt = 0;; attempt++) {
+                try {
+                    return await port.fetch(url, readOptions);
+                }
+                catch (error) {
+                    const delayMs = Math.min(maxDelayMs, baseDelayMs * 2 ** attempt);
+                    // The budget covers the waiting too, so no attempt starts once it is spent.
+                    if (attempt >= retries || Date.now() - started + delayMs > budgetMs || !isTransientFetchFailure(error))
+                        throw error;
+                    try {
+                        options.onRetry?.(Object.freeze({ url, attempt: attempt + 1, delayMs, error }));
+                    }
+                    catch { /* Progress reporting must not change the outcome. */ }
+                    await delay(delayMs, readOptions.signal);
+                }
+            }
+        }
+    });
+}
+/**
+ * Browser fetch port rejects redirects and streams with a byte limit, and retries a transient
+ * failure within `DEFAULT_FETCH_RETRY`. Pass `{retries: 0}` for a single attempt.
+ */
+export function createFetchPort(fetchImpl = globalThis.fetch, retry = {}) {
+    return withFetchRetry(Object.freeze({
         async fetch(url, { signal, maxBytes }) {
             const response = await fetchImpl(remoteURL(url), { signal, redirect: 'error', credentials: 'omit', referrerPolicy: 'no-referrer' });
-            if (!response.ok || response.redirected || response.type === 'opaque' || response.url !== remoteURL(url))
+            if (response.redirected || response.type === 'opaque' || response.url !== remoteURL(url))
                 fail('FETCH_FAILED', 'Remote response is unavailable or redirected');
+            // The status is kept on the cause so a wrapper can tell a rate limit or a server-side
+            // error from an answer such as 404, which repeating would only ask for again.
+            if (!response.ok)
+                throw new LoaderError('FETCH_FAILED', `Remote response is unavailable (HTTP ${response.status})`, undefined, Object.freeze({ status: response.status }));
             const declared = response.headers.get('content-length');
             if (declared !== null && Number(declared) > maxBytes)
                 fail('INVALID_BYTES', 'Remote extension exceeds byte limit');
@@ -203,7 +304,7 @@ export function createFetchPort(fetchImpl = globalThis.fetch) {
             }
             return { bytes, finalURL: response.url, redirects: [] };
         }
-    });
+    }), retry);
 }
 /** The host owns all ports, especially trust decisions and privileged execution. */
 export function createExtensionLoader(ports, options = {}) {
@@ -341,6 +442,9 @@ export function createExtensionLoader(ports, options = {}) {
             }
             if (state !== 'failed')
                 state = 'idle';
+            // Rollback is done, so nothing of this operation should still be running on its signal:
+            // stop the port work the core has already stopped waiting for, retries included.
+            controller.abort(error);
             report({ type: 'error', code: error.code, id: error.extensionId });
             throw error;
         }

package/dist/project-catalog.js

@@ -114,7 +114,12 @@ export async function prepareCatalogExtensionChanges(input, requests, ports, { z
             fetched.set(url, bytes);
             return bytes;
         }
+        // Copies the replaced entries kept; released below unless a final entry still names them.
+        const replacedPaths = new Set();
         for (const choice of choices) {
+            const replaced = prepared.manifest?.extensions.find(spec => spec.id === choice.id)?.source;
+            if (replaced && replaced.type !== 'remote')
+                replacedPaths.add(replaced.path);
             const old = previous.get(choice.id);
             // Every catalog request was validated as a Remote source above.
             const bytes = old ? encoder.encode(old.code) : await fetchBytes(choice.source.url);
@@ -145,6 +150,11 @@ export async function prepareCatalogExtensionChanges(input, requests, ports, { z
                 capabilities: old?.capabilities || [], dependencies: choice.dependencies });
         }
         const manifest = validateManifest({ schemaVersion: 1, extensions: [...extensions.values()] }, loaderOptions);
+        for (const spec of manifest.extensions)
+            if (spec.source.type !== 'remote')
+                replacedPaths.delete(spec.source.path);
+        for (const path of replacedPaths)
+            delete files[path];
         project.turboWarpPlus = manifest;
         project.extensions = [...new Set([...(project.extensions || []), ...manifest.extensions.map(spec => spec.id)])];
         const urls = { ...(project.extensionURLs || {}) };
@@ -167,6 +177,13 @@ export async function prepareCatalogExtensionChanges(input, requests, ports, { z
         check();
         return Object.freeze({ projectBytes, manifest });
     }
+    catch (error) {
+        // The selection is one operation: once an entry finally fails, nothing else about it is
+        // wanted, so stop the port work it started instead of leaving it running unobserved.
+        controller.abort(error instanceof LoaderError ? error :
+            new LoaderError('LOAD_FAILED', 'Catalog changes failed', undefined, error));
+        throw error;
+    }
     finally {
         clearTimeout(timer);
         externalSignal?.removeEventListener('abort', abort);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubohiroya/turbowarp-extension-loader",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "Host-independent verified TurboWarp Plus extension loading core",
   "keywords": [
     "turbowarp",