TurboWarp-Plus-Editor Developer Guide

The official Scratch 3 editor has no mechanism for users to add features. The community browser extension Scratch Addons fills that gap. It injects scripts into scratch.mit.edu pages, then looks for on-screen elements and internal state from the outside and adds features to them.

TurboWarp took the editor-oriented addons from Scratch Addons and bundled them into its own build. The code style and API are nearly the same, but they run as part of the editor instead of as a browser extension.

TurboWarp-Plus-Editor reverses the direction. Its fork of scratch-gui has named sockets that say "use this if something is supplied here", and the build binds Plus's implementation to them. When nothing is supplied, the fork behaves exactly like upstream TurboWarp.

The addon approach doesn't touch the editor itself. In exchange, when the page structure changes, addons silently stop working. The Plus approach leaves call lines in the fork, but its contracts are pinned by types and tests. It can also handle work that must take effect before a project loads, and replace the whole layout.

Plus's main features are the layout, extension review and the save flow. None of them fit the "add from outside" model, so there is little point in Plus aiming for addon compatibility. Small features that can be removed again are written, like addons, so they can be attached later and detached.

Scratch Addons is a browser extension for Chrome or Firefox. Each addon has its own manifest that declares its name, description, tags, settings, whether it is on by default and which pages it runs on. When you open a matching page, the browser extension injects the addon's userscripts and userstyles into it.

A userscript is an async function that receives ({addon, console, msg}). It waits for elements to appear with addon.tab.waitForElement, obtains the VM and Blockly through traps, and watches Redux state. The official editor has no sockets, so everything has to be found from the outside.

TurboWarp pulls the editor addons of Scratch Addons into its own source with a script called pull.js. It applies TurboWarp's patches to the upstream code (the tw branch of TurboWarp/addons), rewrites it further with regular expressions, and places the result in src/addons/. The current fork contains 81 addons, six of which are TurboWarp's own tw- addons.

At run time, api.js recreates the addon object of Scratch Addons and passes it in. APIs that only exist in a browser extension, such as login information, are absent. In their place there are spots tailored to TurboWarp's screen, such as the shared spaces of appendToSharedSpace (nine of them: stageHeader, fullscreenStageHeader, afterGreenFlag, afterStopButton, afterSoundTab, monitor, paintEditorZoomControls and two in the asset context menu). mediarecorder, which adds a "Record" button to the menu bar, also uses this mechanism: it looks for the element next to the File menu and inserts itself there.

Plus does not add a single file to its scratch-gui fork that upstream doesn't have. It puts getHostIntegration() in src/addons/hooks.js, a file upstream also has, and 28 files other than hooks.js ask for values by name, as in getHostIntegration()?.EditorLayout.

In the distributed build, webpack's ProvidePlugin binds __TW_GUI_HOST__ to this repository's site/gui-integration/index.ts. From there it connects to the integration object in site/plus-integration.ts and to the versioned @kubohiroya/turbowarp-* npm packages. When the GUI is built on its own, __TW_GUI_HOST__ doesn't exist, the getter returns null, and the GUI behaves like upstream.

The three approaches differ in when a feature starts working. Addons attach asynchronously after the page or GUI starts running, so they are a poor fit for work that must be in effect before a project loads. Plus can pass such work, like extension review, synchronously through a socket, so it is settled before loading.

Addons look for CSS module class names by prefix (scratchClass, [class*='menu-bar_file-group'] and so on). When upstream changes the page structure, the search fails and nothing happens. Plus's sockets are calls written into the fork's source, so a clash with an upstream change stops at the merge conflict, the type check or the integration tests.

Plot Plus's added features on two axes, "adds or replaces" and "the user may turn it off, or it must always be on". Only the top-left area can take the addon form.

For TurboWarp-Plus-Editor to add features to TurboWarp, the current approach of placing named sockets in the fork and binding implementations at build time suits it better than the addon approach. There are six reasons.

That said, small features in area A of Fig. 7 are written like addons: "attached later, removed with dispose". That makes them easy to move to the addon form if we ever want users to toggle them. We will not rebuild existing features to be addon-compatible.

Plus's added features span three repositories. Dependencies go one way; upstream knows nothing about downstream.

The fork's src/addons/hooks.js, a file upstream also has, contains this getter.

The distribution build's scripts/site/webpack.config.cts uses ProvidePlugin to bind __TW_GUI_HOST__ to site/gui-integration/index.ts. Nothing depends on assigning a global at run time or on startup order. The values the fork reads come in two layers.

The sockets the fork refers to, grouped by purpose. The left column is the name the fork writes after getHostIntegration()?.; the right column is the entry in the integration object. menu-bar.jsx and extension-library.jsx first store getHostIntegration() in a variable named host, so extract the current list by combining the two commands below in a checkout of the fork. hostIntegration is not a socket; it is the getter that hands the integration object to the host… helpers.

The table was extracted on 14 November 2026 from the pinned fork (f1e8f96).

Every socket follows these rules, and so must any new socket.

1. Optional. With no value, the fork behaves like upstream TurboWarp. Helpers return an empty default ([], {}, null).
2. GUI internals arrive as arguments. The host never imports the fork's reducers or UI. The fork passes Modal, the lazily loaded ScratchBlocks, the logger and Redux action creators at call time (for example createCancelSecurityLoad(initialState, defaultProjectId, LoadingState, integration)).
3. Anything attached can be detached. A socket that attaches something returns {dispose()}. Each time the VM changes, the fork calls dispose() on the previous return value before calling again, and never looks inside it.
4. One service per VM. A service read from two places, like the control bar, is kept single with a WeakMap keyed by the VM.
5. No CSS sockets. Upstream's CSS module class names are hashed at build time and can't be targeted from outside. New parts keep their own classes and styles in the package and use the GUI's public theme variables for color.
6. No custom files in the fork. Only socket call lines stay in the fork. Tests aren't added to the fork either; they go in this repository's test/ and in the packages.

attachToWorkspace is the socket that attaches features to Blockly and the VM in one go. It is the closest thing to an addon userscript.

One-time registration once ScratchBlocks is available (block shapes, context menus, palette additions) goes in registerBlockShapes(ScratchBlocks). When you need to wait for an addon to start, list its id in awaitStartupAddons (currently editor-searchable-dropdowns).

Unsandboxed extensions can read the following from Scratch.gui. In addition to upstream's getBlockly and getBlocklyEagerly, these fields appear only when the host supplies a value. Otherwise they stay undefined, so an extension can tell that "this build doesn't have it".

Buttons added with addButton start with visible: false. Call update({visible: true}) to show them. update can change four things: label, text, visible and expanded. To show an element when the button is expanded, hand it to the host with the service's placePanel(element). The registering side owns the element; the host only mounts it.

Whether a feature is on is decided once at startup by the page's twPlus… URL query. config/web-startup-feature-flags.ts reads the URL, and readStartupFeatureFlags in config/feature-flags.ts returns a frozen object. These values must never come from project data.

• Default enablement: site/addon-manifests.ts replaces the fork's generated/addon-manifests through a webpack alias. It enables addons tagged "recommended" plus hide-delete-button and block-palette-icons by default, and keeps hide-flyout off. Choices the user makes in the settings page take precedence.
• Startup wait: For addons listed in awaitStartupAddons, the runner waits for them to start before moving on.
• Context menus: createBlockContextMenu in api.js passes items through finalizeHostTransferMenu before finalizing them. This is where the script transfer menu is added.

First, decide which path the feature takes to reach the editor. Walk the chart below from the top; the first "yes" is where it goes.

Publish the implementation from the packages repository first; the Editor upgrades to that npm release and then wires it in. When a new socket is needed, work on the fork change in parallel and pin its SHA in the Editor.

Dialogs and panels shown by added features follow these conventions.

• Action buttons at the bottom: group them at the bottom right, with Cancel to the left of the primary action such as Save or Apply. Use the shared tw-plus-dialog-actions and set each button's data-dialog-action to cancel, close, confirm or delete. Keep the text labels and pair them with an X for Cancel and Close, a check for Save and confirmation, or a trash can for Delete.
• Close button next to the title: the close button at the top right of a panel or dialog shows no "Close" text, only an X icon. Name it with a translated title and aria-label.
• Strings: displayed strings have ja and en translations (plus ja-hira where hiragana display is needed).