@kubohiroya/sb3-toolchain 0.16.0 → 0.17.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/dist/types.d.ts CHANGED
@@ -21,6 +21,13 @@ export interface NpmExtensionSource {
21
21
  artifact: string;
22
22
  integrity: string;
23
23
  apiManifest?: ExtensionApiManifestSource;
24
+ module?: ExtensionModuleSource;
25
+ }
26
+ export interface ExtensionModuleSource {
27
+ artifact: string;
28
+ formatVersion: 1;
29
+ integrity: string;
30
+ unsandboxed: 'required' | 'optional' | 'not-needed';
24
31
  }
25
32
  export type ExtensionSource = GitHubExtensionSource | NpmExtensionSource;
26
33
  export type ExtensionEncoding = 'base64' | 'percent';
@@ -39,6 +46,8 @@ export interface ExtensionBundleConfiguration {
39
46
  recoveryCapsule?: boolean;
40
47
  sandboxedNotice?: Record<string, string>;
41
48
  blockEditorRegistrations?: boolean;
49
+ buildMode?: 'classic' | 'module';
50
+ sharedDependencies?: Record<string, string>;
42
51
  }
43
52
  export interface EmbeddedExtensionManifest {
44
53
  formatVersion: number;
@@ -9,6 +9,111 @@ one extension.
9
9
 
10
10
  ## Overview
11
11
 
12
+ The default `classic` mode wraps completed scripts. To share their dependencies too, opt in to the
13
+ module build described below. The remaining classic runtime and recovery documentation also applies
14
+ to module bundles unless noted.
15
+
16
+ ## Module builds (off by default)
17
+
18
+ Every member must provide an installed npm JavaScript entry exporting `createExtension(scratch)` and
19
+ `bundleModuleMetadata` (`formatVersion: 1`, `id`, `unsandboxed`). Importing it must not activate an
20
+ extension, register one, or connect listeners. The factory synchronously returns a fresh instance
21
+ using the supplied member Scratch proxy. The composite calls each factory once and registers once.
22
+
23
+ Add a `module` declaration to each member's existing npm `source`. Replace the digest placeholders
24
+ with the SHA-256 of the respective files:
25
+
26
+ ```json
27
+ {
28
+ "provider": "npm",
29
+ "package": "@example/extension-one",
30
+ "version": "1.0.0",
31
+ "artifact": "dist/extension-one.js",
32
+ "integrity": "sha256-<base64 classic digest>",
33
+ "module": {
34
+ "artifact": "lib-module/src/bundle-module.js",
35
+ "formatVersion": 1,
36
+ "integrity": "sha256-<base64 module digest>",
37
+ "unsandboxed": "required"
38
+ }
39
+ }
40
+ ```
41
+
42
+ Select the build and exact shared versions on the bundle:
43
+
44
+ ```json
45
+ {
46
+ "id": "projectbundle",
47
+ "name": "Project Extension Bundle",
48
+ "members": ["extensionone", "extensiontwo"],
49
+ "buildMode": "module",
50
+ "sharedDependencies": {"yaml": "2.9.1"},
51
+ "blockEditorRegistrations": true
52
+ }
53
+ ```
54
+
55
+ Install the pinned owner packages and shared dependencies in the project's `node_modules` first,
56
+ retaining either `pnpm-lock.yaml` or `package-lock.json`. Parent directories of the expanded source
57
+ are searched. The toolchain's own yaml is not a shared input. Builds do not install packages, clone
58
+ repositories, execute owner code, or load project build configurations or plugins. The initial module
59
+ scope is installed npm artifacts; GitHub sources continue to use classic mode.
60
+
61
+ ```bash
62
+ sb3-toolchain extensions bundle app --id projectbundle --name "Project Extension Bundle" \
63
+ extensionone extensiontwo --build-mode module --share yaml@2.9.1
64
+ # Review the plan, then repeat with --yes to save it.
65
+ sb3-toolchain build app --output dist/project.sb3
66
+ ```
67
+
68
+ `bundleExtensions` and `planExtensionBundle` also accept `buildMode` and `sharedDependencies`.
69
+ Repeat `--share` for additional packages. GUI editor adaptation remains an explicit manifest option.
70
+
71
+ The resolver checks the selected version against each importer's declared range and uses one real
72
+ package under browser conditions. yaml must use its browser entry; duplicate copies or mixed Node
73
+ and browser graphs fail. Missing entries, mismatched package versions, classic artifacts, module
74
+ digests, and unsupported contracts also fail. A required sandbox guard runs before any library
75
+ evaluation or factory activation; without permission only the existing notice extension registers.
76
+ All member metadata is checked before any factory activates. If a later factory fails, prior
77
+ instances are disposed. The composite's `dispose()` cleans up each member once.
78
+
79
+ The `moduleBuild` report on bundle plans and `createDeterministicSb3(...).bundlePlans[]` records the
80
+ bundler version, browser / ES2020 settings, lock digest, member entries, loaded files and package
81
+ manifest digests, and shared package copy counts. `Module build inputs` in the generated JS hashes
82
+ this record; absolute paths are omitted. The lock is hashed as an input alongside the actual installed
83
+ files, so install from the lock when reproducing a build. When updating an owner, update both classic
84
+ and module integrity pins. A stale module pin rejects the candidate while retaining the source.
85
+
86
+ Library code and module evaluation are shared per bundle load. Parser, Composer, Document, and other
87
+ parse state remain independent for each input. Other bundles and separate GUI graphs are outside
88
+ this scope. Existing owner feature flags, IDs, opcodes, and parse options stay intact.
89
+
90
+ ### Verification and rollback
91
+
92
+ Regular tests deliberately install private copies of the same yaml version under multiple members.
93
+ To verify the actual unpublished owner entries, build their clean checkouts first, then run:
94
+
95
+ ```bash
96
+ node scripts/prepare-module-owner-fixture.mjs /tmp/new-module-owners \
97
+ /path/to/turbowarp-structured-data /path/to/turbowarp-yaml-json /path/to/turbowarp-3d-scene-runtime
98
+ SB3_MODULE_OWNER_FIXTURE=/tmp/new-module-owners/app pnpm exec vitest run test/extension-module-owners.test.ts
99
+ ```
100
+
101
+ The preparation script packs local artifacts and installs production dependencies with lifecycle
102
+ scripts disabled. The owner test runs only with the environment variable; ordinary CI skips it.
103
+ It writes `module-owner-results.json` (including owner commits and input digests), `shared-yaml.js`,
104
+ and `shared-yaml.sb3` beside `app`. Evaluation and factory counters are injected only into the test
105
+ build; size and reproducibility measurements use uninstrumented output. Tests also cover parsing,
106
+ runtime Schema validation, editor registration and cleanup, sandbox handling, and recovery.
107
+
108
+ To roll back, omit `buildMode` or set it to `classic`, remove `sharedDependencies`, and rebuild from
109
+ the retained classic scripts. That path needs neither installed module dependencies nor a lock.
110
+ Source-based unbundling is unchanged. Direct unbundling from an SB3 still requires the separate
111
+ `recoveryCapsule: true` option. The capsule contains original classic scripts as data, increasing
112
+ artifact size even though the executing shared library has one copy. Measure sizes with it disabled.
113
+ Actual browser permission dialogs and GUI interaction still need the manual checks below.
114
+
115
+ ## Classic overview
116
+
12
117
  ```mermaid
13
118
  flowchart LR
14
119
  subgraph Source["Expanded source (authoritative)"]
package/docs/index.html CHANGED
@@ -49,7 +49,7 @@
49
49
  <body>
50
50
  <header>
51
51
  <h1>SB3 Toolchain</h1>
52
- <p><code>@kubohiroya/sb3-toolchain@0.16.0</code></p>
52
+ <p><code>@kubohiroya/sb3-toolchain@0.17.0</code></p>
53
53
  <nav aria-label="Documentation">
54
54
  <a href="#scope">責務</a><a href="#usage">使い方</a><a href="#api">API</a
55
55
  ><a href="#schemas">Schema</a><a href="#guides">関連文書</a>
@@ -70,7 +70,7 @@
70
70
  <section id="usage">
71
71
  <h2>使い方</h2>
72
72
  <p>公開済みの完全固定versionを使います。</p>
73
- <pre><code>npm install --save-exact @kubohiroya/sb3-toolchain@0.16.0</code></pre>
73
+ <pre><code>npm install --save-exact @kubohiroya/sb3-toolchain@0.17.0</code></pre>
74
74
  <pre><code>sb3-toolchain import tmp/project.sb3 --output app
75
75
  sb3-toolchain check app
76
76
  sb3-toolchain build app --output dist/project.sb3</code></pre>
@@ -8,6 +8,105 @@
8
8
 
9
9
  ## 概要
10
10
 
11
+ 既定の`classic`方式は完成済みJSを束ねます。依存ライブラリも共有する場合は、以下のmodule方式を明示的に選びます。
12
+
13
+ ## module統合ビルド(既定OFF)
14
+
15
+ 全メンバーが`./bundle-module`の契約に対応する場合、単一のbrowser向け依存graphから複合JSを生成できます。
16
+ 入口は`createExtension(scratch)`と`bundleModuleMetadata`(`formatVersion: 1` / `id` / `unsandboxed`)をexportします。
17
+ import時に拡張の生成・登録・listener接続を行わず、factoryは注入されたScratchを使用して同期的に新規instanceを返します。
18
+ toolchainはメンバーごとのScratch proxyを渡して各factoryを1回呼び、外部への登録を複合拡張の1回にまとめます。
19
+
20
+ `embedded-extensions.json`の各メンバーの既存npm `source`へ、package内のJS入口を追加します。
21
+ 次の例のintegrityは実際のファイルのSHA-256に置き換えてください。
22
+
23
+ ```json
24
+ {
25
+ "provider": "npm",
26
+ "package": "@example/extension-one",
27
+ "version": "1.0.0",
28
+ "artifact": "dist/extension-one.js",
29
+ "integrity": "sha256-<classic JSのbase64 digest>",
30
+ "module": {
31
+ "artifact": "lib-module/src/bundle-module.js",
32
+ "formatVersion": 1,
33
+ "integrity": "sha256-<module JSのbase64 digest>",
34
+ "unsandboxed": "required"
35
+ }
36
+ }
37
+ ```
38
+
39
+ bundle側には次を指定します。
40
+
41
+ ```json
42
+ {
43
+ "id": "projectbundle",
44
+ "name": "Project Extension Bundle",
45
+ "members": ["extensionone", "extensiontwo"],
46
+ "buildMode": "module",
47
+ "sharedDependencies": {"yaml": "2.9.1"},
48
+ "blockEditorRegistrations": true
49
+ }
50
+ ```
51
+
52
+ 対応する固定版packageと共有yamlをプロジェクトの`node_modules`へ事前installし、`pnpm-lock.yaml`または
53
+ `package-lock.json`を保持します。`app`のような展開ソースの親directoryも探索対象です。
54
+ toolchain自身のyamlは共有入力として使用しません。ビルド時にinstall、repository clone、拡張コードや
55
+ project側のビルド設定・pluginの実行は行いません。初期対応はinstall済みnpm artifactで、GitHub sourceはclassicを使います。
56
+
57
+ ```bash
58
+ sb3-toolchain extensions bundle app --id projectbundle --name "Project Extension Bundle" \
59
+ extensionone extensiontwo --build-mode module --share yaml@2.9.1
60
+ # 表示された計画を確認後、同じ指定に --yes を付けて保存する。
61
+ sb3-toolchain build app --output dist/project.sb3
62
+ ```
63
+
64
+ APIは`bundleExtensions` / `planExtensionBundle`の`buildMode`と`sharedDependencies`でも指定できます。
65
+ `--share`は複数指定でき、完全な版番号を要求します。GUIの編集登録変換は従来どおりmanifestで明示選択します。
66
+
67
+ 共有packageの要求範囲と選択版を照合し、browser条件で同じ実体へ解決します。yamlはbrowser入口に限定し、
68
+ 別コピーやNode向け実装が混ざるgraphを拒否します。版・classicとの一致・module integrity・対応入口不足も診断します。
69
+ 必要なunsandboxed権限を得られなければ、ライブラリ評価やfactory生成より前に従来の案内拡張だけを登録します。
70
+ 実行時には全メンバーのmetadataを確認してから初期化し、途中でfactoryが失敗した場合は先行instanceをdisposeします。
71
+ 複合拡張の`dispose()`は各メンバーを一度だけ解除します。
72
+
73
+ `createDeterministicSb3(...).bundlePlans[].moduleBuild`とbundle計画の`moduleBuild`には、bundlerの版、browser / ES2020設定、
74
+ lockのdigest、各入口と読み込んだ依存ファイル・package manifestのdigest、共有実体数を返します。
75
+ 生成JSの`Module build inputs`コメントはこの入力記録のdigestです。絶対pathは記録へ含めません。
76
+ 依存lockは入力としてhash化し、実際のinstall内容も記録するため、再現時にはlockに従ってinstallしてください。
77
+ ownerの更新時はclassicとmodule両方のintegrityを更新します。module pinが古い場合、更新候補の検証は失敗して既存ソースを保持します。
78
+
79
+ 共有するのはbundle読込単位のライブラリ実装とmodule評価です。Parser / Composer / Document等の解析状態は
80
+ 従来どおり入力ごとに生成し、別bundleやGUIの別graphをまたぐsingletonにはしません。
81
+ 既存feature flag、保存ID、opcode、解析オプションは変更しません。
82
+
83
+ ### 検証と切戻し
84
+
85
+ 通常のテストには、同版yamlを各メンバーの下に重複配置したfixtureを含めます。
86
+ 未公開の実owner入口を検証する場合は、3つのcleanなcheckoutを次の順番で渡します。
87
+ 事前に各ownerをbuildしておきます。この準備scriptはローカルでpackし、lifecycle scriptを無効にしてproduction installします。
88
+
89
+ ```bash
90
+ node scripts/prepare-module-owner-fixture.mjs /tmp/new-module-owners \
91
+ /path/to/turbowarp-structured-data /path/to/turbowarp-yaml-json /path/to/turbowarp-3d-scene-runtime
92
+ SB3_MODULE_OWNER_FIXTURE=/tmp/new-module-owners/app pnpm exec vitest run test/extension-module-owners.test.ts
93
+ ```
94
+
95
+ 実owner検証は環境変数の指定時に実行し、通常CIではskipします。結果・全入力digest・owner commitはfixture親の
96
+ `module-owner-results.json`、生成物は`shared-yaml.js` / `shared-yaml.sb3`へ保存します。
97
+ module評価とfactoryのcounterはテスト用transformだけに挿入し、サイズと再現性はcounterを含まない生成物で測定します。
98
+ 解析・Schema検証・編集登録 / 解除・権限分岐・復元カプセルも検証します。
99
+
100
+ 切戻しは`buildMode`を未指定または`classic`にし、`sharedDependencies`を削除して再生成します。
101
+ 元classic JSを保持しているためmodule依存やlockなしでも生成できます。設定を削除するsourceのunbundleも従来どおりです。
102
+ SB3単体からの解除には`recoveryCapsule: true`を別途選択してください。カプセルは元classic JSをデータとして含むため、
103
+ 実行される共有実装が1組でも成果物サイズは増えます。計測時はカプセルをOFFにします。
104
+ ブラウザ上の実際の権限dialogやGUI操作は、後述の手動検証項目で確認してください。
105
+
106
+ ## classic方式の概要
107
+
108
+ 以下は既定classic方式の説明です。module方式でも同じopcode / storage / 編集binding変換と復元処理を使用します。
109
+
11
110
  ```mermaid
12
111
  flowchart LR
13
112
  subgraph Source["展開ソース(信頼できる情報源)"]
@@ -169,6 +169,8 @@ APIマニフェストファイルは展開ソースの検証入力であり、SB
169
169
  LABELエントリとseparatorは変更されない
170
170
  - `recoveryCapsule`: 任意の真偽値で、既定値は`false`。追加サイズを許容でき、生成SB3単体からの直接unbundleが
171
171
  必要な場合に限り`true`を指定する
172
+ - `buildMode`: 任意の`classic`(既定)または`module`。module方式では各メンバーのnpm `source.module`にJS artifact、formatVersion 1、SHA-256 integrity、明示的な`unsandboxed`要件を指定し、ownerコードを実行せず単一のbrowser依存graphをビルドする
173
+ - `sharedDependencies`: module方式だけで指定できるpackage名と完全な版番号の対応表。projectへlock付きで事前installし、互換な依存を同じ実体へ解決する。[module統合ビルドの説明](extension-bundles.md#module統合ビルド既定off)を参照
172
174
  - `sandboxedNotice`: 任意のオブジェクトで、bundleがサンドボックス内で読み込まれたときの通知文を小文字の言語タグ
173
175
  ごとに指定する。メンバーの`// Unsandboxed:`ヘッダーによってbundleが`required`または`optional`になる場合だけ
174
176
  指定でき、省略時は内蔵の`en`と`ja`の通知文を使う。[`extension-bundles.md`](extension-bundles.md)を参照
@@ -173,6 +173,8 @@ only in the generated SB3.
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
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
176
+ - `buildMode`: optional `classic` (default) or `module`. Module mode requires each member's npm `source.module` JavaScript artifact, format 1, SHA-256 integrity, and explicit `unsandboxed` requirement. It builds one browser dependency graph without executing owner code
177
+ - `sharedDependencies`: optional package-to-exact-version map, allowed only in module mode. The selected packages must be installed in the project with a dependency lock; compatible member imports share one real package. See the [module build guide](extension-bundles.md#module-builds-off-by-default)
176
178
  - `sandboxedNotice`: optional object mapping lowercase language tags to the message shown when the bundle is loaded sandboxed. Allowed only when a member's `// Unsandboxed:` header makes the bundle `required` or `optional`; built-in `en` and `ja` messages apply otherwise. See [`extension-bundles.md`](extension-bundles.md#declare-unsandboxed-loading)
177
179
 
178
180
  A member cannot belong to more than one bundle. Individual entries, individual JavaScript, `source`,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kubohiroya/sb3-toolchain",
3
- "version": "0.16.0",
3
+ "version": "0.17.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",
@@ -54,10 +54,13 @@
54
54
  "dependencies": {
55
55
  "fflate": "0.8.3",
56
56
  "music-metadata": "11.14.0",
57
+ "rolldown": "1.2.7",
58
+ "semver": "7.8.5",
57
59
  "yaml": "2.9.0"
58
60
  },
59
61
  "devDependencies": {
60
62
  "@types/node": "^24.0.0",
63
+ "@types/semver": "7.8.0",
61
64
  "@vitest/eslint-plugin": "^1.6.27",
62
65
  "eslint": "^9.0.0",
63
66
  "jiti": "^2.7.0",
@@ -77,5 +80,11 @@
77
80
  "turbowarp",
78
81
  "source-control",
79
82
  "reproducible-builds"
80
- ]
83
+ ],
84
+ "gitHead": "bbaf527a47e7884c11908c889e97e33c6edba4bb",
85
+ "x-turbowarp-source": {
86
+ "revision": "bbaf527a47e7884c11908c889e97e33c6edba4bb",
87
+ "revisionRole": "base-commit",
88
+ "sourceState": "local-release-overlay"
89
+ }
81
90
  }