scratch-gui is the MistWarp editor and community site: one Vite build with React 16 and Redux, pnpm, and Jest. It is a fork of TurboWarp's GUI. The engine forks (scratch-vm, scratch-render, scratch-audio, scratch-paint, scratch-blocks) are pinned commits in package.json.
| Path | Holds |
|---|---|
src/modules/<name>/ |
New shared code, in strict TypeScript. index.ts is the module's only public entry. The current modules are listed in docs/conventions.md. |
src/lib/ |
Older shared JavaScript. Don't add to it; write a module instead, and move code out when you touch it substantially. |
src/components/, src/containers/ |
Editor UI. Components are presentational, containers connect to Redux or the VM. New components are function components with hooks. |
src/community/ |
The community site: React Router, hooks, its own i18n and design tokens. |
src/reducers/, src/playground/ |
Editor state, and the page entry points. |
src/addons/ |
The addon runtime. src/addons/addons is vendored from Scratch Addons. |
Never edit src/generated/, src/addons/addons/ or src/addons/generated/ by hand. src/packager/ is the imported TurboWarp Packager and is where packaging changes go: edit it directly, and scripts/vite-packager.mjs rebuilds its player scripts. It keeps its upstream style and ESLint skips it, so lint does not check changes there.
pnpm check runs all of these, and CI runs the same steps (.github/workflows/node.js.yml). Turn on the pre-commit hook with pnpm run hooks:install.
- Lint and types:
pnpm run lint,pnpm run typecheck. TypeScript is strict, includingnoUncheckedIndexedAccess, and uses the typescript-eslint strict and stylistic rules. - Module boundaries: modules may not import components, containers, community, playground, reducers or addons. Every module is imported through its index.
- No code comments and no em dashes in anything you add:
pnpm run check:conventions. Only tool directives (eslint-disable,@ts-expect-error) are allowed. Name things so the code explains itself. - Web storage: use
localandsessionfromsrc/modules/storage. Files still on rawlocalStorageare listed inscripts/eslint-legacy-storage-files.cjs. Remove a file from that list when you migrate it, and never add one. - Strings: editor text goes through react-intl, community text through
text()fromuseCommunityIntl(). Runpnpm run i18n:editor:extractorpnpm run i18n:community:extractand commit the result. - Community CSS:
pnpm run check:community-css.
- Editor
defaultMessagemust be a single string literal, or extraction silently skips it. Community strings must be whole sentences. - Every
.cssimport is a CSS module. A bareimport './x.css'whose classes are never used is dropped from production builds, so check visual changes inpnpm run build:deploy, not onlypnpm start. - UI: never put a left border or accent stripe on anything with rounded corners. Use flat fills, not gradients. Use sentence-case headings, one heading per section, and no eyebrow labels.
- Community UI uses only the tokens in
src/community/styles/tokens.module.css, separates surfaces with fills rather than outlines, usescomponents/UnderlineTabs.jsxfor tabs, and builds from the primitives incomponents/ui/. - A refactor keeps behaviour, so existing tests pass unchanged. New code comes with tests: module tests go in
test/unit/modules/<name>.test.tsand import from@jest/globals.
- The default branch is
develop. This repo is a fork, so open PRs withgh pr create -R MistWarp/scratch-gui --base develop. - PRs with a visible change include screenshots, plus a recording for motion or interaction, checked in Chromium and Firefox.
- To test unmerged engine changes, run
pnpm run linkwith the forks checked out next to this repo.pnpm run deps:syncmoves the pins. - A fresh worktree needs
src/generated/copied from a checkout that has run Vite once. - Never add
Co-Authored-Byor any AI or tool attribution to commits or PRs. - READMEs are overviews. Documentation goes in MistWarp/docs (https://mistwarp.org/docs/), and repo conventions in
docs/conventions.md.