@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.
- package/CHANGELOG.md +53 -0
- package/README.ja.md +1 -1
- package/README.md +1 -1
- package/dist/constants.d.ts +1 -1
- package/dist/constants.js +1 -1
- package/dist/constants.js.map +1 -1
- package/dist/extension-api-manifest.d.ts +44 -0
- package/dist/extension-api-manifest.js +194 -16
- package/dist/extension-api-manifest.js.map +1 -1
- package/dist/extension-bundle.d.ts +12 -1
- package/dist/extension-bundle.js +124 -9
- package/dist/extension-bundle.js.map +1 -1
- package/dist/extension-dependencies.d.ts +10 -0
- package/dist/extension-dependencies.js +14 -2
- package/dist/extension-dependencies.js.map +1 -1
- package/dist/index.d.ts +5 -4
- package/dist/index.js +4 -4
- package/dist/types.d.ts +1 -0
- package/docs/extension-api-compatibility.md +15 -1
- package/docs/extension-bundles.md +52 -0
- package/docs/ja/extension-api-compatibility.md +14 -1
- package/docs/ja/extension-bundles.md +51 -0
- package/docs/ja/source-format-v1.md +4 -1
- package/docs/source-format-v1.md +2 -1
- package/package.json +1 -1
|
@@ -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`:
|
|
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 + "__"`を加え、
|
package/docs/source-format-v1.md
CHANGED
|
@@ -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,
|
|
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