@kubohiroya/sb3-toolchain 0.6.0 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.ja.md CHANGED
@@ -31,7 +31,7 @@ Scratch 3およびTurboWarpの`.sb3`プロジェクトを、Gitで差分を確
31
31
  再現可能なインストールのため、検証済みのnpmバージョンを固定します。
32
32
 
33
33
  ```bash
34
- pnpm add --save-dev --save-exact @kubohiroya/sb3-toolchain@0.6.0
34
+ pnpm add --save-dev --save-exact @kubohiroya/sb3-toolchain@0.8.0
35
35
  ```
36
36
 
37
37
  ## クイックスタート
package/README.md CHANGED
@@ -32,7 +32,7 @@ expanded sources and rebuilding bit-for-bit identical SB3 files from the same in
32
32
  Pin the verified npm version for reproducible installation.
33
33
 
34
34
  ```bash
35
- pnpm add --save-dev --save-exact @kubohiroya/sb3-toolchain@0.6.0
35
+ pnpm add --save-dev --save-exact @kubohiroya/sb3-toolchain@0.8.0
36
36
  ```
37
37
 
38
38
  ## Quick start
@@ -22,7 +22,7 @@ flowchart LR
22
22
  subgraph Output["Generated bundled SB3"]
23
23
  BundledProject["project.json<br/>namespaced opcodes"]
24
24
  Composite["one composite extension<br/>one register() call"]
25
- Capsule["recovery capsule<br/>original extension data"]
25
+ Capsule["optional recovery capsule<br/>original extension data"]
26
26
  end
27
27
 
28
28
  TurboWarp["TurboWarp Editor<br/>one permission prompt"]
@@ -38,8 +38,7 @@ flowchart LR
38
38
  ```
39
39
 
40
40
  The expanded source always retains the individual extensions. Bundling changes only the generated
41
- SB3, and the recovery capsule makes that generated artifact reversible when its safety conditions
42
- remain satisfied.
41
+ SB3. Recovery data is opt-in when direct restoration from that generated artifact is required.
43
42
 
44
43
  ## What problem it solves
45
44
 
@@ -74,7 +73,7 @@ extension to authorize and load.
74
73
  | Create one composite runtime extension from several members | Disable or bypass TurboWarp's permission prompt |
75
74
  | Rewrite generated project references to collision-free namespaces | Rewrite the authoritative source project in place |
76
75
  | Preserve and delegate each member's original implementation | Flatten all member classes into one manually merged class |
77
- | Embed recovery data for direct SB3 unbundling | Guarantee compatibility for arbitrary dynamic extension code |
76
+ | Optionally embed recovery data for direct SB3 unbundling | Guarantee compatibility for arbitrary dynamic extension code |
78
77
  | Reject transformations that cannot be classified safely | Execute extension JavaScript during the build |
79
78
 
80
79
  ## Internal architecture
@@ -147,7 +146,7 @@ projectbundle.js
147
146
  │ ├── generated palette headings and separators
148
147
  │ └── handlers that delegate to captured member instances
149
148
  ├── one real Scratch.extensions.register() call
150
- └── SB3-Toolchain-Reversible-Bundle-v1 recovery capsule
149
+ └── optional SB3-Toolchain-Reversible-Bundle-v1 recovery capsule
151
150
  ```
152
151
 
153
152
  The original scripts still execute their normal initialization code at runtime. Their calls to
@@ -262,6 +261,13 @@ metadata:
262
261
  }
263
262
  ```
264
263
 
264
+ For every ordinary block that does not already define its own `blockIconURI`, the bundle copies the
265
+ member's top-level `getInfo().blockIconURI` onto the transformed block. TurboWarp supports
266
+ `blockIconURI` at block level, so blocks keep their originating extension's icon even though the
267
+ bundle is registered as one extension. A block-specific icon always wins, and members without an
268
+ icon keep the previous icon-free output. Generated headings, documentation buttons, member LABELs,
269
+ and member BUTTONs are not given an inherited icon.
270
+
265
271
  When a member's `getInfo()` returns a non-empty string [`docsURI`](https://docs.turbowarp.org/development/extensions/assorted-apis#docsuri),
266
272
  the bundle inserts an `Open Documentation` button immediately after that member's heading. It uses TurboWarp's native
267
273
  `OPEN_EXTENSION_DOCS` callback, so it preserves the normal `docsURI` behavior instead of delegating
@@ -345,9 +351,14 @@ Only `projectbundle` appears in `extensions` and `extensionURLs`, and the genera
345
351
  `Scratch.extensions.register` once. The initial comments in that JavaScript list every member's
346
352
  name, ID, author, description, and license so the user can inspect them before granting permission.
347
353
 
348
- The end of the JavaScript contains an `SB3-Toolchain-Reversible-Bundle-v1` recovery capsule. The
349
- capsule records each original member data URL, member order, and the original `extensions` and
350
- `extensionURLs` order.
354
+ By default, the JavaScript omits duplicate recovery data. First confirm that every member license
355
+ permits modification and combination, and keep all required notices and corresponding source
356
+ available. The bundle header, member code, block icons, opcode namespaces, and storage behavior are
357
+ unchanged.
358
+
359
+ Set `"recoveryCapsule": true` on a bundle, or pass `--include-recovery-capsule` while configuring it,
360
+ to append an `SB3-Toolchain-Reversible-Bundle-v1` capsule. It records each original member data URL,
361
+ member order, and the original `extensions` and `extensionURLs` order, at the cost of a larger output.
351
362
 
352
363
  ## Restore from expanded source
353
364
 
@@ -394,8 +405,9 @@ accidentally.
394
405
 
395
406
  ## Restore a bundled SB3 directly
396
407
 
397
- A bundled SB3 containing a recovery capsule can be unbundled without the expanded source. The
398
- command is a dry run unless `--yes` is supplied.
408
+ A bundled SB3 containing an explicitly enabled recovery capsule can be unbundled without the expanded
409
+ source. The default compact bundle must instead be restored from its authoritative expanded source.
410
+ The command is a dry run unless `--yes` is supplied.
399
411
 
400
412
  ```bash
401
413
  sb3-toolchain extensions unbundle \
@@ -446,8 +458,9 @@ flowchart TD
446
458
  The tool refuses the operation without modifying the output instead of guessing when any of the
447
459
  following conditions apply:
448
460
 
449
- - The target data URL has no `SB3-Toolchain-Reversible-Bundle-v1` capsule because the bundle was
450
- produced before recovery capsules were introduced, by another tool, or by hand
461
+ - The target data URL has no `SB3-Toolchain-Reversible-Bundle-v1` capsule because recovery was not
462
+ explicitly enabled, the bundle was produced before recovery capsules were introduced, or it was
463
+ produced by another tool or by hand
451
464
  - The bundle data URL or capsule was removed, corrupted, or duplicated; its format version is not
452
465
  supported; or its bundle ID, member ID, and original JavaScript header ID do not agree
453
466
  - The ID set or order in `project.extensions` or `extensionURLs` changed after bundling. For example,
@@ -21,7 +21,7 @@ flowchart LR
21
21
  subgraph Output["生成されたbundle済みSB3"]
22
22
  BundledProject["project.json<br/>名前空間化されたopcode"]
23
23
  Composite["1つの複合機能拡張<br/>1回のregister()呼び出し"]
24
- Capsule["復元カプセル<br/>元の機能拡張データ"]
24
+ Capsule["任意の復元カプセル<br/>元の機能拡張データ"]
25
25
  end
26
26
 
27
27
  TurboWarp["TurboWarp Editor<br/>1回の権限確認"]
@@ -36,8 +36,8 @@ flowchart LR
36
36
  Composite --> TurboWarp
37
37
  ```
38
38
 
39
- 展開ソースには、常に個別機能拡張が保持されます。bundleによって変わるのは生成SB3だけです。安全条件を満たす
40
- 間は、復元カプセルによって生成成果物を元に戻せます。
39
+ 展開ソースには、常に個別機能拡張が保持されます。bundleによって変わるのは生成SB3だけです。生成成果物から
40
+ 直接復元する必要がある場合に限り、復元データを明示的に追加します。
41
41
 
42
42
  ## 解決する問題
43
43
 
@@ -71,7 +71,7 @@ flowchart LR
71
71
  | 複数メンバーから1つの複合ランタイム機能拡張を作成 | TurboWarpの権限確認を無効化または回避 |
72
72
  | 生成プロジェクトの参照を衝突しない名前空間へ書き換え | 信頼できる情報源であるプロジェクトを直接書き換え |
73
73
  | 各メンバーの元の実装を保持して処理を委譲 | すべてのメンバークラスを手作業で1クラスへ平坦化 |
74
- | SB3を直接unbundleするための復元データを埋め込み | 任意の動的な機能拡張コードに対する互換性を保証 |
74
+ | SB3を直接unbundleする復元データを任意で埋め込み | 任意の動的な機能拡張コードに対する互換性を保証 |
75
75
  | 安全に分類できない変換を拒否 | ビルド中に機能拡張JavaScriptを実行 |
76
76
 
77
77
  ## 内部アーキテクチャ
@@ -144,7 +144,7 @@ projectbundle.js
144
144
  │ ├── 生成されたパレット見出しとseparator
145
145
  │ └── 捕捉したメンバーインスタンスへ委譲するhandler
146
146
  ├── 実際のScratch.extensions.register()呼び出し1回
147
- └── SB3-Toolchain-Reversible-Bundle-v1復元カプセル
147
+ └── 任意のSB3-Toolchain-Reversible-Bundle-v1復元カプセル
148
148
  ```
149
149
 
150
150
  元のスクリプトは、ランタイムで通常の初期化コードを引き続き実行します。各スクリプトの
@@ -254,6 +254,13 @@ TurboWarp Editorのパレットでは、各グループが次の形式の装飾
254
254
  }
255
255
  ```
256
256
 
257
+ 各通常ブロックが独自の`blockIconURI`を持たない場合、bundleはメンバーのトップレベル
258
+ `getInfo().blockIconURI`を変換後のブロックへコピーします。TurboWarpはブロック単位の
259
+ `blockIconURI`に対応しているため、1つの機能拡張として登録されたbundleでも、各ブロックは由来元の
260
+ 機能拡張アイコンを保持します。ブロック固有アイコンが常に優先され、アイコンを持たないメンバーの出力は
261
+ 従来どおりです。生成見出し、ドキュメントボタン、メンバーのLABEL、メンバーのBUTTONには継承アイコンを
262
+ 設定しません。
263
+
257
264
  メンバーの`getInfo()`が空でない文字列[`docsURI`](https://docs.turbowarp.org/development/extensions/assorted-apis#docsuri)を返す場合、
258
265
  bundleはそのメンバー見出しの直後に`Open Documentation`ボタンを挿入します。機能拡張コードへの委譲ではなく、TurboWarp標準の
259
266
  `OPEN_EXTENSION_DOCS` callbackを使用するため、通常の`docsURI`と同じ動作を保持します。生成ボタンには別の
@@ -335,8 +342,13 @@ bundleの読み込みを拒否します。
335
342
  `Scratch.extensions.register`を1回呼び出します。そのJavaScriptの先頭コメントには全メンバーの名前、ID、
336
343
  作者、説明、ライセンスが列挙され、ユーザーは権限を許可する前に確認できます。
337
344
 
338
- JavaScriptの末尾には`SB3-Toolchain-Reversible-Bundle-v1`復元カプセルが含まれます。カプセルは各メンバーの
339
- 元のdata URL、メンバー順、元の`extensions`と`extensionURLs`の順序を記録します。
345
+ 既定では、JavaScriptから重複する復元データを省略します。すべてのメンバーライセンスが改変と結合を許可する
346
+ ことを先に確認し、必要な通知と対応ソースを利用可能な状態で保持してください。bundleヘッダー、メンバーコード、
347
+ ブロックアイコン、opcode名前空間、ストレージ動作は変わりません。
348
+
349
+ bundleに`"recoveryCapsule": true`を指定するか、設定時に`--include-recovery-capsule`を渡すと、末尾に
350
+ `SB3-Toolchain-Reversible-Bundle-v1`カプセルを追加します。カプセルは各メンバーの元のdata URL、メンバー順、
351
+ 元の`extensions`と`extensionURLs`の順序を記録しますが、出力サイズは増加します。
340
352
 
341
353
  ## 展開ソースからの復元
342
354
 
@@ -381,8 +393,8 @@ sb3-toolchain build app --output dist/project.sb3 --yes
381
393
 
382
394
  ## bundle済みSB3の直接復元
383
395
 
384
- 復元カプセルを含むbundle済みSB3は、展開ソースがなくてもunbundleできます。`--yes`を指定しない限り、
385
- コマンドはdry runです。
396
+ 明示的に復元カプセルを含めたbundle済みSB3は、展開ソースがなくてもunbundleできます。既定のcompact bundleは、
397
+ 信頼できる展開ソースから復元する必要があります。`--yes`を指定しない限り、コマンドはdry runです。
386
398
 
387
399
  ```bash
388
400
  sb3-toolchain extensions unbundle \
@@ -431,8 +443,8 @@ flowchart TD
431
443
 
432
444
  次のいずれかの条件に該当する場合、ツールは推測せず、出力を変更せずに操作を拒否します。
433
445
 
434
- - 対象data URLに`SB3-Toolchain-Reversible-Bundle-v1`カプセルがない。復元カプセル導入前、別のツール、
435
- または手作業でbundleが生成された場合が該当する
446
+ - 対象data URLに`SB3-Toolchain-Reversible-Bundle-v1`カプセルがない。復元を明示的に有効化していない、
447
+ 復元カプセル導入前、別のツール、または手作業でbundleが生成された場合が該当する
436
448
  - bundle data URLまたはカプセルが削除、破損、重複している、形式バージョンが未対応、またはbundle ID、
437
449
  メンバーID、元のJavaScriptヘッダーIDが一致しない
438
450
  - bundle後に`project.extensions`または`extensionURLs`内のID集合や順序が変わった。たとえば別の機能拡張を
@@ -167,15 +167,19 @@ APIマニフェストファイルは展開ソースの検証入力であり、SB
167
167
  - `members`: 2つ以上の個別機能拡張ID。順序によってブロックとメニューの合成順が決まる。パレットでは、
168
168
  メタデータを持つ装飾済みbundle LABEL見出しとグループ間の二重separatorが追加される一方、元の機能拡張の
169
169
  LABELエントリとseparatorは変更されない
170
+ - `recoveryCapsule`: 任意の真偽値で、既定値は`false`。追加サイズを許容でき、生成SB3単体からの直接unbundleが
171
+ 必要な場合に限り`true`を指定する
170
172
 
171
173
  1つのメンバーを複数のbundleに所属させることはできません。個別エントリ、個別JavaScript、`source`、
172
174
  `project.source.json`が引き続き信頼できる情報源です。`build`は各元opcodeに`memberId + "__"`を加え、
173
175
  出力側の`project.json`のopcode、`extensions`、`extensionURLs`、機能拡張ストレージだけをbundle IDに変更します。
174
176
  埋め込まれるbundle JavaScriptのdata URLは1つです。
175
177
 
176
- bundle JavaScriptの末尾には、元の個別data URLと機能拡張の順序を格納した形式1の復元カプセルが含まれます。
177
- 設定を削除するか、そのカプセルを含む生成SB3に対して`extensions unbundle`を実行すると、通常の出力へ
178
- 復元できます。互換性契約と復元手順については、[`extension-bundles.md`](extension-bundles.md)を参照してください。
178
+ 既定では、メンバーコードとヘッダー通知を生成JavaScriptに残したまま、重複する復元データを省略します。
179
+ `recoveryCapsule: true`では、元の個別data URLと機能拡張の順序を格納した形式1のカプセルを追加します。
180
+ 設定を削除すれば展開ソースから常に通常出力へ戻せますが、生成SB3を直接`extensions unbundle`するには
181
+ カプセルが必要です。互換性契約と復元手順については、
182
+ [`extension-bundles.md`](extension-bundles.md)を参照してください。
179
183
 
180
184
  ## アセット
181
185
 
@@ -172,15 +172,17 @@ only in the generated SB3.
172
172
  - `id`: composite extension ID in TurboWarp's `[a-z0-9]+` form that does not collide with an individual extension
173
173
  - `name`: single-line name displayed in the permission prompt and extension category
174
174
  - `members`: two or more individual extension IDs; their order defines block and menu composition order. The palette receives a decorated, metadata-bearing bundle LABEL heading and a double separator between groups, while LABEL entries and separators from the original extensions remain unchanged
175
+ - `recoveryCapsule`: optional boolean, default `false`. Set it to `true` only when the extra size is acceptable and direct unbundling from the generated SB3 is required
175
176
 
176
177
  A member cannot belong to more than one bundle. Individual entries, individual JavaScript, `source`,
177
178
  and `project.source.json` remain authoritative. `build` adds `memberId + "__"` to each original opcode
178
179
  and changes only the output `project.json` opcodes, `extensions`, `extensionURLs`, and extension storage
179
180
  to the bundle ID. It embeds one bundle JavaScript data URL.
180
181
 
181
- The end of the bundle JavaScript contains a format 1 recovery capsule with the original individual
182
- data URLs and extension order. Removing the configuration or running `extensions unbundle` against a
183
- generated SB3 containing that capsule restores the ordinary output. See
182
+ By default, the bundle omits duplicate recovery data while leaving member code and header notices in
183
+ the generated JavaScript. `recoveryCapsule: true` adds a format 1 capsule with the original individual
184
+ data URLs and extension order. Removing the configuration always restores the ordinary output from
185
+ expanded source; direct `extensions unbundle` of the generated SB3 requires the capsule. See
184
186
  [`extension-bundles.md`](extension-bundles.md) for the compatibility contract and restoration steps.
185
187
 
186
188
  ## Assets
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kubohiroya/sb3-toolchain",
3
- "version": "0.6.0",
3
+ "version": "0.8.0",
4
4
  "description": "Git-friendly source management and deterministic builds for Scratch 3 and TurboWarp SB3 projects",
5
5
  "type": "module",
6
6
  "license": "MPL-2.0",
package/src/cli.js CHANGED
@@ -33,7 +33,7 @@ export function usage() {
33
33
  sb3-toolchain extensions sync SOURCE_DIR [--yes]
34
34
  sb3-toolchain extensions update SOURCE_DIR [EXTENSION_ID] [--migrate-id NEW_ID] [--artifact PATH] [--api-manifest-artifact PATH] [--allow-breaking-api --yes]
35
35
  sb3-toolchain extensions migrate-id SOURCE_DIR --from OLD_ID --to NEW_ID [--yes]
36
- sb3-toolchain extensions bundle SOURCE_DIR --id BUNDLE_ID --name NAME [EXTENSION_ID ...] [--yes]
36
+ sb3-toolchain extensions bundle SOURCE_DIR --id BUNDLE_ID --name NAME [EXTENSION_ID ...] [--include-recovery-capsule] [--yes]
37
37
  sb3-toolchain extensions unbundle SOURCE_DIR BUNDLE_ID [--yes]
38
38
  sb3-toolchain extensions unbundle INPUT.sb3 BUNDLE_ID --output OUTPUT.sb3 [--yes]
39
39
 
@@ -293,6 +293,7 @@ function parseExtensionIdMigrationArguments(arguments_) {
293
293
  function parseExtensionBundleArguments(arguments_) {
294
294
  let bundleId;
295
295
  let bundleName;
296
+ let recoveryCapsule = false;
296
297
  let sourceDirectory;
297
298
  const extensionIds = [];
298
299
  let yes = false;
@@ -307,6 +308,8 @@ function parseExtensionBundleArguments(arguments_) {
307
308
  index += 1;
308
309
  } else if (argument === '--yes') {
309
310
  yes = true;
311
+ } else if (argument === '--include-recovery-capsule') {
312
+ recoveryCapsule = true;
310
313
  } else {
311
314
  assert(!argument.startsWith('-'), `Unknown option: ${argument}`);
312
315
  if (!sourceDirectory) {
@@ -329,6 +332,7 @@ function parseExtensionBundleArguments(arguments_) {
329
332
  bundleName,
330
333
  command: 'extensions',
331
334
  extensionIds,
335
+ recoveryCapsule,
332
336
  sourceDirectory,
333
337
  yes,
334
338
  };
@@ -598,6 +602,7 @@ export async function runCli(
598
602
  bundleId: options.bundleId,
599
603
  bundleName: options.bundleName,
600
604
  extensionIds: options.extensionIds,
605
+ recoveryCapsule: options.recoveryCapsule,
601
606
  sourceDirectory: options.sourceDirectory,
602
607
  yes: options.yes,
603
608
  });
package/src/constants.js CHANGED
@@ -1,4 +1,4 @@
1
1
  // SPDX-License-Identifier: MPL-2.0
2
2
 
3
3
  export const packageName = '@kubohiroya/sb3-toolchain';
4
- export const packageVersion = '0.6.0';
4
+ export const packageVersion = '0.8.0';
@@ -56,11 +56,13 @@ async function configurationContext({
56
56
  bundleId,
57
57
  bundleName,
58
58
  extensionIds,
59
+ recoveryCapsule,
59
60
  sourceDirectory,
60
61
  willReplace,
61
62
  }) {
62
63
  validateBundleId(bundleId);
63
64
  validateBundleName(bundleName);
65
+ assert(typeof recoveryCapsule === 'boolean', 'recoveryCapsule must be a boolean.');
64
66
  const source = await inspectConfigurationSource(sourceDirectory, willReplace);
65
67
  const extensionManifest = await readExtensionManifest(source);
66
68
  const existingBundles = validateExtensionBundleConfigurations(
@@ -81,7 +83,12 @@ async function configurationContext({
81
83
  const candidateManifest = structuredClone(extensionManifest);
82
84
  candidateManifest.extensionBundles = [
83
85
  ...existingBundles,
84
- {id: bundleId, members, name: bundleName},
86
+ {
87
+ id: bundleId,
88
+ members,
89
+ name: bundleName,
90
+ ...(recoveryCapsule === true ? {recoveryCapsule: true} : {}),
91
+ },
85
92
  ];
86
93
  const extensionBundles = validateExtensionBundleConfigurations(
87
94
  candidateManifest.extensionBundles,
@@ -97,11 +104,18 @@ async function configurationContext({
97
104
  return {buildPlan, candidateManifest, configuredBundle, extensionManifest, source};
98
105
  }
99
106
 
100
- export async function planExtensionBundle({bundleId, bundleName, extensionIds, sourceDirectory}) {
107
+ export async function planExtensionBundle({
108
+ bundleId,
109
+ bundleName,
110
+ extensionIds,
111
+ recoveryCapsule = false,
112
+ sourceDirectory,
113
+ }) {
101
114
  const context = await configurationContext({
102
115
  bundleId,
103
116
  bundleName,
104
117
  extensionIds,
118
+ recoveryCapsule,
105
119
  sourceDirectory,
106
120
  willReplace: false,
107
121
  });
@@ -113,6 +127,7 @@ export async function planExtensionBundle({bundleId, bundleName, extensionIds, s
113
127
  components: context.configuredBundle.components.map((component) => component.metadata),
114
128
  counts: context.configuredBundle.counts,
115
129
  members: [...context.configuredBundle.bundle.members],
130
+ recoveryCapsule: context.configuredBundle.bundle.recoveryCapsule === true,
116
131
  sourceDirectory: context.source.resolvedSourceDirectory,
117
132
  };
118
133
  }
@@ -176,6 +191,7 @@ export async function bundleExtensions({
176
191
  bundleId,
177
192
  bundleName,
178
193
  extensionIds,
194
+ recoveryCapsule = false,
179
195
  sourceDirectory,
180
196
  yes = false,
181
197
  }) {
@@ -183,6 +199,7 @@ export async function bundleExtensions({
183
199
  bundleId,
184
200
  bundleName,
185
201
  extensionIds,
202
+ recoveryCapsule,
186
203
  sourceDirectory,
187
204
  willReplace: yes,
188
205
  });
@@ -192,6 +209,7 @@ export async function bundleExtensions({
192
209
  components: context.configuredBundle.components.map((component) => component.metadata),
193
210
  counts: context.configuredBundle.counts,
194
211
  members: [...context.configuredBundle.bundle.members],
212
+ recoveryCapsule: context.configuredBundle.bundle.recoveryCapsule === true,
195
213
  sourceDirectory: context.source.resolvedSourceDirectory,
196
214
  };
197
215
  if (!yes) {
@@ -55,6 +55,10 @@ export function validateExtensionBundleConfigurations(extensionBundles, extensio
55
55
  Array.isArray(bundle.members) && bundle.members.length >= 2,
56
56
  `Extension bundle ${bundle.id} must contain at least two members.`,
57
57
  );
58
+ assert(
59
+ bundle.recoveryCapsule === undefined || typeof bundle.recoveryCapsule === 'boolean',
60
+ `Extension bundle ${bundle.id} recoveryCapsule must be a boolean when present.`,
61
+ );
58
62
 
59
63
  const localMemberIds = new Set();
60
64
  for (const memberId of bundle.members) {
@@ -74,7 +78,12 @@ export function validateExtensionBundleConfigurations(extensionBundles, extensio
74
78
  localMemberIds.add(memberId);
75
79
  bundledMemberIds.add(memberId);
76
80
  }
77
- return {id: bundle.id, members: [...bundle.members], name: bundle.name};
81
+ return {
82
+ id: bundle.id,
83
+ members: [...bundle.members],
84
+ name: bundle.name,
85
+ ...(bundle.recoveryCapsule === undefined ? {} : {recoveryCapsule: bundle.recoveryCapsule}),
86
+ };
78
87
  });
79
88
  }
80
89
 
@@ -359,6 +368,10 @@ ${loaders}
359
368
  throw new Error('Static bundle member ' + componentId + ' must have a non-empty name.');
360
369
  }
361
370
  const namespace = componentId + '__';
371
+ const memberBlockIconURI =
372
+ typeof info.blockIconURI === 'string' && info.blockIconURI.length > 0
373
+ ? info.blockIconURI
374
+ : null;
362
375
  const customFieldTypes = info.customFieldTypes || {};
363
376
  for (const [fieldName, fieldInfo] of Object.entries(customFieldTypes)) {
364
377
  result.customFieldTypes[namespace + fieldName] = fieldInfo;
@@ -391,6 +404,14 @@ ${loaders}
391
404
  throw new Error('XML blocks are unsupported in static bundle member ' + componentId + '.');
392
405
  }
393
406
  const transformed = {...block};
407
+ if (
408
+ memberBlockIconURI !== null &&
409
+ !Object.prototype.hasOwnProperty.call(block, 'blockIconURI') &&
410
+ block.blockType !== Scratch.BlockType.LABEL &&
411
+ block.blockType !== Scratch.BlockType.BUTTON
412
+ ) {
413
+ transformed.blockIconURI = memberBlockIconURI;
414
+ }
394
415
  if (block.arguments) {
395
416
  transformed.arguments = Object.fromEntries(
396
417
  Object.entries(block.arguments).map(([argumentName, argument]) => {
@@ -461,6 +482,9 @@ ${loaders}
461
482
  Scratch.extensions.register(new StaticExtensionBundle());
462
483
  })(Scratch);
463
484
  `;
485
+ if (bundle.recoveryCapsule !== true) {
486
+ return Buffer.from(`${header}\n${runtime}`);
487
+ }
464
488
  const capsule = Buffer.from(
465
489
  JSON.stringify(
466
490
  recoveryCapsule(