@kubohiroya/sb3-toolchain 0.1.1 → 0.3.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 +59 -96
- package/docs/extension-api-compatibility.md +169 -0
- package/docs/extension-bundles.md +446 -0
- package/docs/extension-id-migration.md +44 -33
- package/docs/ja/extension-api-compatibility.md +167 -0
- package/docs/source-format-v1.md +134 -62
- package/docs/workflows.md +249 -0
- package/package.json +1 -1
- package/src/build.js +21 -7
- package/src/cli.js +176 -3
- package/src/constants.js +1 -1
- package/src/extension-api-manifest.js +336 -0
- package/src/extension-bundle-archive.js +422 -0
- package/src/extension-bundle-configuration.js +247 -0
- package/src/extension-bundle.js +640 -0
- package/src/extension-dependencies.js +16 -1
- package/src/extension-id-migration.js +74 -3
- package/src/extension-sync.js +189 -20
- package/src/import.js +28 -12
- package/src/index.js +25 -0
- package/src/source.js +48 -7
|
@@ -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.
|
|
@@ -1,59 +1,70 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Migrating embedded extension IDs
|
|
2
2
|
|
|
3
|
-
TurboWarp
|
|
4
|
-
|
|
5
|
-
|
|
3
|
+
TurboWarp stores the IDs of loaded extensions in project opcodes and monitors. `extensions migrate-id`
|
|
4
|
+
does not perform a global string replacement. It changes only references whose meaning is defined by
|
|
5
|
+
SB3 source format v1.
|
|
6
6
|
|
|
7
|
-
##
|
|
7
|
+
## Dry run and apply
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
The standalone migration command is a dry run by default.
|
|
10
10
|
|
|
11
11
|
```bash
|
|
12
12
|
sb3-toolchain extensions migrate-id app --from twOld --to newext
|
|
13
13
|
```
|
|
14
14
|
|
|
15
|
-
|
|
16
|
-
`extensions/twOld.js
|
|
15
|
+
Review the classified change counts and `Unclassified` references. Before applying the migration,
|
|
16
|
+
place a JavaScript artifact that declares the new ID at `extensions/twOld.js`.
|
|
17
17
|
|
|
18
18
|
```bash
|
|
19
19
|
sb3-toolchain extensions migrate-id app --from twOld --to newext --yes
|
|
20
20
|
```
|
|
21
21
|
|
|
22
|
-
|
|
23
|
-
`extensionURLs
|
|
24
|
-
拒否します。
|
|
22
|
+
The new ID must use TurboWarp's official `[a-z0-9]+` format. The migration is rejected as a collision
|
|
23
|
+
if the new ID already exists in the manifest, `extensionURLs`, or `project.extensions`.
|
|
25
24
|
|
|
26
|
-
##
|
|
25
|
+
## Classified references
|
|
27
26
|
|
|
28
|
-
|
|
29
|
-
- `extensionURLs`の完全一致keyと埋め込み拡張value
|
|
30
|
-
- `targets[*].blocks[*].opcode`の`<oldId>_`完全prefix
|
|
31
|
-
- menu blockのopcode(通常のblockと同じschema)
|
|
32
|
-
- `monitors[*].opcode`の`<oldId>_`完全prefix
|
|
33
|
-
- `embedded-extensions.json`の`id`と`path`
|
|
34
|
-
- `extensions/<oldId>.js`から`extensions/<newId>.js`へのファイル名変更
|
|
27
|
+
The tool changes the following references:
|
|
35
28
|
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
29
|
+
- Exact IDs in `project.source.json` `extensions[]`
|
|
30
|
+
- Exact `extensionURLs` keys and embedded-extension values
|
|
31
|
+
- Exact `<oldId>_` prefixes in `targets[*].blocks[*].opcode`
|
|
32
|
+
- Menu block opcodes, which use the ordinary block schema
|
|
33
|
+
- Exact `<oldId>_` prefixes in `monitors[*].opcode`
|
|
34
|
+
- `id` and `path` in `embedded-extensions.json`
|
|
35
|
+
- The filename from `extensions/<oldId>.js` to `extensions/<newId>.js`
|
|
39
36
|
|
|
40
|
-
|
|
37
|
+
Strings containing the old ID in variable names, list names, block literals, metadata, or another
|
|
38
|
+
extension's opcode are not changed. They appear in the dry-run output as unclassified references
|
|
39
|
+
with JSON Pointers so that a person can determine their meaning.
|
|
41
40
|
|
|
42
|
-
|
|
43
|
-
|
|
41
|
+
## GitHub-managed extensions
|
|
42
|
+
|
|
43
|
+
For a managed extension, the recommended workflow combines the update and migration after the
|
|
44
|
+
upstream repository publishes an artifact declaring the new ID.
|
|
44
45
|
|
|
45
46
|
```bash
|
|
46
47
|
sb3-toolchain extensions update app twOld \
|
|
47
48
|
--migrate-id newext \
|
|
48
|
-
--artifact dist/newext.js
|
|
49
|
+
--artifact dist/newext.js \
|
|
50
|
+
--api-manifest-artifact dist/newext.manifest.json
|
|
49
51
|
```
|
|
50
52
|
|
|
51
|
-
`--artifact
|
|
52
|
-
|
|
53
|
-
|
|
53
|
+
Specify `--artifact` only when the upstream JavaScript artifact path changed. Specify
|
|
54
|
+
`--api-manifest-artifact` only when an opt-in manifest artifact path also changed. The tool resolves
|
|
55
|
+
the tracked ref to an immutable commit and downloads the new artifacts from that commit. It rejects
|
|
56
|
+
an artifact that does not declare `// ID: newext`, a collision, or an invalid new ID before changing
|
|
57
|
+
local files.
|
|
58
|
+
|
|
59
|
+
If the managed extension has `source.apiManifest`, the tool downloads the candidate manifest from
|
|
60
|
+
the same commit, normalizes only the explicit old and new top-level IDs, and applies the ordinary API
|
|
61
|
+
compatibility policy to every remaining field. JavaScript, the renamed local manifest, provenance,
|
|
62
|
+
both remote artifact paths when supplied, and both integrity values change in one transaction. See
|
|
63
|
+
[`extension-api-compatibility.md`](extension-api-compatibility.md).
|
|
54
64
|
|
|
55
|
-
##
|
|
65
|
+
## Validation and rollback
|
|
56
66
|
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
67
|
+
The tool completes normal source validation and a deterministic candidate SB3 build before replacing
|
|
68
|
+
the expanded source directory transactionally. It restores the original directory automatically if
|
|
69
|
+
replacement fails. To roll back after merge, revert the project migration commit so that the old ID,
|
|
70
|
+
artifact, and provenance return together.
|