@kubohiroya/sb3-toolchain 0.4.0 → 0.6.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
@@ -9,11 +9,14 @@ Scratch 3およびTurboWarpの`.sb3`プロジェクトを、Gitで差分を確
9
9
 
10
10
  - SB3を、整形済みの`project.source.json`、アセット、埋め込み機能拡張へ安全に展開
11
11
  - アセット参照、MD5ハッシュ、ZIPエントリ、埋め込み機能拡張の対応関係を検証
12
- - GitHubでホストされる埋め込み機能拡張のコミットとSHA-256ハッシュを記録し、オフラインで検証
12
+ - GitHubの固定コミットまたはインストール済みnpmパッケージの完全固定バージョンから埋め込み機能拡張を管理し、
13
+ SHA-256ハッシュをオフラインで検証
13
14
  - 埋め込みJavaScriptを置き換える前に、バージョン付き機能拡張APIマニフェストを任意で比較
14
15
  - 元のJavaScriptを削除せず、複数の機能拡張を1つの権限単位へ静的にbundleし、展開ソースまたは
15
16
  bundle済みSB3から復元
16
17
  - ZIPエントリ順、タイムスタンプ、圧縮設定を固定した決定的ビルド
18
+ - 展開済みbase sourceを変更せず、JSON/YAML build manifestからsprite、backdrop、costume、soundを追加
19
+ - 全ターゲットのスクリプトをTurboWarp風の決定的な「きれいにする」配置へ任意で整理
17
20
  - import時に未コミットのGit変更を保護
18
21
  - トランザクションによる置換とロールバックで既存出力を保護
19
22
  - CLIとJavaScript APIの両方を提供
@@ -28,7 +31,7 @@ Scratch 3およびTurboWarpの`.sb3`プロジェクトを、Gitで差分を確
28
31
  再現可能なインストールのため、検証済みのnpmバージョンを固定します。
29
32
 
30
33
  ```bash
31
- pnpm add --save-dev --save-exact @kubohiroya/sb3-toolchain@0.4.0
34
+ pnpm add --save-dev --save-exact @kubohiroya/sb3-toolchain@0.6.0
32
35
  ```
33
36
 
34
37
  ## クイックスタート
@@ -75,9 +78,11 @@ await validateSb3Source('app');
75
78
  await buildSb3({
76
79
  sourceDirectory: 'app',
77
80
  outputPath: 'dist/project.sb3',
81
+ // 生成SB3だけを整理済みブロック座標にする場合に明示的に有効化します。
82
+ cleanUpBlocks: true,
78
83
  });
79
84
 
80
- const {archive} = await createDeterministicSb3('app');
85
+ const {archive} = await createDeterministicSb3('app', {cleanUpBlocks: true});
81
86
 
82
87
  const integrity = extensionIntegrity(await readFile('app/extensions/example.js'));
83
88
 
@@ -128,6 +133,7 @@ await unbundleSb3({
128
133
 
129
134
  - [`docs/ja/workflows.md`](docs/ja/workflows.md): SB3ソースと機能拡張を管理するワークフロー
130
135
  - [`docs/ja/source-format-v1.md`](docs/ja/source-format-v1.md): 展開ソース形式と決定的出力
136
+ - [`docs/ja/project-asset-additions.md`](docs/ja/project-asset-additions.md): `--project-assets`のJSON/YAML、backdrop、編集/strict lock仕様
131
137
  - [`docs/ja/extension-id-migration.md`](docs/ja/extension-id-migration.md): プロジェクトで使用中の機能拡張IDの移行
132
138
  - [`docs/ja/extension-api-compatibility.md`](docs/ja/extension-api-compatibility.md): 機能拡張更新時の任意の静的API互換性検査
133
139
  - [`docs/ja/extension-bundles.md`](docs/ja/extension-bundles.md): 1つの権限単位への静的bundleと可逆的なunbundle
package/README.md CHANGED
@@ -9,11 +9,15 @@ expanded sources and rebuilding bit-for-bit identical SB3 files from the same in
9
9
 
10
10
  - Safely expand an SB3 into formatted `project.source.json`, assets, and embedded extensions
11
11
  - Validate asset references, MD5 hashes, ZIP entries, and embedded extension mappings
12
- - Record commits and SHA-256 hashes for GitHub-hosted embedded extensions and verify them offline
12
+ - Manage embedded extensions from pinned GitHub commits or exact installed npm package versions and
13
+ verify their SHA-256 hashes offline
13
14
  - Optionally compare versioned extension API manifests before replacing embedded JavaScript
14
15
  - Statically bundle multiple extensions into one permission unit without deleting their original
15
16
  JavaScript, then restore them from either the expanded source or the bundled SB3
16
17
  - Produce deterministic builds with fixed ZIP entry order, timestamps, and compression settings
18
+ - Add sprites, backdrops, costumes, and sounds from an optional JSON or YAML build manifest without
19
+ modifying the expanded base source
20
+ - Optionally lay out every target's scripts in a deterministic TurboWarp-style cleaned arrangement
17
21
  - Protect uncommitted Git changes when importing
18
22
  - Protect existing output through transactional replacement and rollback
19
23
  - Provide both a CLI and a JavaScript API
@@ -28,7 +32,7 @@ expanded sources and rebuilding bit-for-bit identical SB3 files from the same in
28
32
  Pin the verified npm version for reproducible installation.
29
33
 
30
34
  ```bash
31
- pnpm add --save-dev --save-exact @kubohiroya/sb3-toolchain@0.4.0
35
+ pnpm add --save-dev --save-exact @kubohiroya/sb3-toolchain@0.6.0
32
36
  ```
33
37
 
34
38
  ## Quick start
@@ -75,9 +79,11 @@ await validateSb3Source('app');
75
79
  await buildSb3({
76
80
  sourceDirectory: 'app',
77
81
  outputPath: 'dist/project.sb3',
82
+ // Opt in to cleaned block coordinates in the generated SB3 only:
83
+ cleanUpBlocks: true,
78
84
  });
79
85
 
80
- const {archive} = await createDeterministicSb3('app');
86
+ const {archive} = await createDeterministicSb3('app', {cleanUpBlocks: true});
81
87
 
82
88
  const integrity = extensionIntegrity(await readFile('app/extensions/example.js'));
83
89
 
@@ -128,6 +134,7 @@ await unbundleSb3({
128
134
 
129
135
  - [`docs/workflows.md`](docs/workflows.md): SB3 source and extension management workflows
130
136
  - [`docs/source-format-v1.md`](docs/source-format-v1.md): expanded source format and deterministic output
137
+ - [`docs/project-asset-additions.md`](docs/project-asset-additions.md): JSON/YAML `--project-assets`, backdrops, and editable or strict locks
131
138
  - [`docs/extension-id-migration.md`](docs/extension-id-migration.md): migration of extension IDs already used by a project
132
139
  - [`docs/extension-api-compatibility.md`](docs/extension-api-compatibility.md) ([日本語](docs/ja/extension-api-compatibility.md)): opt-in static API compatibility checks for extension updates
133
140
  - [`docs/extension-bundles.md`](docs/extension-bundles.md): static bundling into one permission unit and reversible unbundling
@@ -180,6 +180,13 @@ sequenceDiagram
180
180
 
181
181
  A->>W: startHats("alpha_whenReady")
182
182
  W->>VM: startHats("projectbundle_alpha__whenReady")
183
+
184
+ A->>W: getOpcodeFunction("beta_echo")
185
+ W->>VM: getOpcodeFunction("projectbundle_beta__echo")
186
+ VM-->>A: Bundled opcode handler
187
+ A->>C: Call handler(args, util)
188
+ C->>B: Call original echo(args, util)
189
+ B-->>A: Result or Promise
183
190
  ```
184
191
 
185
192
  ### Data transformations
@@ -192,6 +199,7 @@ sequenceDiagram
192
199
  | Stored project opcode | `alpha_doSomething` | `projectbundle_alpha__doSomething` |
193
200
  | Menu and custom-field names | Member-local names | `memberId__` namespace |
194
201
  | `startHats()` opcode | `alpha_whenReady` | `projectbundle_alpha__whenReady` |
202
+ | `getOpcodeFunction()` | `beta_echo` | `projectbundle_beta__echo` |
195
203
  | Extension storage | `storage.alpha`, `storage.beta` | `storage.projectbundle.components.alpha/beta` |
196
204
  | Block IDs and graph links | Original IDs and `next`/`parent`/`inputs` | Unchanged |
197
205
 
@@ -222,7 +230,16 @@ behavior. The current static-bundle contract requires all of the following:
222
230
 
223
231
  The bundle namespaces ordinary commands, reporters, booleans, events, buttons, labels, static and
224
232
  dynamic menus, custom fields, and global and target extension storage. Calls from child extensions
225
- to `runtime.startHats` are also translated to bundled opcodes.
233
+ to `runtime.startHats` are also translated to bundled opcodes. When a member calls
234
+ `runtime.getOpcodeFunction()`, an opcode beginning with any member ID in the same bundle is
235
+ translated at runtime. This supports both self references and calls to another member, such as an
236
+ Asset Manager member resolving an Animated Text member's handler.
237
+
238
+ Only the opcode passed to `getOpcodeFunction()` is adapted. The function returned by the VM is
239
+ passed through unchanged, so its binding, handler arguments, synchronous result, or Promise result
240
+ are preserved. Core, external-extension, and unknown opcodes whose prefix is not a bundle member ID
241
+ are passed to the VM unchanged. Other APIs that carry opcode strings are outside this compatibility
242
+ contract unless documented separately.
226
243
 
227
244
  The bundle preserves the `members` order from the manifest and the block-definition order within
228
245
  each member's `getInfo().blocks`. In the TurboWarp Editor palette, each group begins with a decorated
@@ -176,6 +176,13 @@ sequenceDiagram
176
176
 
177
177
  A->>W: startHats("alpha_whenReady")
178
178
  W->>VM: startHats("projectbundle_alpha__whenReady")
179
+
180
+ A->>W: getOpcodeFunction("beta_echo")
181
+ W->>VM: getOpcodeFunction("projectbundle_beta__echo")
182
+ VM-->>A: bundle済みopcodeのhandler
183
+ A->>C: handler(args, util)を呼び出す
184
+ C->>B: 元のecho(args, util)を呼び出す
185
+ B-->>A: 結果またはPromise
179
186
  ```
180
187
 
181
188
  ### データ変換
@@ -188,6 +195,7 @@ sequenceDiagram
188
195
  | 保存されるプロジェクトopcode | `alpha_doSomething` | `projectbundle_alpha__doSomething` |
189
196
  | メニューとカスタムフィールド名 | メンバー内の名前 | `memberId__`名前空間 |
190
197
  | `startHats()`のopcode | `alpha_whenReady` | `projectbundle_alpha__whenReady` |
198
+ | `getOpcodeFunction()` | `beta_echo` | `projectbundle_beta__echo` |
191
199
  | 機能拡張ストレージ | `storage.alpha`、`storage.beta` | `storage.projectbundle.components.alpha/beta` |
192
200
  | ブロックIDとグラフリンク | 元のIDと`next`/`parent`/`inputs` | 変更なし |
193
201
 
@@ -217,7 +225,15 @@ bundle設定は`embedded-extensions.json`だけに追加されます。信頼で
217
225
 
218
226
  bundleは、通常のcommand、reporter、boolean、event、button、label、静的および動的メニュー、
219
227
  カスタムフィールド、グローバルおよびターゲット機能拡張ストレージを名前空間化します。子機能拡張からの
220
- `runtime.startHats`呼び出しもbundle済みopcodeへ変換します。
228
+ `runtime.startHats`呼び出しもbundle済みopcodeへ変換します。メンバーが`runtime.getOpcodeFunction()`を
229
+ 呼び出した場合は、同じbundleに含まれるいずれかのメンバーIDで始まるopcodeをランタイムで変換します。
230
+ これにより、自身のopcode参照だけでなく、Asset ManagerメンバーがAnimated Textメンバーのhandlerを
231
+ 解決するようなmember間呼び出しにも対応します。
232
+
233
+ 変換するのは`getOpcodeFunction()`へ渡すopcodeだけです。VMが返す関数は変更せずそのまま返すため、関数の
234
+ 束縛、handlerの引数、同期的な戻り値、Promiseの戻り値は保持されます。先頭部分がbundle member IDではない
235
+ core、外部機能拡張、未知のopcodeは変更せずVMへ渡します。opcode文字列を受け取るほかのAPIは、個別に明記
236
+ されていない限り、この互換性契約の対象外です。
221
237
 
222
238
  bundleは、マニフェストの`members`順と、各メンバーの`getInfo().blocks`内のブロック定義順を保持します。
223
239
  TurboWarp Editorのパレットでは、各グループが次の形式の装飾済みLABEL見出しから始まります。
@@ -0,0 +1,200 @@
1
+ # `--project-assets`: project asset追加build入力
2
+
3
+ `--project-assets`は、展開済みSB3 sourceを編集せず、生成するSB3にStage backdrop、sprite costume、
4
+ stage/sprite sound、新規spriteを追加するためのbuild入力です。JSONとYAMLを使用できます。
5
+
6
+ ```bash
7
+ sb3-toolchain check app \
8
+ --project-assets stories/my-story/project-assets.yml \
9
+ --allow-asset-root resources
10
+
11
+ sb3-toolchain build app \
12
+ --project-assets stories/my-story/project-assets.yml \
13
+ --allow-asset-root resources \
14
+ --output dist/my-story.sb3
15
+ ```
16
+
17
+ `check`はSB3を書き出さず、base sourceとproject assetsをメモリ上で合成して検証します。`build`だけが
18
+ 出力SB3を生成します。どちらもbase sourceの`project.source.json`、`sb3-source.json`、`assets/`を
19
+ 変更しません。
20
+
21
+ ## YAML形式(推奨)
22
+
23
+ `.yml`または`.yaml`は、DSL 4.0の`assets:`と同様に、asset IDをmapping key、`kind`をasset種別として
24
+ 記述します。新規spriteの表示属性だけを`sprites:`へ分離します。
25
+
26
+ ```yaml
27
+ formatVersion: 1
28
+
29
+ sprites:
30
+ Princess:
31
+ layerOrder: 6
32
+ visible: false
33
+ x: 4
34
+ y: -16
35
+ size: 70
36
+ direction: 90
37
+ draggable: false
38
+ rotationStyle: all around
39
+ volume: 100
40
+
41
+ assets:
42
+ Princess:
43
+ kind: costume
44
+ target: Princess
45
+ file: ../../resources/Princess.png
46
+ bitmapResolution: 2
47
+ rotationCenterX: 507
48
+ rotationCenterY: 507
49
+ license: 'CC-BY-SA-4.0: ../../LICENSES.md'
50
+
51
+ DragonCastle:
52
+ kind: backdrop
53
+ file: ../../resources/DragonCastle.svg
54
+ rotationCenterX: 240
55
+ rotationCenterY: 180
56
+
57
+ OpeningSound:
58
+ kind: sound
59
+ file: ../../resources/OpeningSound.mp3
60
+
61
+ PrincessVoice:
62
+ kind: sound
63
+ target: Princess
64
+ file: ../../resources/PrincessVoice.wav
65
+ ```
66
+
67
+ - `backdrop`は常にStageの`costumes`へ追加します。`target`は指定しません。
68
+ - `costume`は`target`で指定したspriteの`costumes`へ追加します。
69
+ - `sound`は`target`省略時にStage、指定時にそのspriteの`sounds`へ追加します。
70
+ - 既存spriteへ追加する場合、そのspriteを`sprites:`へ重ねて宣言する必要はありません。
71
+ - 新規spriteは`sprites:`で宣言し、`assets:`から1件以上のcostumeを割り当てます。
72
+ - asset ID(例: `Princess`)がScratch内のcostume/backdrop/sound名になります。別名にする場合だけ
73
+ `name`を指定します。
74
+
75
+ YAMLは1.2として解釈します。duplicate key、複数document、anchor、alias、merge key、custom tag、
76
+ `__proto__`/`constructor`/`prototype` keyを拒否します。YAMLコメントは使用できます。
77
+
78
+ ## JSON形式
79
+
80
+ `.json`はYAMLと同じfield構成です。次は上のPrincess部分と等価です。
81
+
82
+ ```json
83
+ {
84
+ "formatVersion": 1,
85
+ "sprites": {
86
+ "Princess": {
87
+ "layerOrder": 6,
88
+ "visible": false,
89
+ "x": 4,
90
+ "y": -16,
91
+ "size": 70,
92
+ "direction": 90,
93
+ "draggable": false,
94
+ "rotationStyle": "all around",
95
+ "volume": 100
96
+ }
97
+ },
98
+ "assets": {
99
+ "Princess": {
100
+ "kind": "costume",
101
+ "target": "Princess",
102
+ "file": "../../resources/Princess.png",
103
+ "bitmapResolution": 2,
104
+ "rotationCenterX": 507,
105
+ "rotationCenterY": 507
106
+ }
107
+ }
108
+ }
109
+ ```
110
+
111
+ JSONでもduplicate keyを拒否します。`.json`、`.yml`、`.yaml`以外の拡張子は受け付けません。
112
+
113
+ ## 編集用の通常モード
114
+
115
+ 画像を描き直したり、音声を録り直したりしながら同じファイルへ上書きする場合、`size`と`sha256`は
116
+ 記述しません。`file`の現在のbyte列を正本として、buildごとにScratch用MD5 `assetId`を再計算します。
117
+
118
+ 画像では次を指定します。
119
+
120
+ | field | 必須 | 内容 |
121
+ | ------------------------------------ | --------------- | --------------------------------- |
122
+ | `kind` | 必須 | `backdrop`または`costume` |
123
+ | `target` | costumeだけ必須 | 追加先sprite名 |
124
+ | `file` | 必須 | manifestからの相対path |
125
+ | `rotationCenterX`, `rotationCenterY` | 必須 | Scratchの回転中心 |
126
+ | `bitmapResolution` | 任意 | `1`(既定)または`2` |
127
+ | `name` | 任意 | Scratch内の名前。省略時はasset ID |
128
+
129
+ 音声では通常、`kind: sound`と`file`だけで足ります。open-sourceの`music-metadata`を使ってMP3/WAVを
130
+ 解析し、`rate`と`sampleCount`を自動取得します。sprite soundだけは`target`も指定します。`dataFormat`は画像・音声ともfile拡張子から
131
+ 取得します。
132
+
133
+ ## 配布用のstrict lock
134
+
135
+ 再現対象の入力byte列を固定する場合だけ、次のfieldを追加します。fieldごとに独立して検証するため、
136
+ 必要なものだけ指定できます。
137
+
138
+ ```yaml
139
+ assets:
140
+ Princess:
141
+ kind: costume
142
+ target: Princess
143
+ file: ../../resources/Princess.png
144
+ rotationCenterX: 507
145
+ rotationCenterY: 507
146
+ size: 220534
147
+ sha256: e9d1857528a619e4a56ebd232fea4767fd6bdd00b20ac67a90c859c6b3598e83
148
+ dataFormat: png
149
+ ```
150
+
151
+ | strict field | 検証内容 |
152
+ | --------------------- | -------------------------------------- |
153
+ | `size` | fileのbyte数と一致すること |
154
+ | `sha256` | fileのSHA-256と一致すること |
155
+ | `dataFormat` | file拡張子から得たformatと一致すること |
156
+ | `rate`, `sampleCount` | 音声から自動取得した値と一致すること |
157
+
158
+ 指定していないstrict fieldは不一致判定に使用しません。`license`は任意の1行の出典・ライセンス情報として
159
+ 検証しますが、Scratchの`project.json`にはコピーしません。
160
+
161
+ 同じbase source、manifest、asset byte列、toolchain versionからはbit-for-bit同一のSB3を生成します。
162
+ 通常モードでasset fileを上書きすれば、次のbuild結果が変わるのは意図した動作です。配布時に意図しない
163
+ 上書きを検出する必要があれば`size`と`sha256`を指定します。
164
+
165
+ ## pathと入力の安全性
166
+
167
+ asset fileは既定でmanifest directory内に限定します。共有素材directoryを参照する場合だけ、
168
+ repeatableな`--allow-asset-root`で明示的に許可します。
169
+
170
+ ```bash
171
+ sb3-toolchain build app \
172
+ --project-assets stories/my-story/project-assets.yml \
173
+ --allow-asset-root resources/images \
174
+ --allow-asset-root resources/sounds \
175
+ --output dist/my-story.sb3
176
+ ```
177
+
178
+ 絶対path、許可rootからの逸脱、symlink経由、通常file以外、拡張子と指定`dataFormat`の不一致、既存の
179
+ target/costume/backdrop/sound名との衝突はfail-closedで拒否します。manifest自体は1 MiB以下の
180
+ 通常fileである必要があります。
181
+
182
+ ## JavaScript API
183
+
184
+ CLIと同じ入力を`createDeterministicSb3`または`buildSb3`へ渡せます。
185
+
186
+ ```js
187
+ await createDeterministicSb3('app', {
188
+ projectAssetsPath: 'stories/my-story/project-assets.yml',
189
+ allowedAssetRoots: ['resources'],
190
+ });
191
+
192
+ await buildSb3({
193
+ sourceDirectory: 'app',
194
+ projectAssetsPath: 'stories/my-story/project-assets.yml',
195
+ allowedAssetRoots: ['resources'],
196
+ outputPath: 'dist/my-story.sb3',
197
+ });
198
+ ```
199
+
200
+ `projectAssetsPath`を指定しなければ、project assetを追加しない従来のbuildへ戻ります。
@@ -42,8 +42,8 @@ embedded-extension:extensions/<extensionId>.js
42
42
 
43
43
  ## `embedded-extensions.json`
44
44
 
45
- このファイルは、埋め込み機能拡張のdata URL情報と展開先パスを記録します。GitHubから管理する機能拡張には、
46
- 任意の`source`メタデータを追加できます。
45
+ このファイルは、埋め込み機能拡張のdata URL情報と展開先パスを記録します。GitHubまたはインストール済み
46
+ npmパッケージから管理する機能拡張には、任意の`source`メタデータを追加できます。
47
47
 
48
48
  ```json
49
49
  {
@@ -74,10 +74,25 @@ embedded-extension:extensions/<extensionId>.js
74
74
  }
75
75
  ```
76
76
 
77
+ 完全固定したnpm依存では、GitHub固有のフィールドをパッケージ情報へ置き換えます。
78
+
79
+ ```json
80
+ {
81
+ "provider": "npm",
82
+ "package": "@owner/example-extension",
83
+ "version": "1.2.3",
84
+ "artifact": "dist/example.js",
85
+ "integrity": "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="
86
+ }
87
+ ```
88
+
89
+ - `provider`: `github`または`npm`
77
90
  - `repository`: `<owner>/<repository>`形式のGitHubリポジトリ
78
91
  - `ref`: 更新候補として追跡するブランチ、タグ、またはコミット
79
92
  - `resolvedCommit`: 現在のファイルの取得に使用した、小文字40文字のコミットSHA
80
- - `artifact`: リポジトリルートを基準にしたJavaScript成果物のパス
93
+ - `package`: スコープを含む完全なnpmパッケージ名
94
+ - `version`: インストール済み`package.json`に記録された完全固定のsemantic version。範囲指定は不可
95
+ - `artifact`: リポジトリまたはnpmパッケージのルートを基準にしたJavaScript成果物のパス
81
96
  - `integrity`: 現在のファイルのSRI形式SHA-256
82
97
  - `apiManifest`: 任意で使用するAPI互換性メタデータ
83
98
  - `artifact`: 同じGitHubリポジトリを基準にしたAPIマニフェストのパス
@@ -89,19 +104,19 @@ embedded-extension:extensions/<extensionId>.js
89
104
 
90
105
  - 実ファイルのSHA-256が`integrity`と一致する
91
106
  - ファイルの`// ID: <extensionId>`ヘッダーが`id`と一致する
92
- - リポジトリ、ref、コミット、成果物パスが安全な形式である
107
+ - GitHubリポジトリ、ref、コミット、npmパッケージ、完全固定バージョン、成果物パスが安全な形式である
93
108
  - `apiManifest`が存在する場合、そのJSONスキーマ、ID、形式バージョン、パス、SHA-256が有効である
94
109
 
95
110
  既存の展開ソースディレクトリへSB3を再importすると、同じIDとパスの`source`メタデータが保持されます。
96
111
  importしたファイルが記録済みのハッシュまたはIDと一致しない場合、既存の出力を変更せずにimportを拒否します。
97
112
  新規importでは来歴を推測できないため、`source`は自動作成されません。
98
113
 
99
- `extensions sync`は、変更不能な`resolvedCommit`を使用してJavaScriptと任意のAPIマニフェストを
100
- ダウンロードし、そのIDとハッシュが既存メタデータに一致する場合に限りローカルファイルを復元します。
101
- `extensions update`はGitHub APIを通じて`ref`を解決し、同じコミットから両方の成果物をダウンロードして、
102
- 候補APIマニフェストをインストール済み契約と比較します。互換性検査と内容検証が成功した後に限り、
103
- `resolvedCommit`と両方のintegrity値を更新します。選択したすべてのエントリのダウンロードと検証が完了するまで、
104
- 展開ソースは変更されません。
114
+ GitHub sourceの`extensions sync`は変更不能な`resolvedCommit`からJavaScriptと任意のAPIマニフェストを
115
+ ダウンロードします。npm sourceでは、最寄りの親`node_modules`にインストールされた完全固定パッケージから、
116
+ ネットワークを使わずに読み込みます。どちらもIDとハッシュが既存メタデータに一致する場合だけ復元します。
117
+ パッケージマネージャーで新しい完全固定npmバージョンを導入した後に`extensions update`を実行すると、成果物を
118
+ コピーして`version`とintegrityを更新します。GitHub更新では`ref`を解決して`resolvedCommit`を更新します。
119
+ どちらも候補APIマニフェストを事前に比較し、選択した全項目の検証が終わるまで展開ソースを変更しません。
105
120
 
106
121
  機能拡張IDの移行では、マニフェストの`id`と`path`、`project.source.json`内の既知の参照、
107
122
  `extensions/<id>.js`を1回のトランザクションで変更します。`extensions update`の一部として管理対象機能拡張を
@@ -84,25 +84,37 @@ sb3-toolchain build app --output dist/project.sb3
84
84
  バイト単位で同一のSB3が生成されます。既存出力が同一なら変更しません。異なる場合は、置換の確認または
85
85
  `--yes`が必要です。
86
86
 
87
+ 生成SB3へ書き込む前に、全ターゲットのトップレベルスクリプトを整理するには、明示的にオプションを指定します。
88
+
89
+ ```bash
90
+ sb3-toolchain build app --output dist/project.sb3 --clean-up-blocks
91
+ ```
92
+
93
+ `--clean-up-blocks`は、TurboWarpの「きれいにする」配置と同じ開始座標、列の判定範囲、余白を使用します。
94
+ ブロック、変数、リスト、コメントは削除せず、ブロックに付いたコメントはスクリプトと一緒に移動します。変換する
95
+ のは生成物内の`project.json`だけであり、展開ソースは変更しません。生成SB3をTurboWarpで開いた後は座標変更を
96
+ 元に戻せない場合があります。ソース座標へ戻すにはこのオプションを外して再ビルドしてください。
97
+
87
98
  プロジェクト固有のテストに加えて、生成SB3をTurboWarpで開き、起動、主要な操作、画像、音声、埋め込み
88
99
  機能拡張の動作を確認してください。
89
100
 
90
101
  ## 管理対象の埋め込み機能拡張
91
102
 
92
- `embedded-extensions.json`の`source`オブジェクトには、GitHubリポジトリ、追跡対象ref、解決済みコミット、
93
- 成果物パス、SHA-256を記録できます。更新時の静的互換性検査に使用するバージョン付きAPIマニフェストも任意で
94
- 設定できます。完全なスキーマは[`source-format-v1.md`](source-format-v1.md)を参照してください。
103
+ `embedded-extensions.json`の`source`オブジェクトには、GitHubコミットの来歴またはインストール済みnpm
104
+ パッケージの完全固定バージョンと、成果物パス、SHA-256を記録できます。更新時の静的互換性検査に使用する
105
+ バージョン付きAPIマニフェストも任意で設定できます。完全なスキーマは
106
+ [`source-format-v1.md`](source-format-v1.md)を参照してください。
95
107
 
96
108
  機能拡張コマンドの役割は次のとおりです。
97
109
 
98
- | コマンド | ネットワーク | refの解決 | メタデータ更新 | 目的 |
99
- | ----------------------- | ------------ | --------- | -------------- | -------------------------------------- |
100
- | `extensions status` | あり | あり | なし | 追跡対象refに更新があるか確認 |
101
- | `extensions sync` | あり | なし | なし | 固定したコミットからファイルを復元 |
102
- | `extensions update` | あり | あり | あり | 最新のrefコミットへ明示的に更新 |
103
- | `extensions migrate-id` | なし | なし | ID/参照 | プロジェクトで使用中の機能拡張IDを移行 |
104
- | `extensions bundle` | なし | なし | bundle設定 | 機能拡張を1つの権限単位へ統合 |
105
- | `extensions unbundle` | なし | なし | 設定またはSB3 | 個別機能拡張を使用する出力へ復元 |
110
+ | コマンド | ネットワーク | refの解決 | メタデータ更新 | 目的 |
111
+ | ----------------------- | ------------ | ---------- | -------------- | -------------------------------------- |
112
+ | `extensions status` | GitHubのみ | GitHubのみ | なし | 上流または導入済みパッケージを確認 |
113
+ | `extensions sync` | GitHubのみ | なし | なし | 宣言したsourceからファイルを復元 |
114
+ | `extensions update` | GitHubのみ | GitHubのみ | あり | 上流または導入済みパッケージを採用 |
115
+ | `extensions migrate-id` | なし | なし | ID/参照 | プロジェクトで使用中の機能拡張IDを移行 |
116
+ | `extensions bundle` | なし | なし | bundle設定 | 機能拡張を1つの権限単位へ統合 |
117
+ | `extensions unbundle` | なし | なし | 設定またはSB3 | 個別機能拡張を使用する出力へ復元 |
106
118
 
107
119
  ### 更新の確認
108
120
 
@@ -110,8 +122,8 @@ sb3-toolchain build app --output dist/project.sb3
110
122
  sb3-toolchain extensions status app
111
123
  ```
112
124
 
113
- `status`はローカルファイルを変更しません。追跡対象refが`resolvedCommit`と異なる機能拡張について上流の
114
- 変更を確認し、更新するかどうかを判断します。
125
+ `status`はローカルファイルを変更しません。GitHub sourceでは追跡対象refと`resolvedCommit`を比較します。
126
+ npm sourceでは、宣言した完全固定バージョンとインストール済みパッケージをネットワークなしで比較します。
115
127
 
116
128
  ### 固定したコミットからの復元
117
129
 
@@ -120,9 +132,9 @@ sb3-toolchain extensions sync app
120
132
  sb3-toolchain check app
121
133
  ```
122
134
 
123
- `sync`は変更可能なブランチやタグを解決しません。記録済みの`resolvedCommit`からダウンロードし、
124
- JavaScriptと任意のAPIマニフェストが記録済みIDおよびSHA-256値に一致する場合に限り、ローカルファイルを
125
- 置き換えます。
135
+ `sync`は変更可能なブランチやタグを解決しません。GitHub sourceは`resolvedCommit`からダウンロードし、
136
+ npm sourceは最寄りの親`node_modules`へ導入済みの完全固定パッケージから読み込みます。JavaScriptと任意の
137
+ APIマニフェストが記録済みIDおよびSHA-256値に一致する場合に限り、ローカルファイルを置き換えます。
126
138
 
127
139
  ### 追跡対象refの更新
128
140
 
@@ -136,6 +148,10 @@ git diff -- app
136
148
  IDを省略すると、管理対象の全機能拡張を1回のトランザクションで更新します。ダウンロードまたは検証が1つでも
137
149
  失敗した場合、ファイルもメタデータも変更しません。
138
150
 
151
+ npm sourceでは、最初にプロジェクトのパッケージマネージャーで新しい完全固定バージョンを導入し、続けて
152
+ `extensions status`と`extensions update`を実行します。updateは導入済み成果物をコピーし、パッケージの
153
+ `version`とintegrityを記録します。sb3-toolchain自身はnpm registryへ問い合わせません。
154
+
139
155
  `source.apiManifest`が存在する場合、同じ解決済みコミットからJavaScriptとAPIマニフェストをダウンロードします。
140
156
  互換性のある追加は報告されます。ブロックの削除、ブロック種別の変更、引数契約の変更、参照中メニューの削除、
141
157
  `acceptReporters`の変更は、インストール前に拒否されます。未参照メニューの削除には互換性があります。
@@ -148,8 +164,8 @@ sb3-toolchain extensions update app EXTENSION_ID --allow-breaking-api --yes
148
164
  バージョン付きマニフェスト契約、分類表、既定OFFの動作、ロールバックについては、
149
165
  [`extension-api-compatibility.md`](extension-api-compatibility.md)を参照してください。
150
166
 
151
- 更新PRでは、`resolvedCommit`、JavaScriptとマニフェストのintegrity、互換性パス、両成果物をまとめて確認し、
152
- 生成SB3で機能拡張の主要機能をテストします。
167
+ 更新PRでは、`resolvedCommit`またはnpmの`version`、JavaScriptとマニフェストのintegrity、互換性パス、
168
+ 両成果物をまとめて確認し、生成SB3で機能拡張の主要機能をテストします。
153
169
 
154
170
  ## 機能拡張IDの移行
155
171