# Web extension IDE

> How to use the CatSuite IDE in the browser to create extensions from scratch or from examples, validate, simulate, inspect and export .catplug packages.

- Language: en
- Canonical URL: https://netcattest.com/catsuite/en/docs/extensions/ide
- Section: Extensions
- Updated: 2026-10-06
- Other language (pt-BR): https://netcattest.com/catsuite/docs/extensoes/ide

The [extension IDE](https://netcattest.com/catsuite/en/ide) is a complete environment to write, test and package `.catplug` extensions right in the browser. Everything happens on your device: code is never sent to servers, the simulator makes no network connections and the project is saved only in this browser.

## Starting a project

Nothing is loaded automatically when the IDE opens. The start screen asks how you want to begin:

| Option | What happens |
|---|---|
| **Continue where I left off** | Reopens the project saved in this browser, showing its name, ID, version, file count and last save time. It only appears when a saved project exists. |
| **Start from scratch** | Creates a blank project with `manifest.json` and an empty `main.js`. You enter the name, the name in the other language, the ID and the author. |
| **Start from an example** | Opens one of the ready-made templates, all tested in the simulator with fictional data. |
| **Import .catplug** | Opens a package exported by the app or by the IDE itself. |

The IDE toolbar **New** button returns to this screen at any time, with an option to go back to the open project.

> [!WARNING]
> The IDE keeps one project per browser. Creating, opening an example or importing replaces the saved project, so the IDE always asks for confirmation first. Export the `.catplug` to keep a copy.

### Starting from scratch

The ID is generated from the name: accents are removed, spaces become hyphens and the `lab.` prefix is added. You can edit the ID freely as long as it follows the manifest pattern: 3 to 64 characters, starting with a letter, using only lowercase letters, numbers, dots and hyphens.

The initial manifest already passes validation:

```json
{
  "formatVersion": 1,
  "apiVersion": 1,
  "id": "lab.my-extension",
  "version": "1.0.0",
  "author": "QA team",
  "entry": "main.js",
  "name": {
    "pt-BR": "Minha extensão",
    "en": "My extension"
  },
  "description": {
    "pt-BR": "Descreva aqui o que a extensão faz.",
    "en": "Describe what the extension does."
  },
  "permissions": [],
  "targets": [],
  "externalHosts": [],
  "settings": {},
  "hashes": {}
}
```

### Available examples

| Example | Shows | Permissions |
|---|---|---|
| Basic template | command, native tab, field and storage | `commands`, `ui.tab`, `storage` |
| Request tagger | `onRequest` and `onResponse` hooks in the laboratory | `traffic.read`, `traffic.modify`, `ui.tab`, `storage`, `commands` |
| Cache auditor | sends, simulated external API, menu and a finding with evidence | `traffic.read`, `http.send`, `external.call`, `findings`, `storage`, `ui.menu`, `ui.tab`, `commands` |
| Workflow step | step with checkpoints and a JSON parser | `pipeline.step`, `parsers`, `traffic.read` |
| Components panel | every native interface component | `ui.tab`, `commands`, `storage` |

## IDE areas

| Area | Purpose |
|---|---|
| Files | package list, plus creating, renaming and deleting files |
| Permissions | checkboxes that update `permissions` in `manifest.json` |
| SDK reference | `cat` APIs with a filter and snippets ready to insert |
| Templates | replaces the current project with an example |
| Editor | syntax highlighting, line numbers and problem markers |
| Problems | validation errors, warnings and hints with a shortcut to the line |
| Console | `cat.log` entries, simulated sends and runtime failures |
| Laboratory | captures fictional requests to test proxy hooks |
| Preview | tabs registered by the extension, rendered like in the app |
| Inspector | hooks, commands, menus, steps, parsers and stored data |
| Findings | recorded findings with severity, confidence, status and evidence |

On small screens the areas are grouped into four tabs: **Files**, **Code**, **Preview** and **Console**.

## Editor and shortcuts

| Shortcut | Action |
|---|---|
| `Tab` and `Shift` + `Tab` | indent and outdent |
| `Enter` | new line keeping the indentation |
| `Ctrl` + `S` | save in the browser |
| `Ctrl` + `Enter` | validate and run in the simulator |
| `Esc` then `Tab` | leave the editor with the keyboard |

On macOS, use `Cmd` instead of `Ctrl`. The project is also saved automatically a moment after every change.

## Validation

Validation runs on every change and uses the same import rules as the app:

- required manifest fields, `pt-BR` and `en` texts, version and ID;
- `targets` and `externalHosts` destinations, including wildcards, ports and private addresses;
- declared permissions compared with the APIs used in the code;
- steps and parsers with `http` inputs require `traffic.read`;
- APIs that do not exist in QuickJS, such as `fetch`, `require` and `document`;
- `import` and `export`, which are not supported because the code runs as a script;
- syntax errors in the entry file, checked without running the code.

Errors block running and exporting. Warnings and hints do not.

## Simulator

**Run** loads the entry file into an isolated Web Worker that reproduces SDK API v1. The simulator uses the language selected in the site language selector: in Portuguese, `cat.i18n.text` and bilingual texts show `pt-BR`; in English, `en`.

The simulator applies the same rules as the app:

- every API requires its permission and answers `E_PERMISSION` when it is missing;
- sends and external APIs respect `targets` and `externalHosts`;
- change hooks must be synchronous and are stopped if they hang;
- storage is limited to 128 KiB per value and 10 MiB per extension;
- findings are consolidated by `fingerprint`.

[CatBridge](https://netcattest.com/catsuite/en/docs/catbridge) connectors are not available in the browser and answer `E_CONNECTOR`.

### Fictional data with fixtures.json

Sends, external APIs and the laboratory use the routes in `fixtures.json`. Missing routes answer with a simulated 404.

```json
{
  "scenario": "fictional",
  "routes": [
    {
      "url": "https://api.aurora.test/api/perfil",
      "status": 200,
      "cacheControl": "public, max-age=600",
      "body": { "id": "cliente-ficticio-001", "scenario": "fictional" }
    },
    {
      "url": "https://api.aurora.test/timeout",
      "error": "E_TIMEOUT"
    }
  ]
}
```

To use `cat.laboratory.capture`, enable `settings.laboratory` in the manifest.

## Exporting the package

**Export .catplug** validates the project and builds the package:

1. removes the previous signature, because the content was edited;
2. recomputes the SHA-256 of every file in `hashes`;
3. in format 2, creates a new `revisionId` and records `parentHash` when the project came from an import;
4. compresses everything into an `id-version.catplug` file.

Then import the file in the app under **Settings → Extensions**. The app signs the package again and shows the permissions before enabling the extension.

## IDE security

- The page blocks every network connection through its content security policy.
- Extension code runs isolated, with no access to the page, cookies or browser storage.
- `fetch`, `XMLHttpRequest`, `WebSocket`, `importScripts`, `WebAssembly` and the worker message channel are blocked for extension code.
- Imported packages go through the format limits: up to 10 MiB compressed, 40 MiB expanded, 4 MiB per file and 500 files, with no absolute paths, `..`, symbolic links or encrypted entries.
- Mismatched hashes produce a console warning and are recomputed on export.
- Password-protected packages (`CATSEAL2`) do not open in the web IDE: open them in the app or inspect them in [CatSuite Studio](https://netcattest.com/catsuite/en/docs/extensions/vscode).

> [!TIP]
> Start from the basic template, run it in the simulator and only then add permissions. Validation points out every declared permission the code does not use.

## Prefer VS Code?

The same experience exists as an installable extension: **CatSuite Studio** brings SDK suggestions, validation, a local preview with fixtures and signed `.catplug` package builds inside Visual Studio Code. Projects started in the web IDE can carry on in the editor.

- [Install CatSuite Studio from the Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=NetCatTest.catsuite-studio)
- [Source code in the catsuite-vscode folder on GitHub](https://github.com/netcattest/catsuite/tree/main/catsuite-vscode)
- [Full CatSuite Studio guide](https://netcattest.com/catsuite/en/docs/extensions/vscode)

## Next steps

- [CatSuite Studio for VS Code](https://netcattest.com/catsuite/en/docs/extensions/vscode)
- [Manifest and .catplug package](https://netcattest.com/catsuite/en/docs/extensions/manifest)
- [JavaScript API reference](https://netcattest.com/catsuite/en/docs/extensions/api)
- [Interface, data and findings](https://netcattest.com/catsuite/en/docs/extensions/ui-and-data)