@kubohiroya/sb3-toolchain 0.1.0 → 0.2.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.md CHANGED
@@ -1,95 +1,48 @@
1
1
  # sb3-toolchain
2
2
 
3
- Scratch 3/TurboWarpの`.sb3`をGit差分可能な展開ソースとして管理し、同じ入力から
4
- bit-for-bitで同一のSB3を再生成するNode.jsツールチェーンです。
3
+ A Node.js toolchain for managing Scratch 3 and TurboWarp `.sb3` projects as Git-diffable
4
+ expanded sources and rebuilding bit-for-bit identical SB3 files from the same input.
5
5
 
6
- ## 主な機能
6
+ ## Features
7
7
 
8
- - SB3を整形済み`project.source.json`、アセット、埋め込み拡張へ安全に展開
9
- - アセット参照、MD5、ZIPエントリ、埋め込み拡張対応を検証
10
- - GitHub由来の埋め込み拡張についてcommitとSHA-256を記録し、オフラインで検証
11
- - ZIPエントリ順、タイムスタンプ、圧縮条件を固定した決定的ビルド
12
- - Git管理中の未コミット変更を保護したimport
13
- - 既存出力を保護する原子的な置換とロールバック
14
- - CLIとJavaScript API
8
+ - Safely expand an SB3 into formatted `project.source.json`, assets, and embedded extensions
9
+ - Validate asset references, MD5 hashes, ZIP entries, and embedded extension mappings
10
+ - Record commits and SHA-256 hashes for GitHub-hosted embedded extensions and verify them offline
11
+ - Statically bundle multiple extensions into one permission unit without deleting their original
12
+ JavaScript, then restore them from either the expanded source or the bundled SB3
13
+ - Produce deterministic builds with fixed ZIP entry order, timestamps, and compression settings
14
+ - Protect uncommitted Git changes when importing
15
+ - Protect existing output through transactional replacement and rollback
16
+ - Provide both a CLI and a JavaScript API
15
17
 
16
- TMPose紙芝居の台本変換、特定作品のデータ、TurboWarp PackagerによるWebアプリ生成は
17
- このパッケージの対象外です。
18
+ TMPose kamishibai script conversion, project-specific data, and web application generation with
19
+ TurboWarp Packager are outside the scope of this package.
18
20
 
19
- ## 必要な環境
21
+ ## Requirements
20
22
 
21
- - Node.js 22.12.0以上
23
+ - Node.js 22.12.0 or later
22
24
  - pnpm 11
23
25
 
24
- ## インストール
26
+ ## Installation
25
27
 
26
- リリースタグを固定してインストールします。公開前の例では`VERSION`を利用するタグへ
27
- 置き換えてください。
28
+ Pin the verified npm version for reproducible installation.
28
29
 
29
30
  ```bash
30
- pnpm add --save-dev github:kubohiroya/sb3-toolchain#VERSION
31
+ pnpm add --save-dev --save-exact @kubohiroya/sb3-toolchain@0.2.0
31
32
  ```
32
33
 
33
- ## CLI
34
+ ## Quick start
34
35
 
35
- TurboWarpで保存したSB3を展開します。
36
+ Expand an SB3 saved by TurboWarp, validate it, and rebuild it.
36
37
 
37
38
  ```bash
38
39
  sb3-toolchain import tmp/project.sb3 --output app
39
- ```
40
-
41
- 展開ソースを検証します。
42
-
43
- ```bash
44
40
  sb3-toolchain check app
45
- ```
46
-
47
- 決定的なSB3を生成します。
48
-
49
- ```bash
50
41
  sb3-toolchain build app --output dist/project.sb3
51
42
  ```
52
43
 
53
- 管理対象の埋め込み拡張について、追跡中のGitHub refに更新があるか確認します。
54
-
55
- ```bash
56
- sb3-toolchain extensions status app
57
- ```
58
-
59
- 記録済みの固定commitから実ファイルを復元します。refは解決せず、メタデータも変更しません。
60
-
61
- ```bash
62
- sb3-toolchain extensions sync app
63
- ```
64
-
65
- 追跡中のrefを最新commitへ解決し、成果物と`resolvedCommit`/`integrity`を更新します。
66
- IDを省略すると、すべての管理対象拡張を一つのtransactionとして更新します。
67
-
68
- ```bash
69
- sb3-toolchain extensions update app
70
- sb3-toolchain extensions update app example
71
- ```
72
-
73
- 読み込み済みの拡張IDを変更する場合は、まずdry-runで分類済みの変更件数と、変更しない
74
- 未分類参照を確認します。`--yes`を付けたときだけ適用します。
75
-
76
- ```bash
77
- sb3-toolchain extensions migrate-id app --from oldId --to newid
78
- sb3-toolchain extensions migrate-id app --from oldId --to newid --yes
79
- ```
80
-
81
- GitHub管理対象では、新IDを宣言する新しい成果物の取得とID移行を一つのtransactionにします。
82
- リモートの成果物パスも変わる場合は`--artifact`で明示します。
83
-
84
- ```bash
85
- sb3-toolchain extensions update app oldId \
86
- --migrate-id newid \
87
- --artifact dist/newid.js
88
- ```
89
-
90
- 既存出力と内容が同じ場合は更新時刻を変えません。異なる既存出力の置換には対話確認
91
- または`--yes`が必要です。import先に未コミット変更がある場合、`--yes`だけでは置換せず、
92
- 明示的な`--discard-local-changes`も要求します。
44
+ See [`docs/workflows.md`](docs/workflows.md) for the recommended source-of-truth, re-import,
45
+ replacement protection, extension update, and CI workflows for a project repository.
93
46
 
94
47
  ## JavaScript API
95
48
 
@@ -98,6 +51,7 @@ import {readFile} from 'node:fs/promises';
98
51
 
99
52
  import {
100
53
  buildSb3,
54
+ bundleExtensions,
101
55
  createDeterministicSb3,
102
56
  extensionIntegrity,
103
57
  extensionStatus,
@@ -105,6 +59,8 @@ import {
105
59
  migrateExtensionId,
106
60
  planExtensionIdMigration,
107
61
  syncExtensions,
62
+ unbundleSb3,
63
+ unbundleExtensions,
108
64
  updateExtensions,
109
65
  validateSb3Source,
110
66
  } from '@kubohiroya/sb3-toolchain';
@@ -145,43 +101,44 @@ await updateExtensions({
145
101
  sourceArtifact: 'dist/newid.js',
146
102
  yes: true,
147
103
  });
104
+ await bundleExtensions({
105
+ sourceDirectory: 'app',
106
+ bundleId: 'projectbundle',
107
+ bundleName: 'Project Extension Bundle',
108
+ extensionIds: ['extensionone', 'extensiontwo'],
109
+ yes: true,
110
+ });
111
+ await unbundleExtensions({
112
+ sourceDirectory: 'app',
113
+ bundleId: 'projectbundle',
114
+ yes: true,
115
+ });
116
+ await unbundleSb3({
117
+ inputPath: 'dist/project.sb3',
118
+ outputPath: 'dist/project.unbundled.sb3',
119
+ bundleId: 'projectbundle',
120
+ yes: true,
121
+ });
148
122
  ```
149
123
 
150
- ## 管理対象の埋め込み拡張
151
-
152
- `embedded-extensions.json`の拡張エントリには、任意の`source`メタデータとして
153
- GitHubリポジトリ、追跡するref、解決済みcommit、成果物パス、SHA-256を記録できます。
154
- `check`と`build`はネットワークへ接続せず、ローカルのJavaScriptが記録済みハッシュおよび
155
- `// ID: <extensionId>`ヘッダーと一致することを検証します。
156
-
157
- 既存の展開ディレクトリへSB3を再importする場合、同じIDとパスを持つ拡張の`source`は
158
- 維持されます。SB3内の実ファイルが記録済みの内容から変わっている場合は、既存出力を
159
- 変更せずにimportを拒否します。メタデータ形式は
160
- [`docs/source-format-v1.md`](docs/source-format-v1.md)を参照してください。
161
-
162
- `extensions sync`は`resolvedCommit`だけから取得するため、mutableなbranchやtagを
163
- 再現処理に使いません。`extensions update`だけが`ref`を解決します。取得先はGitHubの
164
- HTTPS endpointに限定し、redirectと5 MiBを超える成果物を拒否します。取得したJavaScriptは
165
- 実行せず、IDとSHA-256を検証してから展開ディレクトリを置換します。複数拡張の一部だけが
166
- 失敗した場合は、ファイルもメタデータも変更しません。
167
-
168
- ID移行はTurboWarp公式形式の`[a-z0-9]+`を新IDに要求し、任意の文字列置換を行いません。
169
- 対象schema、dry-run、未分類参照の詳細は
170
- [`docs/extension-id-migration.md`](docs/extension-id-migration.md)を参照してください。
124
+ ## Documentation
171
125
 
172
- 展開形式の詳細は[`docs/source-format-v1.md`](docs/source-format-v1.md)を参照してください。
126
+ - [`docs/workflows.md`](docs/workflows.md): SB3 source and extension management workflows
127
+ - [`docs/source-format-v1.md`](docs/source-format-v1.md): expanded source format and deterministic output
128
+ - [`docs/extension-id-migration.md`](docs/extension-id-migration.md): migration of extension IDs already used by a project
129
+ - [`docs/extension-bundles.md`](docs/extension-bundles.md): static bundling into one permission unit and reversible unbundling
173
130
 
174
- ## 開発
131
+ ## Development
175
132
 
176
133
  ```bash
177
134
  pnpm install
178
135
  pnpm check
179
136
  ```
180
137
 
181
- ## ライセンス
138
+ ## License
182
139
 
183
140
  [Mozilla Public License 2.0](LICENSE)
184
141
 
185
- 本実装は
186
- [`kubohiroya/tmpose-kamishibai`](https://github.com/kubohiroya/tmpose-kamishibai)
187
- で開発したSB3ソース管理機構を、作品およびTMPose固有処理から分離したものです。
142
+ This implementation extracts the general SB3 source-management mechanism developed for
143
+ [`kubohiroya/tmpose-kamishibai`](https://github.com/kubohiroya/tmpose-kamishibai) from its
144
+ project- and TMPose-specific processing.
@@ -0,0 +1,446 @@
1
+ # Static bundles for embedded extensions
2
+
3
+ When a newly opened SB3 contains several unsandboxed extensions, TurboWarp asks for permission to
4
+ run each extension. A static bundle keeps the individual extensions in the expanded source but
5
+ transforms only the generated SB3 into one composite extension, reducing the permission unit to
6
+ one extension.
7
+
8
+ ## Overview
9
+
10
+ ```mermaid
11
+ flowchart LR
12
+ subgraph Source["Expanded source (authoritative)"]
13
+ Project["project.source.json<br/>original opcodes"]
14
+ Alpha["extensions/alpha.js"]
15
+ Beta["extensions/beta.js"]
16
+ end
17
+
18
+ Build["sb3-toolchain build"]
19
+
20
+ subgraph Output["Generated bundled SB3"]
21
+ BundledProject["project.json<br/>namespaced opcodes"]
22
+ Composite["one composite extension<br/>one register() call"]
23
+ Capsule["recovery capsule<br/>original extension data"]
24
+ end
25
+
26
+ TurboWarp["TurboWarp Editor<br/>one permission prompt"]
27
+
28
+ Project --> Build
29
+ Alpha --> Build
30
+ Beta --> Build
31
+ Build --> BundledProject
32
+ Build --> Composite
33
+ Build --> Capsule
34
+ BundledProject --> TurboWarp
35
+ Composite --> TurboWarp
36
+ ```
37
+
38
+ The expanded source always retains the individual extensions. Bundling changes only the generated
39
+ SB3, and the recovery capsule makes that generated artifact reversible when its safety conditions
40
+ remain satisfied.
41
+
42
+ ## What problem it solves
43
+
44
+ TurboWarp grants unsandboxed execution permission per loaded custom extension. A project with three
45
+ embedded extensions therefore presents three prompts even when all three are maintained and shipped
46
+ as one project. The bundle changes the loading boundary, not the security decision itself.
47
+
48
+ ```mermaid
49
+ flowchart LR
50
+ subgraph Before["Without a bundle"]
51
+ BeforeSB3["SB3"] --> PromptA["Allow extension A?"]
52
+ PromptA --> PromptB["Allow extension B?"]
53
+ PromptB --> PromptC["Allow extension C?"]
54
+ PromptC --> RunBefore["Run project"]
55
+ end
56
+
57
+ subgraph After["With a static bundle"]
58
+ AfterSB3["SB3"] --> BundlePrompt["Allow project bundle?"]
59
+ BundlePrompt --> Members["Extension A + B + C"]
60
+ Members --> RunAfter["Run project"]
61
+ end
62
+ ```
63
+
64
+ The user still reviews and authorizes unsandboxed JavaScript. The difference is that the generated
65
+ SB3 exposes one composite extension ID and one embedded extension URL, so TurboWarp has one custom
66
+ extension to authorize and load.
67
+
68
+ ### What it is and what it is not
69
+
70
+ | This feature does | This feature does not |
71
+ | ----------------------------------------------------------------- | ------------------------------------------------------------ |
72
+ | Create one composite runtime extension from several members | Disable or bypass TurboWarp's permission prompt |
73
+ | Rewrite generated project references to collision-free namespaces | Rewrite the authoritative source project in place |
74
+ | Preserve and delegate each member's original implementation | Flatten all member classes into one manually merged class |
75
+ | Embed recovery data for direct SB3 unbundling | Guarantee compatibility for arbitrary dynamic extension code |
76
+ | Reject transformations that cannot be classified safely | Execute extension JavaScript during the build |
77
+
78
+ ## Internal architecture
79
+
80
+ Bundling has separate build-time and runtime layers. Build time validates and rewrites data without
81
+ executing extension JavaScript. Runtime uses a generated wrapper to capture each member registration,
82
+ combine its metadata, and delegate calls.
83
+
84
+ ```mermaid
85
+ flowchart TB
86
+ subgraph BuildTime["Build time: Node.js toolchain"]
87
+ Config["extensionBundles configuration"]
88
+ Sources["Individual member JavaScript"]
89
+ SourceProject["Original project.source.json"]
90
+ Validator["Static contract validator"]
91
+ Generator["Bundle source generator"]
92
+ Rewriter["Project reference rewriter"]
93
+ BundleJS["Generated composite JavaScript"]
94
+ BundledProject["Generated project.json"]
95
+ Archive["Deterministic SB3 archive"]
96
+
97
+ Config --> Validator
98
+ Sources --> Validator
99
+ Validator --> Generator
100
+ SourceProject --> Rewriter
101
+ Config --> Rewriter
102
+ Generator --> BundleJS
103
+ Rewriter --> BundledProject
104
+ BundleJS --> Archive
105
+ BundledProject --> Archive
106
+ end
107
+
108
+ subgraph Runtime["Runtime: TurboWarp"]
109
+ Manager["Extension manager"]
110
+ Wrapper["Generated bundle wrapper"]
111
+ Captured["Captured member instances"]
112
+ Composite["StaticExtensionBundle"]
113
+ Palette["One palette category"]
114
+ VM["Scratch VM execution"]
115
+
116
+ Manager -->|"load one data URL"| Wrapper
117
+ Wrapper -->|"execute members with Scratch proxy"| Captured
118
+ Captured -->|"compose getInfo() and delegates"| Composite
119
+ Composite -->|"register once"| Manager
120
+ Manager --> Palette
121
+ VM -->|"namespaced opcode"| Composite
122
+ Composite -->|"delegate"| Captured
123
+ end
124
+
125
+ Archive --> Manager
126
+ ```
127
+
128
+ ### Anatomy of the generated JavaScript
129
+
130
+ The generated data URL is a self-contained classic extension script with these layers:
131
+
132
+ ```text
133
+ projectbundle.js
134
+ ├── human-readable bundle header
135
+ │ └── member name, ID, author, description, and license
136
+ ├── runtime adapter
137
+ │ ├── Scratch proxy for each member
138
+ │ ├── synchronous register() capture
139
+ │ ├── opcode, menu, custom-field, and hat namespaces
140
+ │ └── global and target storage aliases
141
+ ├── original member source A
142
+ ├── original member source B
143
+ ├── StaticExtensionBundle
144
+ │ ├── combined getInfo()
145
+ │ ├── generated palette headings and separators
146
+ │ └── handlers that delegate to captured member instances
147
+ ├── one real Scratch.extensions.register() call
148
+ └── SB3-Toolchain-Reversible-Bundle-v1 recovery capsule
149
+ ```
150
+
151
+ The original scripts still execute their normal initialization code at runtime. Their calls to
152
+ `Scratch.extensions.register()` are intercepted by a member-specific Scratch proxy instead of being
153
+ sent to TurboWarp. After every member registers exactly once, the wrapper registers the composite
154
+ extension with the real API.
155
+
156
+ ### Runtime call flow
157
+
158
+ ```mermaid
159
+ sequenceDiagram
160
+ participant VM as TurboWarp VM
161
+ participant W as Bundle wrapper
162
+ participant A as Member alpha
163
+ participant B as Member beta
164
+ participant C as Composite extension
165
+
166
+ VM->>W: Load projectbundle data URL
167
+ W->>A: Execute with proxied Scratch
168
+ A-->>W: register(alpha instance) captured
169
+ W->>B: Execute with proxied Scratch
170
+ B-->>W: register(beta instance) captured
171
+ W->>C: Construct combined getInfo() and delegates
172
+ W->>VM: register(composite) once
173
+
174
+ VM->>C: Call alpha__doSomething(args, util)
175
+ C->>A: Call original doSomething(args, util)
176
+ A-->>C: Result
177
+ C-->>VM: Result
178
+
179
+ A->>W: startHats("alpha_whenReady")
180
+ W->>VM: startHats("projectbundle_alpha__whenReady")
181
+ ```
182
+
183
+ ### Data transformations
184
+
185
+ | Concern | Before bundling | Generated bundled SB3 |
186
+ | --------------------------- | ----------------------------------------- | --------------------------------------------- |
187
+ | Loaded extension IDs | `alpha`, `beta` | `projectbundle` |
188
+ | Embedded data URLs | One per member | One composite data URL |
189
+ | Member `getInfo()` opcode | `doSomething` | `alpha__doSomething` |
190
+ | Stored project opcode | `alpha_doSomething` | `projectbundle_alpha__doSomething` |
191
+ | Menu and custom-field names | Member-local names | `memberId__` namespace |
192
+ | `startHats()` opcode | `alpha_whenReady` | `projectbundle_alpha__whenReady` |
193
+ | Extension storage | `storage.alpha`, `storage.beta` | `storage.projectbundle.components.alpha/beta` |
194
+ | Block IDs and graph links | Original IDs and `next`/`parent`/`inputs` | Unchanged |
195
+
196
+ This split is why existing scripts continue to call their original methods while the saved project
197
+ uses the composite extension ID expected by TurboWarp.
198
+
199
+ ## Compatibility and reversibility
200
+
201
+ Bundle configuration is added only to `embedded-extensions.json`. The following authoritative
202
+ sources are not modified:
203
+
204
+ - Original JavaScript in `extensions/<extensionId>.js`
205
+ - Individual extension entries and `source` provenance in `embedded-extensions.json`
206
+ - Original extension IDs, block and monitor opcodes, and extension storage in `project.source.json`
207
+
208
+ `check` and `extensions status|sync|update` continue to validate and update individual extensions.
209
+ Only `build` transforms the in-memory `project.json` and embedded JavaScript into their bundled
210
+ representation. There is no mode that deletes the original files.
211
+
212
+ An extension that cannot be transformed safely is rejected instead of being bundled with changed
213
+ behavior. The current static-bundle contract requires all of the following:
214
+
215
+ - Every member has Extension Gallery-style `Name`, `ID`, `Description`, `By`, and `License` headers
216
+ - The header ID, manifest ID, and runtime `getInfo().id` are identical
217
+ - Every member is a classic script that calls `Scratch.extensions.register` exactly once and synchronously
218
+ - No member uses XML blocks
219
+ - No unclassified opcode references remain outside blocks, monitors, or dynamic block metadata
220
+
221
+ The bundle namespaces ordinary commands, reporters, booleans, events, buttons, labels, static and
222
+ dynamic menus, custom fields, and global and target extension storage. Calls from child extensions
223
+ to `runtime.startHats` are also translated to bundled opcodes.
224
+
225
+ The bundle preserves the `members` order from the manifest and the block-definition order within
226
+ each member's `getInfo().blocks`. In the TurboWarp Editor palette, each group begins with a decorated
227
+ LABEL heading in this form:
228
+
229
+ ```text
230
+ ◆ Bundled extension: <name> [<memberId>] ◆
231
+ ```
232
+
233
+ Two consecutive `---` separators divide member groups. A generated LABEL also carries the following
234
+ machine-readable metadata:
235
+
236
+ ```js
237
+ {
238
+ sb3Toolchain: {
239
+ kind: 'bundle-member-heading',
240
+ memberId,
241
+ },
242
+ }
243
+ ```
244
+
245
+ LABEL entries and separators originally defined by a member are preserved unchanged and in their
246
+ original positions. The decorated bundle heading and wider double separator therefore remain
247
+ visually distinct from an original heading or ordinary separator. A tool can identify the generated
248
+ heading by its `sb3Toolchain` metadata and treat the two separators immediately before it as the
249
+ bundle group boundary.
250
+
251
+ The resulting palette has this visual hierarchy:
252
+
253
+ ```text
254
+ ┌─ Project Extension Bundle ─────────────────────────────┐
255
+ │ ◆ Bundled extension: Alpha Tools [alpha] ◆ │ ← generated heading
256
+ │ alpha block 1 │
257
+ │ Alpha original heading │ ← original LABEL
258
+ │ │ ← original separator
259
+ │ alpha block 2 │
260
+ │ │
261
+ │ │ ← generated double separator
262
+ │ ◆ Bundled extension: Beta Tools [beta] ◆ │ ← generated heading
263
+ │ beta block 1 │
264
+ └────────────────────────────────────────────────────────┘
265
+ ```
266
+
267
+ ## Configure a bundle
268
+
269
+ Start with a dry run to validate the selected members, header metadata, collisions, and opcode
270
+ references.
271
+
272
+ ```bash
273
+ sb3-toolchain extensions bundle app \
274
+ --id projectbundle \
275
+ --name "Project Extension Bundle" \
276
+ extensionone extensiontwo
277
+ ```
278
+
279
+ If member IDs are omitted, all embedded extensions not already assigned to another bundle are
280
+ selected. A bundle requires at least two members. Review the result before applying it.
281
+
282
+ ```bash
283
+ sb3-toolchain extensions bundle app \
284
+ --id projectbundle \
285
+ --name "Project Extension Bundle" \
286
+ extensionone extensiontwo \
287
+ --yes
288
+ sb3-toolchain check app
289
+ sb3-toolchain build app --output dist/project.sb3
290
+ ```
291
+
292
+ Member opcodes are transformed as follows in the generated SB3:
293
+
294
+ ```text
295
+ Original extension getInfo() opcode: doSomething
296
+ Bundle getInfo() opcode: extensionone__doSomething
297
+ Original project.json opcode: extensionone_doSomething
298
+ Bundled project.json opcode: projectbundle_extensionone__doSomething
299
+ ```
300
+
301
+ The bundle adds `memberId + "__"` to each original opcode, so identical opcodes from different
302
+ members cannot collide. Member IDs are restricted to `[a-z0-9]+`, making the delimiter unambiguous.
303
+ Loading the bundle is rejected if transformed opcodes still collide within the same member.
304
+
305
+ Only `projectbundle` appears in `extensions` and `extensionURLs`, and the generated JavaScript calls
306
+ `Scratch.extensions.register` once. The initial comments in that JavaScript list every member's
307
+ name, ID, author, description, and license so the user can inspect them before granting permission.
308
+
309
+ The end of the JavaScript contains an `SB3-Toolchain-Reversible-Bundle-v1` recovery capsule. The
310
+ capsule records each original member data URL, member order, and the original `extensions` and
311
+ `extensionURLs` order.
312
+
313
+ ## Restore from expanded source
314
+
315
+ Choose the restoration path based on which artifact is available:
316
+
317
+ ```mermaid
318
+ flowchart TD
319
+ Start{"What do you have?"}
320
+ Source["Expanded source directory"]
321
+ SB3["Bundled SB3 only"]
322
+ SourceCommand["extensions unbundle SOURCE_DIR"]
323
+ ArchiveCommand["extensions unbundle INPUT.sb3<br/>--output OUTPUT.sb3"]
324
+ Rebuild["Rebuild from preserved<br/>project.source.json and member JS"]
325
+ Recover["Validate recovery capsule<br/>and reverse project transformations"]
326
+ Restored["SB3 with individual extensions"]
327
+
328
+ Start -->|"authoritative source"| Source
329
+ Start -->|"distribution artifact"| SB3
330
+ Source --> SourceCommand --> Rebuild --> Restored
331
+ SB3 --> ArchiveCommand --> Recover --> Restored
332
+ ```
333
+
334
+ First inspect the unbundle plan with a dry run, then pass `--yes` to remove the bundle configuration.
335
+
336
+ ```bash
337
+ sb3-toolchain extensions unbundle app projectbundle
338
+ sb3-toolchain extensions unbundle app projectbundle --yes
339
+ sb3-toolchain check app
340
+ sb3-toolchain build app --output dist/project.sb3 --yes
341
+ ```
342
+
343
+ Because the original JavaScript and project representation are preserved, the next build restores
344
+ the individual IDs and data URLs and regenerates block, dynamic block metadata, and monitor opcodes
345
+ with their original values. This form of unbundle does not attempt to reverse-engineer a distribution
346
+ SB3. It regenerates the project from the saved `project.source.json` and individual JavaScript, so no
347
+ information is lost through an inferred opcode reversal. If `extensions update` ran while the bundle
348
+ was configured, the project is restored using the updated individual JavaScript.
349
+
350
+ Treat the expanded source as authoritative. Do not re-import a generated bundled SB3 into that same
351
+ authoritative source. Importing it into a new directory expands the distribution composite extension
352
+ as one ordinary extension and cannot recover the individual provenance. The normal Git-difference
353
+ protection and replacement confirmation still apply if an existing authoritative source is selected
354
+ accidentally.
355
+
356
+ ## Restore a bundled SB3 directly
357
+
358
+ A bundled SB3 containing a recovery capsule can be unbundled without the expanded source. The
359
+ command is a dry run unless `--yes` is supplied.
360
+
361
+ ```bash
362
+ sb3-toolchain extensions unbundle \
363
+ dist/project.sb3 projectbundle \
364
+ --output dist/project.unbundled.sb3
365
+ sb3-toolchain extensions unbundle \
366
+ dist/project.sb3 projectbundle \
367
+ --output dist/project.unbundled.sb3 \
368
+ --yes
369
+ ```
370
+
371
+ Direct unbundling restores all of the following:
372
+
373
+ - Bundle opcodes to `memberId_originalOpcode`, while leaving block IDs, `next`, `parent`, and `inputs` unchanged
374
+ - Opcodes in ordinary blocks, dynamic block metadata, and monitors
375
+ - The bundle storage `components` as storage keyed by the original member IDs
376
+ - Individual member data URLs and the original order of `extensions` and `extensionURLs`
377
+ - Asset entries and their byte contents
378
+
379
+ Blocks may be added, deleted, or moved in TurboWarp after bundling. An added block can still be
380
+ restored when its opcode has the `bundleId_memberId__originalOpcode` form. An SB3 containing several
381
+ bundles can be unbundled one bundle at a time in any order when every bundle has a valid recovery
382
+ capsule and their member sets do not overlap.
383
+
384
+ ### Conditions that make direct unbundling impossible
385
+
386
+ ```mermaid
387
+ flowchart TD
388
+ Input["Bundled SB3"]
389
+ Capsule{"Valid recovery capsule?"}
390
+ Order{"Extension ID set and<br/>order still match?"}
391
+ Mapping{"Every bundle opcode maps<br/>to exactly one member?"}
392
+ Storage{"Storage uses reversible<br/>format 1 without collisions?"}
393
+ Write["Write unbundled SB3"]
394
+ Refuse["Refuse safely<br/>leave output unchanged"]
395
+
396
+ Input --> Capsule
397
+ Capsule -->|"yes"| Order
398
+ Capsule -->|"no"| Refuse
399
+ Order -->|"yes"| Mapping
400
+ Order -->|"no"| Refuse
401
+ Mapping -->|"yes"| Storage
402
+ Mapping -->|"no"| Refuse
403
+ Storage -->|"yes"| Write
404
+ Storage -->|"no"| Refuse
405
+ ```
406
+
407
+ The tool refuses the operation without modifying the output instead of guessing when any of the
408
+ following conditions apply:
409
+
410
+ - The target data URL has no `SB3-Toolchain-Reversible-Bundle-v1` capsule because the bundle was
411
+ produced before recovery capsules were introduced, by another tool, or by hand
412
+ - The bundle data URL or capsule was removed, corrupted, or duplicated; its format version is not
413
+ supported; or its bundle ID, member ID, and original JavaScript header ID do not agree
414
+ - The ID set or order in `project.extensions` or `extensionURLs` changed after bundling. For example,
415
+ adding or removing another extension makes the exact insertion positions of the original members
416
+ unsafe to infer
417
+ - An opcode beginning with `bundleId_` cannot be assigned to a member's `memberId__` namespace, or
418
+ an unclassified bundle opcode reference remains outside ordinary blocks, dynamic block metadata,
419
+ and monitors
420
+ - Bundle storage is not `{formatVersion: 1, components: {...}}`, contains an unknown member or an
421
+ additional bundle-level field, or collides with storage already using a restored member ID
422
+ - Active reversible bundles contain overlapping members
423
+ - The ZIP is empty, `project.json` is missing or invalid, an entry name is unsafe, or entry order
424
+ cannot be preserved safely
425
+
426
+ If the expanded source is still available, these conditions do not prevent the source-based
427
+ `extensions unbundle SOURCE_DIR` workflow from removing the bundle configuration and rebuilding the
428
+ project. An older generated SB3 without a recovery capsule cannot be reversed directly from that SB3
429
+ alone.
430
+
431
+ Direct unbundling preserves asset bytes but recompresses the ZIP deterministically. It does not
432
+ preserve byte-for-byte identity of input ZIP metadata, entry timestamps, or archive comments.
433
+
434
+ ## Verification
435
+
436
+ Static validation cannot prove compatibility with browser APIs, cameras, the renderer, or implicit
437
+ dependencies between extensions. Run the same project-level automated tests before and after
438
+ bundling, then open the generated SB3 in a fresh TurboWarp session and verify all of the following:
439
+
440
+ - The unsandboxed execution prompt appears only once
441
+ - Green flag behavior and block, reporter, hat, monitor, and menu results are unchanged
442
+ - Permission paths used by the project, such as camera, network, file picker, and renderer access, work
443
+ - An SB3 saved again by TurboWarp retains extension storage and still works after reloading
444
+
445
+ Exclude a member from the bundle and keep it as an individual extension when its compatibility
446
+ cannot be verified.