Appearance
Packaging And Installation
Mantis accepts extension packages as:
.mantisx.zip.json
For real extensions, prefer .mantisx or .zip. A JSON package is useful for small examples and debugging.
Zip package layout
The package must contain mantis.extension.json either at the root:
text
my-extension.zip
mantis.extension.json
dist/extension.js
dist/panel.js
dist/styles.css
backend/main.pyOr inside one single top-level folder:
text
my-extension.zip
my-extension/
mantis.extension.json
dist/extension.js
dist/panel.js
dist/styles.css
backend/main.pyPackages with multiple unrelated top-level folders are rejected.
JSON package layout
A JSON package contains the manifest, browser assets, and backend files inline:
json
{
"manifest": {
"manifestVersion": 1,
"id": "demo.inline-extension",
"name": "Inline Extension",
"version": "0.1.0",
"main": "dist/extension.js",
"activationEvents": ["onPanel:main"],
"contributes": {
"panels": [
{
"id": "main",
"title": "Inline Panel",
"entry": "dist/panel.js"
}
]
}
},
"assets": {
"dist/extension.js": "exports.activate = function () {};",
"dist/panel.js": "document.getElementById('root').textContent = 'Hello';"
},
"backend": {}
}This is convenient for fixtures, but larger extensions should use zip-based packages.
File groups
Mantis splits files into two groups:
| Group | Source | Exposed to panel? |
|---|---|---|
assets | Any file not under backend/ | Yes |
backend | Files under backend/ | No |
Extension host main, panel entry, scripts, and styles must refer to files in assets.
Backend entry must refer to a file in backend.
Validation rules
The backend validates packages before installation and again during installation.
Validation checks include:
- package size
- UTF-8 text files
- manifest shape
- supported permissions
- supported contribution points
- safe relative paths
- extension host main existence
- panel asset existence
- backend entry existence
- user/project access
Absolute paths and paths containing .. are rejected.
Install flow
When a user imports an extension:
- Mantis validates the package.
- Mantis shows a trust dialog with the extension name, version, panels, permissions, backend status, and network request.
- If the user confirms, Mantis installs the package for that user and project.
Packages are validated before installation. If any referenced asset, backend file, permission, or manifest field is invalid, installation fails.
Where extensions appear
Installed extension panels appear in:
text
Verticals > ExtensionsExtensions can be disabled, enabled, or removed from the installed extensions list in the same menu.
Enable, disable, and uninstall
Disabling an extension hides its contributed panels, closes open extension tabs, and stops its extension host. Uninstalling removes the installed package for the current user and project.
Backend dependency caches may remain until the server cleans them or the package/version changes.
Sharing an extension with a map
An extension belongs to one account until it is shared with the map. Sharing attaches the package to the map itself, so every reader of that map is offered it without the package being installed for them first.
Two routes attach a package to a map, and both leave the reader in control:
| Route | Where | What the reader does |
|---|---|---|
| Published | Verticals > Extensions, Publish beside an installed extension | Chooses Install on the Published On This Map entry |
| In the files | A .mantisx or .zip package in the map's file tree | Hovers the row and chooses the install action |
An account that may edit the map sees Publish beside each installed extension; an account that may not sees the offers without that action. The publication then appears under Published On This Map for every reader of the map, described by the version, permissions, panels and backend the publication states.
Publishing requires the coordinate to be installed for the publishing account: the published package is a copy of a package that account runs, made at the moment of publishing.
What a publication records
A publication stores the package under the map and records, beside it:
- the account that published it, which is not the same field as the manifest's own
publisherstring. The manifest field is a name an author writes for readers, and it is the one an offer and the consent step state; the recorded account is the one Mantis observed publishing. The publication keeps it beside the package, and a reader's own install of the package keeps it as provenance, but neither reader-facing step displays it yet (see the limits on Security and current limits). - the time it was published.
- the digest of the package stored at that coordinate.
The digest is the identity an agreement is bound to. The map may publish the same id and version again, which replaces the package sitting at the coordinate.
What stays the reader's own
Installing a package a map offers creates the reader's own install of it. The install, its enabled state, and the decision to install are the reader's records on the reader's account: the map cannot enable, disable or remove an extension on a reader's behalf, and one reader's choices are unaffected by what other readers of the same map do.
Withdrawing is the map's act rather than the reader's. It takes back the offer, and it also stops the extension for a reader who accepted it: an install of a published package is a record naming the map's package rather than a copy of it, so the code goes when the map's copy goes, and it returns if the map publishes that same package at the coordinate again. What stays with the reader is the decision itself - that the coordinate was installed, whether it is enabled, and the version the decision was about - because the record names the package rather than the place it sat.
When the listing and the package disagree
A published extension is never installed on its own. Choosing Install opens the consent step used for a package installed from a file, and the package is fetched from the map only once that step is confirmed, so no package code reaches a reader before agreement. The confirmation carries the digest the listing named, and the server refuses when the package at the coordinate is no longer that package.
The refusal is not a fault in the install: it means the map published a different package at the same coordinate after the listing the reader read. The map's current offer is the thing to read, and installing again from that listing decides about the package that is actually there.
Installing, enabling, disabling and removing then behave exactly as they do for a local package: the panels, the SDK capabilities the permissions allow, and the backend actions work the same way for the reader as for the publisher. A published package is validated exactly as a package installed from a file is, against the same manifest shape, permission list, path rules, size caps and text-only encoding described above.
The map holds one package per id and version, so publishing a coordinate again replaces what the map offers at that coordinate. Increment the version to offer an update.
The trust consequences of an offer - what a reader is agreeing to, and what the map cannot do once a reader has agreed - are in Security and current limits.
Size and encoding limits
| Limit | Value |
|---|---|
| Package size | 25 MB |
| Any single file | 5 MB |
Packages are UTF-8 text only
Every file in a package is decoded as UTF-8 during import. Anything that is not valid UTF-8 text fails with "Extension file must be UTF-8 text", which means you cannot ship images, fonts, wasm, or any other binary asset. Inline small assets as data URIs in your JavaScript or CSS, or fetch them at runtime from a URL.
Beyond the hard caps, keep packages small:
- bundle only what the panel needs
- avoid large datasets inside the extension package
- fetch project data through the SDK instead of shipping static copies
- keep Python dependencies minimal
Versioning
The server stores extensions by id and version, so multiple versions coexist on disk. Use normal version increments when publishing updates:
json
{
"id": "demo.sample-panel",
"version": "0.1.1"
}Version strings may contain only letters, numbers, ., _ and -, because the value becomes a directory name. A semver build suffix such as 1.0.0+build.3 is rejected.
Only the newest version runs
However many versions of an id are installed, the workspace loads exactly one: the highest version. Older builds stay on the server but are never activated, so installing an older package to test a regression will not have the effect you expect unless you remove the newer one first.
Changing the id creates a separate extension from Mantis's perspective.
Recommended build output
If you use a bundler, produce plain browser JavaScript and CSS:
text
dist/
extension.js
panel.js
styles.cssDo not rely on imports from the parent Mantis app. Bundle host dependencies into extension.js and panel dependencies into your panel output.