@kubohiroya/sb3-toolchain 0.13.0 → 0.15.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.
@@ -61,7 +61,21 @@ Add `apiManifest` below an existing GitHub `source` object:
61
61
 
62
62
  - `artifact` is the manifest path in the GitHub repository.
63
63
  - `path` must be `extensions/<extensionId>.manifest.json` in expanded source.
64
- - `formatVersion` must be `1`.
64
+ - `formatVersion` must be `1` or `2`.
65
+
66
+ Version 2 adds, on every block, the metadata a server-side compiler needs to lower it: `resultType`,
67
+ `effect`, `immutable`, `errors` and `server`. Arguments may additionally carry `normalizesTo`,
68
+ `staticLiteral`, `minimum` and `maximum`. All five block fields are required together, and `effect`
69
+ must be one of `pure`, `immutable`, `control`, `request-read`, `response-write`, `storage-read`,
70
+ `storage-write`, `binary-read` or `binary-write`.
71
+
72
+ A comparison reports every change to that metadata as breaking, in both directions: a project can
73
+ rely on a block being immutable just as readily as on it not being. The two exceptions are a block
74
+ gaining server support and a block declaring a new error code, which only widen what the block
75
+ offers. A rise from version 1 to version 2 is compatible, because it only adds metadata no existing
76
+ project was reading; a fall from 2 to 1 is breaking, because it removes metadata a server may
77
+ already lower against.
78
+
65
79
  - `integrity` is the SHA-256 SRI value of the installed manifest file.
66
80
 
67
81
  The JavaScript and manifest artifacts use the same repository and `resolvedCommit`. Separate
@@ -360,6 +360,58 @@ Set `"recoveryCapsule": true` on a bundle, or pass `--include-recovery-capsule`
360
360
  to append an `SB3-Toolchain-Reversible-Bundle-v1` capsule. It records each original member data URL,
361
361
  member order, and the original `extensions` and `extensionURLs` order, at the cost of a larger output.
362
362
 
363
+ ### Declare unsandboxed loading
364
+
365
+ Each extension can declare, in its own header, whether the user must check TurboWarp's "Run
366
+ without sandbox" when allowing it:
367
+
368
+ ```js
369
+ // Name: Extension One
370
+ // ID: extensionone
371
+ // By: Example Author
372
+ // License: MPL-2.0
373
+ // Unsandboxed: required
374
+ ```
375
+
376
+ | Value | Meaning |
377
+ | ------------ | ---------------------------------------------------------- |
378
+ | `required` | The extension cannot work sandboxed |
379
+ | `optional` | It works sandboxed, but some features need unsandboxed use |
380
+ | `not-needed` | It works fully sandboxed |
381
+
382
+ Any other value fails the build. The declaration travels with the file, so it holds whether the
383
+ extension is bundled or loaded on its own; extensions without the line behave exactly as before.
384
+
385
+ A bundle derives its requirement from its members: `required` if any member is, otherwise
386
+ `optional` if any member is, and `not-needed` only when every member says so. The generated header
387
+ records the result as `// Unsandboxed:` along with each member's own value. TurboWarp's permission
388
+ dialog itself cannot be changed by an extension, so the bundle acts on what happens after the user
389
+ answers it:
390
+
391
+ - `required` and loaded sandboxed: no member runs. The bundle registers a placeholder under its
392
+ ID whose palette shows the bundle name and how to reload the project unsandboxed, and logs the
393
+ same text as a console error. Without it, a member that throws because it is sandboxed stops the
394
+ whole bundle: in TurboWarp's sandboxed iframe the project never finishes loading, and in a worker
395
+ the user sees only a generic load failure. With the placeholder the project loads, its bundle
396
+ blocks stay in the scripts, and loading the project again unsandboxed restores them.
397
+ - `optional` and loaded sandboxed: the members run, and the palette starts with a notice that some
398
+ features are unavailable, also logged as a console warning.
399
+ - `not-needed`, no declaration, or loaded unsandboxed: nothing is added.
400
+
401
+ The notices have built-in English and Japanese text and follow `Scratch.translate.language`,
402
+ falling back to the primary language subtag and then to English. Override or add locales with the
403
+ bundle's `sandboxedNotice`, an object mapping lowercase language tags to messages; `\n` starts a
404
+ new palette label. It is accepted only when the bundle derives `required` or `optional`:
405
+
406
+ ```json
407
+ {
408
+ "id": "projectbundle",
409
+ "name": "Project Extension Bundle",
410
+ "members": ["extensionone", "extensiontwo"],
411
+ "sandboxedNotice": {"de": "Projekt erneut laden\nund ohne Sandbox ausführen."}
412
+ }
413
+ ```
414
+
363
415
  ## Restore from expanded source
364
416
 
365
417
  Choose the restoration path based on which artifact is available:
@@ -60,7 +60,20 @@ flowchart LR
60
60
 
61
61
  - `artifact`はGitHubリポジトリ内のマニフェストのパスです。
62
62
  - `path`は展開ソース内の`extensions/<extensionId>.manifest.json`でなければなりません。
63
- - `formatVersion`は`1`でなければなりません。
63
+ - `formatVersion`は`1`または`2`でなければなりません。
64
+
65
+ バージョン2は、サーバー側コンパイラがブロックをloweringするために必要なメタデータを各ブロックに追加します。
66
+ `resultType`、`effect`、`immutable`、`errors`、`server`です。引数はさらに`normalizesTo`、`staticLiteral`、
67
+ `minimum`、`maximum`を持てます。ブロックの5つのフィールドは揃って必須で、`effect`は`pure`、`immutable`、
68
+ `control`、`request-read`、`response-write`、`storage-read`、`storage-write`、`binary-read`、
69
+ `binary-write`のいずれかでなければなりません。
70
+
71
+ 比較では、このメタデータの変更はどちら向きでも破壊的として報告します。ブロックがimmutableであることに
72
+ プロジェクトが依存しうるのと同様に、immutableでないことにも依存しうるためです。例外は2つで、ブロックが
73
+ サーバー対応を獲得した場合と、新しいエラーコードを宣言した場合です。どちらもブロックの提供範囲を広げる
74
+ だけです。バージョン1から2への上昇は互換です。既存のプロジェクトが読んでいなかったメタデータを追加する
75
+ だけだからです。2から1への下降は破壊的です。サーバーが既にloweringに使っているメタデータを失うためです。
76
+
64
77
  - `integrity`はインストール済みマニフェストファイルのSHA-256 SRI値です。
65
78
 
66
79
  JavaScript成果物とマニフェスト成果物は、同じリポジトリと`resolvedCommit`を使用します。別のリポジトリや
@@ -350,6 +350,57 @@ bundleに`"recoveryCapsule": true`を指定するか、設定時に`--include-re
350
350
  `SB3-Toolchain-Reversible-Bundle-v1`カプセルを追加します。カプセルは各メンバーの元のdata URL、メンバー順、
351
351
  元の`extensions`と`extensionURLs`の順序を記録しますが、出力サイズは増加します。
352
352
 
353
+ ### unsandboxedでの読み込みを宣言する
354
+
355
+ 各機能拡張は、許可するときにTurboWarpの「サンドボックスなしで実行する」へのチェックが必要かどうかを、
356
+ 自身のヘッダーで宣言できます。
357
+
358
+ ```js
359
+ // Name: Extension One
360
+ // ID: extensionone
361
+ // By: Example Author
362
+ // License: MPL-2.0
363
+ // Unsandboxed: required
364
+ ```
365
+
366
+ | 値 | 意味 |
367
+ | ------------ | ------------------------------------------------------------ |
368
+ | `required` | チェック必須。サンドボックス内では動作しない |
369
+ | `optional` | チェック任意。サンドボックス内でも動くが、一部機能が使えない |
370
+ | `not-needed` | チェック不要。サンドボックス内で完全に動作する |
371
+
372
+ それ以外の値はビルドエラーになります。宣言はファイルと一緒に移動するので、bundleしても単体で読み込んでも
373
+ 有効です。この行がない機能拡張の動作は従来と変わりません。
374
+
375
+ bundleの要件はメンバーから導出されます。いずれかが`required`なら`required`、そうでなくいずれかが
376
+ `optional`なら`optional`、全員が`not-needed`のときだけ`not-needed`です。生成ヘッダーには結果が
377
+ `// Unsandboxed:`として、各メンバー自身の値とともに記録されます。TurboWarpの権限ダイアログそのものは
378
+ 機能拡張から変更できないため、bundleはユーザーがそれに答えた後の動作を制御します。
379
+
380
+ - `required`でサンドボックス内に読み込まれた場合: メンバーを一切実行しません。bundle IDでプレースホルダーを
381
+ 登録し、パレットにbundle名とサンドボックスなしで開き直す手順を表示し、同じ内容をコンソールにエラーとして
382
+ 出力します。これがないと、サンドボックスのために例外を投げたメンバーがbundle全体を止めます。TurboWarpの
383
+ sandboxed iframeではプロジェクトの読み込みが終わらず、workerでは汎用的な読み込み失敗しか表示されません。
384
+ プレースホルダーがあればプロジェクトは読み込まれ、bundleのブロックはスクリプトに残り、サンドボックスなしで
385
+ 開き直すと元に戻ります。
386
+ - `optional`でサンドボックス内に読み込まれた場合: メンバーは実行され、パレットの先頭に一部機能が使えない旨の
387
+ 通知が表示され、コンソールにも警告が出力されます。
388
+ - `not-needed`、宣言なし、またはサンドボックスなしで読み込まれた場合: 何も追加しません。
389
+
390
+ 通知文は英語と日本語を内蔵し、`Scratch.translate.language`に従います。一致しない場合は主言語サブタグ、
391
+ 次に英語を使います。bundleの`sandboxedNotice`で、小文字の言語タグからメッセージへの対応を指定すると、
392
+ ロケールを上書き・追加できます。`\n`でパレットのラベルを改行します。bundleが`required`または
393
+ `optional`になる場合だけ指定できます。
394
+
395
+ ```json
396
+ {
397
+ "id": "projectbundle",
398
+ "name": "Project Extension Bundle",
399
+ "members": ["extensionone", "extensiontwo"],
400
+ "sandboxedNotice": {"de": "Projekt erneut laden\nund ohne Sandbox ausführen."}
401
+ }
402
+ ```
403
+
353
404
  ## 展開ソースからの復元
354
405
 
355
406
  利用可能な成果物に応じて復元経路を選択します。
@@ -97,7 +97,7 @@ npmパッケージから管理する機能拡張には、任意の`source`メタ
97
97
  - `apiManifest`: 任意で使用するAPI互換性メタデータ
98
98
  - `artifact`: 同じGitHubリポジトリを基準にしたAPIマニフェストのパス
99
99
  - `path`: 必須のローカルパス`extensions/<extensionId>.manifest.json`
100
- - `formatVersion`: 対応するマニフェスト形式。現在は`1`
100
+ - `formatVersion`: 対応するマニフェスト形式。`1`または`2`
101
101
  - `integrity`: インストール済みマニフェストのSRI形式SHA-256
102
102
 
103
103
  検証とビルドでは、ネットワークへ接続せずに管理対象機能拡張を検証します。
@@ -169,6 +169,9 @@ APIマニフェストファイルは展開ソースの検証入力であり、SB
169
169
  LABELエントリとseparatorは変更されない
170
170
  - `recoveryCapsule`: 任意の真偽値で、既定値は`false`。追加サイズを許容でき、生成SB3単体からの直接unbundleが
171
171
  必要な場合に限り`true`を指定する
172
+ - `sandboxedNotice`: 任意のオブジェクトで、bundleがサンドボックス内で読み込まれたときの通知文を小文字の言語タグ
173
+ ごとに指定する。メンバーの`// Unsandboxed:`ヘッダーによってbundleが`required`または`optional`になる場合だけ
174
+ 指定でき、省略時は内蔵の`en`と`ja`の通知文を使う。[`extension-bundles.md`](extension-bundles.md)を参照
172
175
 
173
176
  1つのメンバーを複数のbundleに所属させることはできません。個別エントリ、個別JavaScript、`source`、
174
177
  `project.source.json`が引き続き信頼できる情報源です。`build`は各元opcodeに`memberId + "__"`を加え、
@@ -98,7 +98,7 @@ For an exact npm dependency, replace the GitHub-specific fields with the package
98
98
  - `apiManifest`: optional, opt-in API compatibility metadata
99
99
  - `artifact`: API manifest path relative to the same GitHub repository
100
100
  - `path`: required local path `extensions/<extensionId>.manifest.json`
101
- - `formatVersion`: supported manifest format, currently `1`
101
+ - `formatVersion`: supported manifest format, `1` or `2`
102
102
  - `integrity`: SRI-form SHA-256 of the installed manifest
103
103
 
104
104
  Validation and builds verify managed extensions without accessing the network:
@@ -173,6 +173,7 @@ 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
+ - `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)
176
177
 
177
178
  A member cannot belong to more than one bundle. Individual entries, individual JavaScript, `source`,
178
179
  and `project.source.json` remain authoritative. `build` adds `memberId + "__"` to each original opcode
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kubohiroya/sb3-toolchain",
3
- "version": "0.13.0",
3
+ "version": "0.15.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",