Web extension IDE

The extension 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:

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

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:

{
  "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 #

IDE areas #

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

Editor and shortcuts #

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 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.

{
  "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.

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
• Source code in the catsuite-vscode folder on GitHub
• Full CatSuite Studio guide

Next steps #

• CatSuite Studio for VS Code
• Manifest and .catplug package
• JavaScript API reference
• Interface, data and findings