scratch4js

A pnpm monorepo of small, focused JavaScript packages for working with Scratch and TurboWarp — edit .sb3 projects programmatically, talk to the Scratch website, drive it all from an AI agent, and build & bundle TurboWarp extensions.

📖 Documentation:https://playforge-coding.github.io/scratch4js/

Packages

Path	Package	What it is
packages/scratch4js	scratch4js	The core library: read/edit .sb3 files with a small, declarative API.
packages/s-api4js	s-api4js	A class-based wrapper for the Scratch website API: read public data, and log in to download/edit/publish .sb3.
packages/scratch-mcp	scratch-mcp	An MCP server exposing the library's editing surface as tools, plus a TurboWarp live-reload bridge.
packages/tw-plugin-webpack	tw-plugin-webpack	webpack/Rspack plugin that bundles a multi-file TurboWarp extension into one IIFE-wrapped file.
packages/tw-plugin-rollup	tw-plugin-rollup	Rollup/Rolldown/Vite plugin that bundles a multi-file TurboWarp extension into one IIFE-wrapped file.
packages/create-tw-extension	create-tw-extension	Scaffolder (npm create tw-extension) for a new TurboWarp extension project with your choice of bundler.
packages/web-editor	browser-ide-kit	Reusable React building blocks for in-browser IDEs: split-pane layout, Monaco, an xterm/WebContainer terminal, file tree.
packages/tw-extension-maker	tw-extension-maker	In-browser IDE (built on browser-ide-kit) that bundles a TurboWarp extension in a WebContainer and previews it live.
packages/userscript	userscript	TurboWarp Desktop userscript (ES modules → one IIFE): scratch-mcp live-reload + real-time collaboration over a WebSocket relay.

How they fit together

 AI agent / MCP client
│ (MCP tools over stdio)
▼
┌──────────────┐ edits in memory ┌────────────┐
│ scratch-mcp │ ──────────────────► │ scratch4js │
└──────┬───────┘ save → .sb3 file └────────────┘
│ WebSocket bridge (localhost:9060)
▼ "loadSB3" → fetch /get.sb3
TurboWarp Desktop + userscript ──► live preview

An agent edits a project through scratch-mcp; on save the server writes the .sb3 and signals the userscript, which reloads it into TurboWarp Desktop instantly.

Getting started

pnpm install
pnpm build # build every package (-r build)
pnpm lint
pnpm fmt # prettier --write .

Then:

1. Install the userscript into TurboWarp Desktop (pnpm --filter userscript deploy; per-OS paths in its README).
2. Run the MCP server and point your MCP client at it.
3. Open .sb3 files, edit, and save_project to see changes live.

Workspace layout

.
├── packages/
│ ├── scratch4js/ # the core library (+ examples + example.sb3)
│ ├── s-api4js/ # Scratch website API wrapper
│ ├── scratch-mcp/ # the MCP server + live-reload bridge
│ ├── tw-plugin-webpack/ # webpack/Rspack extension bundler plugin
│ ├── tw-plugin-rollup/ # Rollup/Rolldown/Vite extension bundler plugin
│ ├── create-tw-extension/ # extension scaffolder CLI
│ ├── web-editor/ # in-browser IDE building blocks
│ ├── tw-extension-maker/ # in-browser extension IDE
│ └── userscript/ # TurboWarp Desktop userscript: live-reload + collaboration
├── docs/ # Rspress documentation site
├── pnpm-workspace.yaml
└── package.json # workspace root (build/lint/fmt delegate to -r)