@kubohiroya/turbowarp-extension-loader 0.3.1 → 0.5.0

package/README.ja.md

@@ -12,7 +12,7 @@ npm install @kubohiroya/turbowarp-extension-loader
 
 - `project.json` の独自フィールド `turboWarpPlus` に schema v1 の Manifest を配置します。標準 SB3 仕様ではありません。
 - Manifest の厳格検証、未知フィールド拒否、重複・標準拡張 ID 拒否、依存順、循環・欠落依存拒否。
-- 拡張ごとの Embedded / Remote / Cached 解決、SHA-256 必須固定、UTF-8 検証、コードごと・全体のサイズ上限。
+- 拡張ごとに4つの source 形式のいずれかで解決、SHA-256 必須固定、UTF-8 検証、コードごと・全体のサイズ上限。
 - SHA-256 キーのキャッシュポート。読み出すたびに exact bytes を再検証し、キャッシュ利用時もホストの認可を要求します。
 - 明示的なホスト認可後、全拡張の検証・認可が揃ってから登録を始めます。登録 ID 不一致・登録失敗はホスト transaction の rollback を要求します。
 - キャンセル、取得・認可のタイムアウト、Remote の一時的な失敗の有限回の再試行、重複ロード拒否、unload、診断イベント。
@@ -21,17 +21,22 @@ npm install @kubohiroya/turbowarp-extension-loader
 
 ### ソースの形式
 
-`source` は拡張のバイト列の所在を示し、3つの形式のいずれかを取ります。0.2.0で追加した `cached` は2つの所在を同時に示すため、正本の公開場所を保ったままオフラインでも動作します。
+`source` は拡張のバイト列の所在を示します。作者が決めるもので、4つの形式があります。この4つは SB3 の保存形式および選択画面と同じ名前なので、層の間で読み替えが起きません。
 
-| 形式 | 構造 | 解決順 |
+| 形式 | 構造 | バイト列の出どころ |
 | --- | --- | --- |
-| `embedded` | `{type: 'embedded', path}` | `path` のアーカイブ内エントリ |
-| `remote` | `{type: 'remote', url}` | `url` のHTTPS取得 |
-| `cached` | `{type: 'cached', url, path}` | `path` の保持コピー → `url` のHTTPS取得 |
+| `remote-non-cacheable` | `{type, url}` | 毎回 `url` を HTTPS 取得 |
+| `remote-cacheable` | `{type, url}` | cache port、無ければ `url` を HTTPS 取得 |
+| `embedded-file` | `{type, path, url?}` | `path` のアーカイブ内エントリ、無ければ `url` |
+| `embedded-data` | `{type, url?}` | 作品の文書の `data:` 運び手、無ければ `url` |
 
-保持コピーは弱いソースではありません。ManifestがSHA-256を固定しているため、保持コピーは固定されたコードそのものか、さもなくば `DIGEST_MISMATCH` で失敗します。だからネットワークより先に読んでよいのです。エントリが無い場合は `retained-copy-unavailable` を診断として報告してURLへ退避し、そのURLは `remote` と同じredirect・最終URL方針のもとで固定バイト列を返さなければなりません。`path` は `embedded` と同じ `extensions/*.js` 方針に従い、cache portは両方の所在より優先されます。
+embedded の2つは兄弟です。どちらも「作品だけで、オフラインで、どこでも動く」を実現します。違いは運び手で、運び手が「ほかに誰が読めるか」を決めます。`embedded-data` は、標準 TurboWarp がこの Manifest を知らないまま作品を開けるようにする形です。標準ホストは作品の文書の中の URL を探すので、バイト列がその URL そのものになります。
 
-`cached` は `schemaVersion: 1` を維持するので、使っていないManifestは0.1.0でそのまま読めます。使っているManifestは0.2.0以降を必要とし、古い版は弱い形式で読み込まずに `INVALID_SOURCE` で拒否します。
+持っている中身は弱いソースではありません。ManifestがSHA-256を固定しているため、固定されたコードそのものか、さもなくば `DIGEST_MISMATCH` で失敗します。運び手が欠けている場合は `retained-copy-unavailable` を診断として報告して `url` へ退避し、その URL は参照形と同じ redirect・最終URL方針のもとで固定バイト列を返さなければなりません。`path` は `extensions/*.js` 方針に従います。
+
+キャッシュを読み書きするのは `remote-cacheable` だけです。embedded の作品は既に中身を持っているので、ブラウザーに2つ目の控えを置いても得るものがなく、作者もそれを求めていません。
+
+古い版が使っていた3つの綴り（`remote`、`cached`、`embedded`）は**拒否します**。それぞれ、何が置き換えるかをメッセージで示します。対になった2つは読み替えもしません。古い名前は選択を暗黙にしていたので、それを決めるのは読む人です。
 
 ## ホスト側の接続
 
@@ -71,7 +76,7 @@ await loader.unload();
 - injected fetch ポートは `finalURL` と明示的な空 `redirects` を返す必要があります。ポート自体は信頼済みホストが実装する境界であり、再試行もその境界に置いています（後述）。
 - 取得・認可は応答しないポートでもタイムアウトします。登録処理はキャンセル後も完了を待ってから rollback します。遅れて完了する登録と rollback の競合を避けるため、登録ポートが `AbortSignal` に応答しない場合、登録中の有限時間終了は保証できません。
 - キャッシュの容量・失効・永続化・出所ログはホストのポートが担当します。壊れたキャッシュを暗黙に無視して Remote へ切り替えません。
-- `./packager` はEmbedded / Remote変換、明示承認付きData URL移行、lock/license metadata保持、offline SB3準備を提供します。外部依存資源がある拡張は同梱を推測せず拒否します。署名・発行者鍵のpinningはホスト側で追加できる設計で、初期実装は内容・取得元に束縛したセッション承認です。
+- `./packager` は source 形式の相互変換、明示承認付きData URL移行、lock/license metadata保持、offline SB3準備を提供します。外部依存資源がある拡張は同梱を推測せず拒否します。署名・発行者鍵のpinningはホスト側で追加できる設計で、初期実装は内容・取得元に束縛したセッション承認です。
 - ZIP の実装は `createProjectIO({zip: JSZip})` に注入します。core の codec が ZIP central directory を直接検査し、重複・経路・宣言容量を検証してから、ストリーム展開の実容量と CRC32 を検査します。外部実装の archive port を使う場合も同等の検証が必要です。
 
 既定値は最大64拡張、1拡張16 MiB、合計64 MiB、取得・認可30秒です。1拡張と合計の既定値は project codec の1 entry と全展開量の上限に揃えてあり、作品に格納できる拡張ファイルは Loader でも読めます。ホストは loader options で下げられます。データURLやHTTPの開発モード例外はありません。標準 TurboWarp / 非対応エディターが独自 Manifest と ZIP エントリを破棄する可能性があるため、保持対応のないホストでの再保存は移行手段になりません。
@@ -122,6 +127,124 @@ const loader = createExtensionLoader({...hostPorts, cache});
 - 新たな Remote バイト列を取得し保存した場合も、権限承認は毎回別途必要です。コード内から追加取得される依存リソースや外部サービスはこのキャッシュの対象外です。
 - Web/Editor はこのポートを初期化して注入するだけとし、`scratch-gui` と `turbowarp-plus-editor` に別のキャッシュロジックを実装しないでください。
 
+### そのバイト列が誰のものか、どう手放すか
+
+キャッシュは内容アドレス方式です。キーが digest なので、2つの作品が同じ拡張を使っていても実体は
+1つで、持っていないバイト列のキーに書き込むことはできません。だから共有が安全で、同時に
+**エントリは誰のものでもありません**。もう1つのストアに「claim」を記録することで、作品ごとの
+取り分を一覧し、手放せるようにしています。バイト列を二重に持つことはありません。
+
+```js
+const cache = createIndexedDBContentCache({appURI: manifest.uri, sharedDigests: catalogDigests});
+
+await cache.listBuckets();                 // 何かを持っている作品すべてと、その量
+await cache.listBucket(manifest.uri);      // この作品が持っているもの
+await cache.listBucket(SHARED_BUCKET);     // どの作品のものでもないもの
+await cache.deleteBucket(manifest.uri);    // 手放す。他が参照していないバイト列も回収する
+```
+
+カタログの拡張は版が固定で多くの作品が共有するので、`sharedDigests` でどれか1つの作品の下に
+入らないようにします。そうしないと、最初に取得した作品が、他の全作品が使い回す容量の責任を
+負っているように見え、その作品を手放すと他がまだ使いたいバイト列まで落ちます。この集合は書き込み
+ごとに読むので、カタログの読み込みに合わせて埋めていけます。どの作品を開いているか言えないホスト
+は、すべてを shared に入れます。名前を推測するのは、無いと認めるより悪いからです。
+
+バケットを手放すと claim が落ち、**他が参照していない**バイト列だけが回収されます。2回参照されて
+いる1つの実体は残ります。もう一方の作品は失うことを求めていません。容量超過で追い出すときは
+claim も一緒に落ちるので、バケットが「もう無いもの」を並べることはありません。
+
+誰が入れたかの記録は無いので、作品を手放すとは「**その作品が名指す digest** を手放す」ことです。
+別の作品が使い回したはずのバイト列を落とす可能性があります。代償は取得1回だけですが、人に見せる
+一覧でそれ以上を約束しないようにしたいです。
+
+## 機能拡張のバイト列がどこから来るか
+
+このファミリーは、機能拡張に限らず何を保持するにも4つの形式で整理しています。どの形式かは
+**作品の作者**が決めます。
+
+| 形式 | ブラウザー（IndexedDB） | 作品（SB3） | 標準 TurboWarp |
+| --- | --- | --- | --- |
+| `remote-non-cacheable` | 残さない | 参照だけ | 開けない |
+| `remote-cacheable` | 検証した控えを残してよい | 参照だけ | 開けない |
+| `embedded-file` | 使わない | 作品が中身を持つ | 開けない |
+| `embedded-data` | 使わない | 作品が中身を持つ | **開ける** |
+
+### 作者が決めること、開く人が断れること
+
+4つはすべて作者の決定で、既に Manifest に入っています。読み込み時に残る問いはもっと狭く、
+**`remote-cacheable` の控えを、開く人が自分のブラウザーに残すかどうか**だけです。保存先は
+その人の端末なので、作者が許した範囲の中でなら下げられます。範囲の中でだけです。
+
+```js
+await loader.load(manifest, {
+    // 控えを残さない拡張の id。指定しなければ、作者が許したとおりになります。
+    declineCaching: new Set(['someextension'])
+});
+```
+
+Map ではなく Set なのは、これが**断ることしかできない**からです。`remote-non-cacheable` は
+禁止であり、書ける反対がありません。作者には開く人から見えない理由があります——控えがあると、
+URL が固定したバイト列を返さなくなったことを控えが尽きるまで隠してしまう。共用の機械に渡す
+作品にコードを残したくない。断るのは常に安全で、代償はせいぜい取得1回です。他の形式を名指し
+ても効果はありません。残り3つはどちらにしてもキャッシュの扱いが決まっています。
+
+断る指定は両方向に効きます。その拡張についてキャッシュを読まず、書き込みもしません。
+何も残したくないと言った人には、何も残りません。
+
+### 参照形へ戻れるかどうか
+
+embedded の `url` は、バイト列の取得元を記録します。
+
+```json
+{"type": "embedded-file", "path": "extensions/thing-<sha256>.js", "url": "https://example.test/thing.js"}
+```
+
+これは2つの働きをします。運び手が欠けたときに取得へ落ちられること、そして**参照形へ戻る道を
+残す唯一の手がかり**であること。無ければ、その作品を `remote-cacheable` へ変換することは
+二度とできません。指す先が存在しないからです。
+
+`prepareCatalogExtensionChanges` の `distribution` も同じ4つの名前を取ります。カタログの拡張は
+どこかから取得したものなので、embedded のどちらの形も、分かっている取得元を捨てずに中身の横へ
+残します。URL は、どの形で保存されていても、固定したバイト列を返すか照合します。url が省略可能
+なのは一般の場合のためで、どこからも取得していないバイト列 — コスチューム、音、エディター上で
+書いた拡張 — には記録すべき取得元がありません。
+
+## 作品を同定するもの
+
+Manifest は `uri` を持てます。その作品をダウンロードできる住所で、同時にその作品を同定するもの
+です。
+
+```json
+{"schemaVersion": 1, "uri": "https://example.test/editor/turbowarp-plus-projects/66/66aa/0193f0a1-2b3c-7d4e-8f01-2233445566aa.sb3", "extensions": []}
+```
+
+1つの作品に1つの URI。何度編集しても変わりません。だから指紋ではなく住所なのです。指紋は保存
+するたびに変わるので、ブラウザーのキャッシュも開く人の選択の記録も、触るたびに同じ作品を別名で
+綴じてしまいます。住所は中身が変わっても変わりません。
+
+`./project-authoring` の `createProjectUUID` と `defaultProjectURI` が、作者が住所を選んで
+いないときに与える住所を組みます。
+
+```js
+const uri = defaultProjectURI(location.origin + location.pathname, createProjectUUID());
+```
+
+オリジンはエディター自身のもので、配信していない host を名乗ることはありません。この住所は作品
+を人に渡すとき SB3 の中に入って一緒に移動するからです。識別子は UUID version 7 なので、初回保存
+の時刻順に並びます。2段のディレクトリは UUID の**末尾**から取ります。version 7 の先頭はミリ秒
+時計の上位で、ほとんど動かないので、先頭でシャーディングすると**作られた全作品が1つの
+ディレクトリに入ります**。
+
+この住所は意図的に不透明です。読みやすい住所はタイトル由来になり、タイトルを変えると変わるので、
+1つの作品が2つ目の名前で綴じられます。読みやすさは「公開する」という意図的な操作のもので、その
+ときは作者が自分で住所を名乗ります。人が読む一覧には、これと並べて作品のタイトルを出します。
+
+作者がそこへ公開するまで、この住所は何も返しません。それが想定どおりです。**解決しない URI は
+何も語りません。** 保存したが公開していない作品と、公開したが住所が腐った作品は、まったく同じに
+見えます。解決するかどうかで何かを決めてはいけません。まして何を消すかを決めてはいけません。
+URI は作品自身の申告で、検証していません。作品は他の住所も名乗れます。それで壊れるのは帳簿だけ
+です。キャッシュは digest をキーにしていて、ヒットごとに照合するからです。
+
 ## ソースとビルド
 
 ソースもテストも TypeScript で、`src/*.ts` と `test/*.test.ts` に置き、他の `@kubohiroya/turbowarp-*` パッケージと同じ構成にしています。`tsconfig.json` が出力なしの型検査、`tsconfig.build.json` がそれを継承して出力、`test/tsconfig.json` がテスト用の継承設定です。`npm run build`（`tsc -p tsconfig.build.json`）が ES2022 の ESM と型宣言を `dist/` に出力し、`exports`・`main`/`module`・webpack 4 用のルートファイル（`packager.js` など）はすべて `dist/` を指します。`dist/` は Git に含めず、Git 依存としてインストールされるときに `prepare` スクリプトがビルドします。npm パッケージにはビルド済みの `dist/` を含めます。webpack 4 では従来どおり `./webpack4` の Babel 設定が `dist/` を変換します。
@@ -188,7 +311,7 @@ const candidate = await prepareExtensionAddition(currentSB3, {
 
 ## 一覧からの一括設定API
 
-`./project-catalog` の `prepareCatalogExtensionChanges(currentSB3, requests, ports, options)` は、カタログの選択をまとめてSB3候補へ反映します。requestは `{id, url, distribution: 'embedded' | 'remote' | 'cached', execution: 'sandboxed' | 'unsandboxed', dependencies?, version?}` です。JS取得・SHA-256計算・依存順・全件検証・ホスト承認を共通Loaderで行い、全件承認後に `{projectBytes, manifest}` を返します。実VMには触りません。
+`./project-catalog` の `prepareCatalogExtensionChanges(currentSB3, requests, ports, options)` は、カタログの選択をまとめてSB3候補へ反映します。requestは `{id, url, distribution: 'remote-non-cacheable' | 'remote-cacheable' | 'embedded-file' | 'embedded-data', execution: 'sandboxed' | 'unsandboxed', dependencies?, version?}` です。JS取得・SHA-256計算・依存順・全件検証・ホスト承認を共通Loaderで行い、全件承認後に `{projectBytes, manifest}` を返します。実VMには触りません。
 
 既存Plus拡張の配布方式・実行モードを変える場合は、検証済みコードとSHA-256・発行者・バージョン・lockを保持します。Remote出力先が現在のコードを返さない場合、更新として勝手に追従せず拒否します。`readProjectAuthoringState(input, options)` は検証済みManifestを返し、UIの状態復元に使えます。これらの作品情報は実行許可ではありません。
 

package/README.md

@@ -12,7 +12,7 @@ npm install @kubohiroya/turbowarp-extension-loader
 
 - A schema v1 Manifest lives in `turboWarpPlus`, a non-standard field of `project.json`. This is not part of the standard SB3 specification.
 - Strict Manifest validation: unknown fields rejected, duplicate and standard extension IDs rejected, dependency ordering enforced, cyclic and missing dependencies rejected.
-- Per-extension Embedded / Remote / Cached resolution, a mandatory pinned SHA-256, UTF-8 validation, and per-code and total size limits.
+- Per-extension resolution in any of the four source forms, 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, a bounded retry of transient Remote failures, duplicate load rejection, unload, and diagnostic events.
@@ -21,17 +21,22 @@ Standard extensions, generic custom URLs and legacy Data URLs are not reinterpre
 
 ### Source forms
 
-A `source` names where one extension's bytes live, and takes one of three forms. Added in 0.2.0, `cached` names both locations at once, so a project keeps working offline without giving up a canonical published location.
+A `source` names where one extension's bytes live, as the author of the project decided. There are four forms, and they are the same four names the SB3 save format and the screen that offers the choice use, so nothing is translated between layers.
 
-| Form | Shape | Resolution order |
+| Form | Shape | Where the bytes come from |
 | --- | --- | --- |
-| `embedded` | `{type: 'embedded', path}` | the archive entry at `path` |
-| `remote` | `{type: 'remote', url}` | an HTTPS fetch of `url` |
-| `cached` | `{type: 'cached', url, path}` | the retained copy at `path`, then an HTTPS fetch of `url` |
+| `remote-non-cacheable` | `{type, url}` | an HTTPS fetch of `url`, every time |
+| `remote-cacheable` | `{type, url}` | the cache port, else an HTTPS fetch of `url` |
+| `embedded-file` | `{type, path, url?}` | the archive entry at `path`, else `url` |
+| `embedded-data` | `{type, url?}` | the `data:` carrier in the project document, else `url` |
 
-A retained copy is not a weaker source: the Manifest pins the SHA-256, so the copy either is exactly the pinned code or the load fails with `DIGEST_MISMATCH`. That is why it may be read before the network. When the entry is absent the loader reports a `retained-copy-unavailable` diagnostic and falls back to the URL, which must still serve the pinned bytes under the same redirect and final-URL policy as `remote`. `path` follows the same `extensions/*.js` policy as `embedded`, and the cache port still takes precedence over both locations.
+The two embedded forms are siblings: both make a project that runs offline, anywhere, on its own. They differ in the carrier, and the carrier decides who else can read it — `embedded-data` is what lets a standard TurboWarp host open the project without knowing this Manifest, because that host looks for a URL in the project document and the bytes are that URL.
 
-`cached` keeps `schemaVersion: 1`, so a Manifest that does not use it stays loadable by 0.1.0. A Manifest that does use it needs 0.2.0 or newer; older versions reject it with `INVALID_SOURCE` rather than loading it in a weaker form.
+A carried copy is not a weaker source: the Manifest pins the SHA-256, so the copy either is exactly the pinned code or the load fails with `DIGEST_MISMATCH`. When the carrier is missing the loader reports a `retained-copy-unavailable` diagnostic and falls back to `url` under the same redirect and final-URL policy as a reference. `path` follows the `extensions/*.js` policy.
+
+The cache is reached for `remote-cacheable` and for nothing else. An embedded project already carries the bytes, so a second copy in the browser buys nothing and the author never asked for one.
+
+The three spellings older versions used — `remote`, `cached` and `embedded` — are **refused**, each with a message naming what replaces it. The two that became a pair are not translated at all: the old name left the choice implicit and the reader is the one who has to make it.
 
 ## Host integration
 
@@ -71,7 +76,7 @@ The real VM adapter is owned by `scratch-gui/src/lib/tw-plus-extension-registrar
 - 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.
+- `./packager` provides conversion between the source forms, 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.
 - The ZIP implementation is injected through `createProjectIO({zip: JSZip})`. The core codec inspects the ZIP central directory directly and validates duplicates, paths and declared capacity before checking the real expanded size and CRC32 of the stream. An externally implemented archive port needs equivalent validation.
 
 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.
@@ -121,6 +126,130 @@ const loader = createExtensionLoader({...hostPorts, cache});
 - Fetching and storing new Remote bytes still requires a separate authorization every time. Dependent resources and external services fetched from inside the code are outside the scope of this cache.
 - The Web and Editor hosts should only initialize and inject this port, and should not implement separate cache logic in `scratch-gui` or `turbowarp-plus-editor`.
 
+### Whose bytes these are, and releasing them
+
+The cache is content-addressed: the key is the digest, so one extension that two projects both use
+is one copy, and no project can put the wrong bytes under a key it does not have the bytes for.
+That is why sharing is safe, and it is also why an entry does not belong to anyone. A second store
+records the claims, so a project's share can be listed and released without storing its bytes
+twice.
+
+```js
+const cache = createIndexedDBContentCache({appURI: manifest.uri, sharedDigests: catalogDigests});
+
+await cache.listBuckets();                 // every project that holds something, and how much
+await cache.listBucket(manifest.uri);      // what this one holds
+await cache.listBucket(SHARED_BUCKET);     // what belongs to no one project
+await cache.deleteBucket(manifest.uri);    // release it, and any bytes nothing else refers to
+```
+
+A catalog extension is pinned to a version and shared by many projects, so `sharedDigests` keeps it
+out of whichever project happened to fetch it first: that project would otherwise look responsible
+for storage every other one reuses, and releasing it would evict bytes the rest still want. The set
+is read at each write, so a host may keep filling it as its catalog loads. A host that cannot say
+which project it is opening files everything as shared, because guessing a name is worse than
+admitting there is none.
+
+Releasing a bucket drops its claims and reclaims only the bytes **nothing else refers to**. One
+copy referred to twice stays: the other project did not ask to lose it. An eviction takes the
+claims on it as well, so a bucket never lists bytes that are gone.
+
+Because there is no record of who put an entry there, releasing a project means releasing the
+digests **that project names** — which may evict bytes another project would have reused. That
+costs a fetch and nothing else, but a list shown to a person should not claim more than that.
+
+## Where an extension's bytes come from
+
+The family holds anything — extensions included — in one of four forms, and the author of the
+project decides which.
+
+| Form | Browser (IndexedDB) | Project (SB3) | Standard TurboWarp |
+| --- | --- | --- | --- |
+| `remote-non-cacheable` | nothing kept | reference only | cannot open it |
+| `remote-cacheable` | a verified copy may be kept | reference only | cannot open it |
+| `embedded-file` | not used | the project carries the bytes | cannot open it |
+| `embedded-data` | not used | the project carries the bytes | **can open it** |
+
+### What the author decides, and what the opener may decline
+
+All four are the author's decision and are already in the manifest. What is left to ask at load
+time is narrower: whether the person opening the project keeps a copy of a `remote-cacheable`
+extension in **their own** browser. Storage is their device, so they can come in under what the
+author permitted — and only under it:
+
+```js
+await loader.load(manifest, {
+    // IDs this person will not keep a copy of. Leaving it out keeps what the author permitted.
+    declineCaching: new Set(['someextension'])
+});
+```
+
+A set, not a map, because this can only ever refuse. `remote-non-cacheable` is a prohibition with
+no opposite to write: the author has reasons the opener cannot see — a kept copy hides a URL that
+stopped serving the pinned bytes until the copy runs out, and a work handed to a shared machine
+should leave no code behind. Declining is always safe; the worst it costs is a fetch. Naming
+anything else has no effect, since the other three forms reach the cache either way.
+
+Declining holds in both directions: the cache is not read for that extension and not written
+either, so a person who asked to leave nothing behind leaves nothing behind.
+
+### Where a reference can still be reached from
+
+`url` on an embedded source records where the bytes came from:
+
+```json
+{"type": "embedded-file", "path": "extensions/thing-<sha256>.js", "url": "https://example.test/thing.js"}
+```
+
+It does two things: it lets a missing carrier fall back to a fetch, and it is the only thing that
+keeps a path back to a reference form open. Without it the project can never be converted to
+`remote-cacheable` again, because there is nothing to point at.
+
+`prepareCatalogExtensionChanges` takes `distribution` as one of the same four names. A catalog
+extension was fetched from an address, so both embedded forms keep that address beside the bytes
+rather than discarding what is already known, and the URL is checked against the pinned bytes
+whichever form it is stored in. A url is optional for the general case, where bytes nobody
+fetched — a costume, a sound, an extension written in the editor — have no address to record.
+
+## What identifies one project
+
+A manifest may carry a `uri`: the address the project can be downloaded from, which is also what
+identifies it.
+
+```json
+{"schemaVersion": 1, "uri": "https://example.test/editor/turbowarp-plus-projects/66/66aa/0193f0a1-2b3c-7d4e-8f01-2233445566aa.sb3", "extensions": []}
+```
+
+One work, one URI, across every edit. That is why it is an address and not a fingerprint: a
+fingerprint changes on every save, so a browser cache and a record of what the opener chose would
+file one work under a new name each time it was touched. An address does not change when the bytes
+do.
+
+`createProjectUUID` and `defaultProjectURI` in `./project-authoring` build the address a project
+is given when its author has not chosen one:
+
+```js
+const uri = defaultProjectURI(location.origin + location.pathname, createProjectUUID());
+```
+
+The origin is the editor's own, never a host it does not serve from, because this address travels
+inside the SB3 when the work is handed on. The identifier is a UUID version 7, so it sorts by when
+the project was first saved, and the two directory levels are taken from its **end** — a version 7
+UUID begins with the top of a millisecond clock, which barely moves, so sharding on its first
+characters would put every project ever created in one directory.
+
+The address is deliberately opaque. A readable one would be derived from the title and would
+change when the title changed, filing one work under a second name; readability belongs to the
+deliberate act of publishing, where the author names the address themselves. A list meant for a
+person shows the project's title beside this.
+
+Nothing is served from the address until the author publishes there, and that is expected. **A URI
+that does not resolve says nothing**: a work saved but never published and a published work whose
+address rotted look exactly alike. Never decide anything by whether it resolves, least of all what
+to delete. The URI is also the project's own claim and is not verified — a work can name any
+address, including another's. What that can spoil is bookkeeping and nothing else, because the
+cache is keyed by digest and every hit is verified against it.
+
 ## Source and build
 
 The source and the tests are TypeScript, in `src/*.ts` and `test/*.test.ts`, laid out the same way as the other `@kubohiroya/turbowarp-*` packages: `tsconfig.json` typechecks without emitting, `tsconfig.build.json` extends it to emit, and `test/tsconfig.json` extends it for the tests. `npm run build` (`tsc -p tsconfig.build.json`) emits ES2022 ESM and type declarations to `dist/`, and `exports`, `main`/`module` and the root files used by webpack 4 (`packager.js` and the rest) all point at `dist/`. `dist/` is not committed to Git; the `prepare` script builds it when the package is installed as a Git dependency, and the npm package ships the built `dist/`. Under webpack 4, the Babel configuration in `./webpack4` transpiles `dist/` as before.
@@ -186,7 +315,7 @@ const candidate = await prepareExtensionAddition(currentSB3, {
 
 ## Bulk configuration from a catalog
 
-`prepareCatalogExtensionChanges(currentSB3, requests, ports, options)` in `./project-catalog` applies a catalog selection to an SB3 candidate in one pass. A request is `{id, url, distribution: 'embedded' | 'remote' | 'cached', execution: 'sandboxed' | 'unsandboxed', dependencies?, version?}`. JS fetching, SHA-256 computation, dependency ordering, verification of every entry and host approval all go through the shared Loader, and `{projectBytes, manifest}` is returned once every entry is approved. The real VM is untouched.
+`prepareCatalogExtensionChanges(currentSB3, requests, ports, options)` in `./project-catalog` applies a catalog selection to an SB3 candidate in one pass. A request is `{id, url, distribution: 'remote-non-cacheable' | 'remote-cacheable' | 'embedded-file' | 'embedded-data', execution: 'sandboxed' | 'unsandboxed', dependencies?, version?}`. JS fetching, SHA-256 computation, dependency ordering, verification of every entry and host approval all go through the shared Loader, and `{projectBytes, manifest}` is returned once every entry is approved. The real VM is untouched.
 
 When changing the distribution method or execution mode of an existing Plus extension, the verified code, SHA-256, publisher, version and lock are preserved. If the Remote destination does not return the current code, it is rejected rather than silently adopted as an update. `readProjectAuthoringState(input, options)` returns the verified Manifest and can be used to restore UI state. This project information is not an execution permission.
 

package/dist/index.d.ts

@@ -6,17 +6,57 @@
  * weaker source — the Manifest pins the SHA-256, so a retained copy either is exactly the pinned
  * code or the load fails, which is why it may be read before the network.
  */
+/**
+ * Where a project keeps an extension.
+ *
+ * `embedded` is the project carrying the bytes; `remote` is the project carrying only a
+ * reference. An embedded source may also record the URL the bytes came from, which is what makes
+ * falling back possible when a retained copy is missing — and is the only difference between the
+ * two forms this used to spell as separate types.
+ *
+ * A manifest written before 0.4.0 spells that same embedded source `cached`. It is refused, not
+ * translated: this family does not promise to read what older versions wrote, and a refusal
+ * names the problem where a silent translation would hide it.
+ */
+/**
+ * Where one extension's bytes live, as the author of the project decided.
+ *
+ * Four names, used unchanged by the SB3 save format and by the screen that offers the choice, so
+ * nothing has to be translated between layers. Two hold a reference and two hold the bytes:
+ *
+ * - `remote-non-cacheable` — a URL, fetched every time. Nothing is kept anywhere.
+ * - `remote-cacheable` — a URL, and a verified copy may be kept in this browser.
+ * - `embedded-file` — the bytes are a file inside the archive.
+ * - `embedded-data` — the bytes are a `data:` value in the project document, which is also what
+ *   lets a standard TurboWarp host open the project without knowing this manifest.
+ *
+ * The two embedded forms are siblings: both make a project that runs offline, anywhere, on its
+ * own. They differ in the carrier, and the carrier is what decides who else can read it.
+ *
+ * `url` on an embedded source records where the bytes came from, which is what keeps a path back
+ * to a reference open. Bytes nobody fetched — written here, or authored locally — have no origin
+ * to record, so it is optional.
+ */
+export type RemoteExtensionSource = Readonly<{
+    type: 'remote-non-cacheable' | 'remote-cacheable';
+    url: string;
+}>;
 export type ExtensionSource = Readonly<{
-    type: 'embedded';
-    path: string;
-} | {
-    type: 'remote';
+    type: 'remote-non-cacheable';
     url: string;
 } | {
-    type: 'cached';
+    type: 'remote-cacheable';
     url: string;
+} | {
+    type: 'embedded-file';
     path: string;
+    url?: string;
+} | {
+    type: 'embedded-data';
+    url?: string;
 }>;
+/** Whether the project holds a reference the loader has to fetch, rather than the bytes. */
+export declare const isRemoteSource: (source: ExtensionSource) => source is RemoteExtensionSource;
 export type ExecutionMode = 'sandboxed' | 'unsandboxed';
 export interface ExtensionSpec {
     readonly id: string;
@@ -30,6 +70,19 @@ export interface ExtensionSpec {
 }
 export interface Manifest {
     readonly schemaVersion: 1;
+    /**
+     * The address this project can be downloaded from, which is also what identifies it.
+     *
+     * One work, one URI, across every edit: it is what the browser's caches and the opener's
+     * recorded decisions are filed under, so a fingerprint would not do — that changes on every
+     * save and would file one work under a new name each time. An address does not.
+     *
+     * It is the project's own claim and is not verified. Nothing is served from it until the
+     * author actually publishes there, so a URI that does not resolve says nothing: a work saved
+     * but never published and a published work whose address rotted look exactly alike. Never
+     * decide anything, least of all what to delete, by whether it resolves.
+     */
+    readonly uri?: string;
     readonly extensions: readonly ExtensionSpec[];
 }
 export interface ResolvedCode extends ExtensionSpec {
@@ -52,6 +105,16 @@ export interface AuthorizedCode extends ResolvedCode {
 }
 export interface OperationOptions {
     signal?: AbortSignal;
+    /**
+     * Extension IDs the person opening the project will not keep a copy of in this browser.
+     *
+     * The author sets the ceiling and the opener may come in under it, so this can only ever
+     * refuse. A set says that in the type: there is no way to write "cache this anyway" for a
+     * source the author marked `remote-non-cacheable`, and declining is always safe — the worst
+     * it costs is a fetch. Naming anything else has no effect: `remote-non-cacheable` keeps
+     * nothing already, and embedded bytes travel with the project.
+     */
+    declineCaching?: ReadonlySet<string>;
 }
 export interface ReadOptions {
     signal: AbortSignal;
@@ -99,8 +162,15 @@ export type DiagnosticEvent = Readonly<{
     code?: string;
 }>;
 export interface LoaderPorts {
+    /**
+     * The two embedded carriers, each reached the way it is addressed: a file by its path, a
+     * `data:` value by the extension's ID, because the manifest entry already carries one and
+     * writing the value into the manifest as well would put the bytes in the project twice.
+     * A host implements the carriers it can reach; a source needing the other one fails.
+     */
     embeddedReader?: {
-        read(path: string, options: ReadOptions): Promise<Uint8Array>;
+        read?(path: string, options: ReadOptions): Promise<Uint8Array>;
+        readData?(id: string, options: ReadOptions): Promise<Uint8Array>;
     };
     fetcher?: FetchPort;
     trustProvider: {