TurboWarp-Plus-Editor 開発者ガイド

Scratch 3 の公式エディターには、利用者が機能を足すための仕組みがありません。そこを埋めたのが、有志のブラウザー拡張 Scratch Addons です。scratch.mit.edu のページにスクリプトを注入し、画面の要素や内部の状態を外から探して機能を付け足します。

TurboWarp は、この Scratch Addons のうちエディター向けのものを取り込み、自分のビルドに同梱しました。書き方も API もほぼ同じですが、ブラウザー拡張ではなくエディターの一部として動きます。

TurboWarp-Plus-Editor はこの向きを逆にしました。フォークした scratch-gui に「ここで何か渡されていれば使う」という名前付きの口を置き、ビルド時に Plus 側の実装をそこへ結び付けます。何も渡されなければ、フォークは本家の TurboWarp と同じに動きます。

アドオンの方式は、エディター本体に手を入れずに済みます。そのかわり、画面の構造が変わると黙って効かなくなります。Plus の方式はフォークに呼び出しの行が残りますが、契約が型とテストで固定され、作品の読み込みより前に効かせる処理やレイアウト全体の置き換えまで扱えます。

Plus の主な機能はレイアウト、拡張の審査、保存の流れです。これらは「外から付け足す」モデルに収まらないので、Plus がアドオン互換を目指す意味は大きくありません。外して戻せる小さな機能については、アドオンと同じく後から付けて外せる形で書くことにしています。

Scratch Addons は Chrome や Firefox に入れるブラウザー拡張です。アドオンは1つずつマニフェストを持ち、名前・説明・タグ・設定項目・既定で有効かどうか・どのページで動くかを宣言します。条件に合うページを開くと、ブラウザー拡張が userscript と userstyle をそのページに注入します。

userscript は ({addon, console, msg}) を受け取る非同期関数です。addon.tab の waitForElement で画面要素の出現を待ち、traps で VM や Blockly を手に入れ、Redux の状態を見張ります。公式エディターには口がないので、すべてを外から探し当てます。

TurboWarp は Scratch Addons のエディター向けアドオンを、pull.js というスクリプトで自分のソースに取り込みます。上流のコードに TurboWarp 用のパッチ（TurboWarp/addons の tw ブランチ）を当て、さらに正規表現で書き換えてから src/addons/ に置きます。今のフォークには 81 件が入っていて、そのうち 6 件は TurboWarp 独自の tw- アドオンです。

実行時は、api.js が Scratch Addons の addon オブジェクトを作り直して渡します。ログイン情報のようにブラウザー拡張にしかない API はありません。そのかわり、appendToSharedSpace の共有スペース（stageHeader、fullscreenStageHeader、afterGreenFlag、afterStopButton、afterSoundTab、monitor、paintEditorZoomControls と、アセットの右クリックメニューの2か所、合わせて 9 か所）のように、TurboWarp の画面に合わせた置き場所が用意されています。メニューバーに「録画」ボタンを足す mediarecorder も、この仕組みでファイルメニューの横の要素を探して差し込みます。

Plus はフォークした scratch-gui に、本家に無いファイルを1つも置きません。本家にもある src/addons/hooks.js に getHostIntegration() を置き、hooks.js 以外の 28 のファイルが getHostIntegration()?.EditorLayout のように名前を指定して問い合わせます。

配信用のビルドでは、webpack の ProvidePlugin が __TW_GUI_HOST__ を本リポジトリの site/gui-integration/index.ts に結び付けます。そこから site/plus-integration.ts の統合オブジェクトと、npm で版を持つ @kubohiroya/turbowarp-* パッケージへつながります。GUI を単体でビルドすると __TW_GUI_HOST__ は存在せず、getter は null を返し、本家どおりに動きます。

三つの方式は、機能がいつ効き始めるかが違います。アドオンはページや GUI が動き出してから非同期に付くので、作品の読み込みより前に必ず効いていなければならない処理には向きません。Plus は、拡張の審査のように読み込みの前に決まっていなければならない処理を、口として同期的に渡せます。

アドオンは CSS モジュールのクラス名を前方一致で探します（scratchClass、[class*='menu-bar_file-group'] など）。本家が画面の構造を変えると、探し当てられずに何も起きません。Plus の口はフォークのソースに書かれた呼び出しなので、本家の変更とぶつかればマージの衝突や型検査、統合テストで止まります。

Plus の追加機能を「付け足すか、置き換えるか」と「利用者が切ってよいか、常に効いている必要があるか」の二つの軸で並べると、アドオンの形に寄せられるのは左上の区画だけです。

TurboWarp-Plus-Editor が TurboWarp に機能を足すには、アドオンの方式よりも、フォークに名前付きの口を置いてビルド時に実装を結び付ける今の方式が適しています。理由は次の6つです。

そのうえで、図7の A に当たる小さな機能は、アドオンと同じく「後から付けて、dispose で外せる」形で書きます。こうしておけば、利用者が切り替えられるようにしたくなったとき、アドオンの形へ移しやすくなります。既存の機能をアドオン互換に作り直す作業は行いません。

Plus の追加機能は3つのリポジトリにまたがります。依存は一方向で、上流は下流を知りません。

フォークの src/addons/hooks.js は次の getter を持ちます。本家にも存在するファイルです。

/* global __TW_GUI_HOST__ */
// The distributing build supplies this module; standalone GUI builds have no extra host.
export const getHostIntegration = () =>
    (typeof __TW_GUI_HOST__ === 'undefined' ? null : __TW_GUI_HOST__);

配信ビルドの scripts/site/webpack.config.cts が ProvidePlugin で __TW_GUI_HOST__ を site/gui-integration/index.ts に結び付けます。実行時の global への代入や起動順には依存しません。フォークが読む値は2層になっています。

フォークが参照している口を用途ごとに並べます。左の名前はフォークが getHostIntegration()?. の後に書く名前、右の項目は統合オブジェクトの項目です。menu-bar.jsx と extension-library.jsx は getHostIntegration() をいったん変数 host に受けてから読むので、最新の一覧はフォークの checkout で次の2つのコマンドを合わせて取り出します。hostIntegration は口ではなく、host… 補助関数に統合オブジェクトを渡すための getter です。

表は 2026年11月14日に、固定しているフォーク（f1e8f96）で取り出したものです。

grep -rhoE "getHostIntegration\(\)\?\.[A-Za-z]+" src | sort | uniq -c
grep -hoE "host\??\.[A-Za-z]+" src/components/menu-bar/menu-bar.jsx src/containers/extension-library.jsx | sort -u

すべての口は次の約束を守ります。新しい口を開けるときも同じです。

1. 任意であること。値が無ければ、フォークは本家の TurboWarp と同じに動きます。補助関数は空の既定値（[]、{}、null）を返します。
2. GUI 内部の値は引数で受け取ること。ホストはフォークの reducer や UI を import しません。Modal、遅延読み込みの ScratchBlocks、logger、Redux の action creator は、フォークが呼び出し時に渡します（例：createCancelSecurityLoad(initialState, defaultProjectId, LoadingState, integration)）。
3. 付けたものは外せること。何かを付ける口は {dispose()} を返します。フォークは VM が替わるたびに前の戻り値を dispose() してから呼び直し、戻り値の中は見ません。
4. VM ごとに同じサービスを返すこと。操作欄のように二か所から読まれるサービスは、VM をキーにした WeakMap で1つに保ちます。
5. CSS の口は作らないこと。本家の CSS モジュールのクラス名はビルド時にハッシュされ、外から狙えません。新しい部品は自分のクラスとスタイルをパッケージ側に持ち、色は GUI の公開テーマ変数を使います。
6. 独自のファイルをフォークに足さないこと。フォークに残すのは口を呼ぶ行だけです。テストもフォークには足さず、このリポジトリの test/ とパッケージ側に置きます。

attachToWorkspace は、Blockly や VM に付く機能をまとめて取り付ける口です。アドオンの userscript に最も近い形をしています。

ScratchBlocks が使えるようになった時点で一度だけ行う登録（ブロックの形、右クリックメニュー、パレットへの項目の追加）は、registerBlockShapes(ScratchBlocks) に置きます。アドオンの起動を待つ必要があるときは、そのアドオンの id を awaitStartupAddons に書きます（今は editor-searchable-dropdowns）。

非サンドボックスの拡張は Scratch.gui から次の値を読めます。本家にある getBlockly と getBlocklyEagerly に加え、ホストが値を渡したときだけ次の項目が生えます。値が無いときは undefined のままなので、拡張は「このビルドには無い」と判断できます。

addButton で足したボタンは visible: false で始まります。表示するには update({visible: true}) を呼びます。update で変えられるのは label、text、visible、expanded の4つです。展開したときに見せる要素は、サービスの placePanel(element) でホストに渡します。要素の持ち主は登録した側で、ホストは取り付けるだけです。

機能の有効・無効は、ページの URL クエリ twPlus… で起動時に一度だけ決まります。config/web-startup-feature-flags.ts が URL を読み、config/feature-flags.ts の readStartupFeatureFlags が凍結したオブジェクトを返します。作品のデータからこの値を受け取ってはいけません。

• 既定の有効化：site/addon-manifests.ts が、webpack の alias でフォークの generated/addon-manifests を置き換えます。「おすすめ」タグの付いたアドオンと hide-delete-button、block-palette-icons を既定で有効にし、hide-flyout は無効のままにします。利用者が設定画面で選んだ値が優先されます。
• 起動待ち：awaitStartupAddons に書いたアドオンは、実行器がその起動を待ってから次へ進みます。
• 右クリックメニュー：api.js の createBlockContextMenu は、項目を確定する前に finalizeHostTransferMenu を通します。スクリプト転送のメニューはここで足されます。

最初に、機能がどの経路でエディターに届くかを決めます。下の図の上から順に当てはめ、最初に「はい」になったところが置き場所です。

実装はパッケージのリポジトリで先に公開し、Editor はその npm 公開版に上げてからつなぎます。新しい口が要るときは、フォークの変更を並行して進め、Editor で SHA を固定します。

追加機能が出すダイアログやパネルは、次の形に揃えます。

• 下部の操作ボタン：右端にまとめ、キャンセルを左、保存・適用などの主操作を右に置きます。共通の tw-plus-dialog-actions を使い、ボタンの data-dialog-action に cancel、close、confirm、delete のいずれかを指定します。文字のラベルを残し、キャンセルと閉じるには×、保存・確定にはチェック、削除にはごみ箱のアイコンを添えます。
• 見出しの横の閉じるボタン：パネルやダイアログの右上に置く閉じるボタンには「閉じる」「Close」の文字を出さず、×アイコンだけにします。名前は翻訳した title と aria-label で示します。
• 文字列：表示する文字列は ja と en の翻訳を持ちます（ひらがな表示が要るものは ja-hira も）。