new extension

[supervoidcoder]

[traycerai]

Warning

Ticket Assist will be discontinued on May 1, 2026. After that date, the feature will no longer be available. We suggest installing the Traycer IDE Extension for continued AI-powered, spec-driven development. Thank you for choosing Traycer!

Plan

Observations

This is the TurboWarp Extension Gallery (extensions.turbowarp.org). Currently extensions/extensions.json lists only "js", meaning only one extension (extensions/js.js) is featured. The build system (development/builder.js) reads all .js files from the extensions/ folder, validates metadata headers, and serves them. Validation enforces // Name:, // ID:, // Description: (with trailing punctuation), and // License: (valid SPDX) for any extension listed in extensions.json.

Approach

Since the ticket provides no description of what the extension should do, the plan covers the structural steps required to add any new extension to this gallery — following the exact conventions already established by extensions/js.js and documented in CONTRIBUTING.md.

---

Implementation Steps

1. Create a user folder and extension file

Create a new folder under extensions/ using your GitHub/Scratch username (e.g., extensions/YourUsername/), then create your extension JS file inside it (e.g., extensions/YourUsername/my-extension.js).

The slug (used in extensions.json, image paths, and docs paths) will be YourUsername/my-extension.

---

2. Add the required metadata header

At the very top of the JS file, before any code, add line comments in this exact format (parsed by development/parse-extension-metadata.js):

// Name: My Extension Name
// ID: uniqueExtensionId
// Description: A short description ending with punctuation.
// By: YourName <https://scratch.mit.edu/users/YourUsername/>
// License: MPL-2.0

Validation rules (enforced by ExtensionFile.validate() in development/builder.js):

• // ID: — must be present and match getInfo().id
• // Name: — must be present
• // Description: — must be present and end with ., !, or ?
• // License: — must be a valid SPDX expression (e.g., MPL-2.0)
• // By: links must point to https://scratch.mit.edu/users/

---

3. Implement the extension class

Below the header, wrap the extension in an IIFE following the pattern in extensions/js.js:

• Wrap everything in (function (Scratch) { "use strict"; ... })(Scratch);
• If the extension requires unsandboxed access, add the guard: if (!Scratch.extensions.unsandboxed) { throw new Error("..."); }
• Define a class with a getInfo() method returning { id, name, blocks, ... }
• Implement block handler methods on the class
• Register with Scratch.extensions.register(new YourExtension())

---

4. Register the extension in extensions/extensions.json

Add the slug (path without extensions/ prefix and without .js) to file:extensions/extensions.json:

[
  "js",
  "YourUsername/my-extension"
]

The order in this array determines the display order on the homepage.

---

5. (Optional) Add an extension image

Save an image at images/YourUsername/my-extension.svg (preferred), .png, or .jpg. Requirements:

• Exact 2:1 aspect ratio (validated by ImageFile.validate())
• PNG/JPG must be 600×300 pixels
• SVG must not contain <text> elements (convert text to paths)
• Add attribution to images/README.md for any non-original resources
• Image must be licensed under GPL-3.0

---

6. (Optional) Add documentation

If the extension needs explanation beyond what the blocks convey, create docs/YourUsername/my-extension.md. Then set docsURI in getInfo() to https://extensions.turbowarp.org/YourUsername/my-extension.

---

7. Verify locally

Run the following commands to confirm everything passes before submitting:

Command	Purpose
npm run validate	Checks metadata headers, image sizes, sample URLs
npm run lint	ESLint checks for JS errors
npm run format	Auto-fixes Prettier formatting (optional, maintainers will fix)

---

graph TD
    A[Create extensions/YourUsername/my-extension.js] --> B[Add metadata header comments]
    B --> C[Implement extension class with getInfo + block handlers]
    C --> D[Register in extensions/extensions.json]
    D --> E{Optional assets?}
    E -->|Yes| F[Add image to images/YourUsername/]
    E -->|Yes| G[Add docs to docs/YourUsername/]
    E -->|No| H[Run npm run validate + npm run lint]
    F --> H
    G --> H

Loading

Import In IDE

🤖 Prompt for AI Agents

## Observations

This is the **TurboWarp Extension Gallery** (`extensions.turbowarp.org`). Currently `extensions/extensions.json` lists only `"js"`, meaning only one extension (`extensions/js.js`) is featured. The build system (`development/builder.js`) reads all `.js` files from the `extensions/` folder, validates metadata headers, and serves them. Validation enforces `// Name:`, `// ID:`, `// Description:` (with trailing punctuation), and `// License:` (valid SPDX) for any extension listed in `extensions.json`.

## Approach

Since the ticket provides no description of what the extension should do, the plan covers the **structural steps** required to add any new extension to this gallery — following the exact conventions already established by `extensions/js.js` and documented in `CONTRIBUTING.md`.

---

## Implementation Steps

### 1. Create a user folder and extension file

Create a new folder under `extensions/` using your GitHub/Scratch username (e.g., `extensions/YourUsername/`), then create your extension JS file inside it (e.g., `extensions/YourUsername/my-extension.js`).

The **slug** (used in `extensions.json`, image paths, and docs paths) will be `YourUsername/my-extension`.

---

### 2. Add the required metadata header

At the very top of the JS file, before any code, add line comments in this exact format (parsed by `development/parse-extension-metadata.js`):

```
// Name: My Extension Name
// ID: uniqueExtensionId
// Description: A short description ending with punctuation.
// By: YourName <https://scratch.mit.edu/users/YourUsername/>
// License: MPL-2.0
```

**Validation rules** (enforced by `ExtensionFile.validate()` in `development/builder.js`):
- `// ID:` — must be present and match `getInfo().id`
- `// Name:` — must be present
- `// Description:` — must be present and end with `.`, `!`, or `?`
- `// License:` — must be a valid SPDX expression (e.g., `MPL-2.0`)
- `// By:` links must point to `https://scratch.mit.edu/users/`

---

### 3. Implement the extension class

Below the header, wrap the extension in an IIFE following the pattern in `extensions/js.js`:

- Wrap everything in `(function (Scratch) { "use strict"; ... })(Scratch);`
- If the extension requires unsandboxed access, add the guard: `if (!Scratch.extensions.unsandboxed) { throw new Error("..."); }`
- Define a class with a `getInfo()` method returning `{ id, name, blocks, ... }`
- Implement block handler methods on the class
- Register with `Scratch.extensions.register(new YourExtension())`

---

### 4. Register the extension in `extensions/extensions.json`

Add the slug (path without `extensions/` prefix and without `.js`) to `file:extensions/extensions.json`:

```json
[
  "js",
  "YourUsername/my-extension"
]
```

The order in this array determines the display order on the homepage.

---

### 5. (Optional) Add an extension image

Save an image at `images/YourUsername/my-extension.svg` (preferred), `.png`, or `.jpg`. Requirements:
- Exact **2:1 aspect ratio** (validated by `ImageFile.validate()`)
- PNG/JPG must be **600×300** pixels
- SVG must not contain `<text>` elements (convert text to paths)
- Add attribution to `images/README.md` for any non-original resources
- Image must be licensed under GPL-3.0

---

### 6. (Optional) Add documentation

If the extension needs explanation beyond what the blocks convey, create `docs/YourUsername/my-extension.md`. Then set `docsURI` in `getInfo()` to `https://extensions.turbowarp.org/YourUsername/my-extension`.

---

### 7. Verify locally

Run the following commands to confirm everything passes before submitting:

| Command | Purpose |
|---|---|
| `npm run validate` | Checks metadata headers, image sizes, sample URLs |
| `npm run lint` | ESLint checks for JS errors |
| `npm run format` | Auto-fixes Prettier formatting (optional, maintainers will fix) |

---

```mermaid
graph TD
    A[Create extensions/YourUsername/my-extension.js] --> B[Add metadata header comments]
    B --> C[Implement extension class with getInfo + block handlers]
    C --> D[Register in extensions/extensions.json]
    D --> E{Optional assets?}
    E -->|Yes| F[Add image to images/YourUsername/]
    E -->|Yes| G[Add docs to docs/YourUsername/]
    E -->|No| H[Run npm run validate + npm run lint]
    F --> H
    G --> H
```

---

Execution Information

Branch: master
Commit: 7b18e02

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.