How eurekascratch/eureka works
Project type and purpose
• Eureka is a userscript project whose goal is to sideload and manage third-party extensions in Scratch-based editors. It also provides a built-in React-based dashboard for managing those extensions at runtime in the browser.
File structure
• Top-level config & CI files: .github/, jest.config.mjs, rollup.config.mjs, babel.config.cjs, tsconfig.json, pnpm-lock.yaml
• Source code: src/main/ – the core runtime; subfolders:
• dashboard/ – React app (app.tsx, CSS, assets) that renders the UI
• middleware/ – pipeline for loading extensions (extension-metadata, indexing)
• patches/ – code that applies hooks/patches into Scratch internals
• trap/ – trap modules to intercept and adapt VM/blocks APIs
• ctx.ts – shared runtime context object
• index.ts & meta.js – userscript bootstrap and metadata
• Types: src/types/ – TypeScript definitions for CSS, VM, global and SVG
• Tests: tests/ – automated tests via Jest
README for additional insights
• Eureka’s core functionality:
• Inject itself via UserScript Manager (Tampermonkey)
• Detect Scratch editors on the page
• Hook into the Scratch VM or Blocks API
• Provide an extended extension-loading API
• Expose a React dashboard for end users
• Supported platforms table shows how it integrates with different Scratch forks
a. Main components
1. Userscript injector (Tampermonkey/Violentmonkey)
2. Bootstrap / entry point (src/main/index.ts + meta.js)
3. Runtime context object (ctx.ts)
4. Middleware pipeline (middleware/)
5. Patcher engine (patches/)
6. Trap modules (trap/) – VM/Blocks adapters
7. Utility services (util/) – logging, settings, localization, injection helpers
8. Extension loader API (exposed for 3rd-party extensions)
9. Dashboard UI (React app under dashboard/) served as an overlay or panel
10. External Scratch editor environment (VM, Blocks workspace)
11. User settings storage (localStorage or internal store)
12. Tests suite (Jest) – peripheral
b. Relationships & data flow
• The Userscript injector adds the Eureka bundle into the page
• Bootstrap initializes ctx, then runs middleware in sequence:
→ extension-metadata middleware reads 3rd-party manifest
• Patcher engine applies code patches to the Scratch VM/Blocks
• Trap modules intercept API calls (e.g., block creation, VM execution)
• Utility modules provide services (i18n, settings, console capture)
• Dashboard UI connects to ctx to read settings, list loaded extensions, toggle them
• The Extension loader API allows 3rd-party scripts to call ctx.loadExtension(...)
• All interactions occur in the browser environment, no backend
c. Architectural patterns & design principles
• Modular pipeline (middleware)
• Plugin architecture: clear extension points
• Separation of concerns: injector / patcher / trap / dashboard / utils
• Single‐page overlay for UI (React)
• TypeScript for type safety, Rollup for bundling
d. Key technologies/frameworks
• TypeScript
• React & JSX (dashboard)
• Rollup & Babel (build pipeline)
• Jest (testing)
• PNPM (package management)
• UserScript metadata (Tampermonkey)
Final advice
• Be very detailed: represent each folder/major module as a component