Repository navigation
Extensions
github-actions[bot] edited this page Nov 7, 2026
·
1 revision
formcut loads extensions under the Form Extension Contract, API 1, the same contract every Form app follows. FormPortal installs them, form.ext makes them and formai.studio lists them; none is bundled with formcut. The API an extension programs against (the document snapshot, the commands, the events) is in docs/EXTENSIONS.md.
- Extensions menu in the titlebar: each contributed command, then Extensions Panel, Reload Extensions and Manage in FormPortal.
- Extensions tab in the left pane: one row per extension with its version, source (Catalogue, File, Development), permission chips and state (Ready, Needs Permission, Refused with the reason), Open for its panels, Run for its commands, and the folder of a development extension. With nothing installed it points to FormPortal.
- An extension's dock panels open in the same tab, under the list; its dialogs open as formcut dialogs.
- The first time a version runs, formcut asks for the permissions it lists. Allow is remembered for that id, version and permission set; Not Now is asked again next time.
Effect packages (looks, filter chains, shaders) are a separate, older mechanism: data only, imported from the Effects tab.
-
Engine.
backend/app/formext_host.pyis the contract kit's resolver, vendored unchanged: it finds FormPortal's folder, readsextensions/formcut/enabled.json(FormPortal) anddev.json(form.ext), checks each manifest and serves files safely.backend/app/extensions.pymountsGET /api/extensions(the list and itsstamp),GET /api/extensions/stamp,GET /api/extensions/files/{id}/{version}/{path}(contract headers, 404 for anything outside the folder, a symlink or a type outside the list), and the system file dialogs,httpsfetch and window bridge an extension or agent can ask for.security.pylets GET and HEAD on the files route through from this computer with any Origin (a sandboxed frame sendsOrigin: null), since it serves only a package's own files; every other route keeps its guard. -
Window.
frontend/src/extensions/host-bridge.tsis the kit's host, vendored unchanged: the sandboxed frame (allow-scriptsonly), message routing, permission checks, timeouts.frontend/src/extensions/catalogue.tsis the document snapshot and the command catalogue over the state engine;document.applyruns insideProjectEngine.transaction, so one call is one undo step and a failing op puts the document back.frontend/src/ui/extensions.tsbuilds the menu, the tab, docks, dialogs and consent, polls the stamp every 2 s while the window has focus, and patches only the rows that changed. -
Agents.
extensions.listandextensions.commandonPOST /api/rpc, and the MCP toolsformcut_extensions_listandformcut_extension_command(the contract's<prefix>_names, since every formcut tool carries the prefix), reach the window through the engine: the window long-pollsGET /api/extensions/agent/nextand answers each request, so consent is asked in the window and an agent can never skip it. With no window open (none has polled in 35 s),extensions.listanswers from the engine alone andextensions.commandfails at once with "the formcut window is not open". -
HTTP RPC only.
extensions.commandworks only through the running engine's HTTP server:POST /api/rpc(which the MCP server uses) or the/api/rpc/wswebsocket, both of which run it off the event loop.python -m app.cli(stdin,--tcp,--unix,--grpc) runs the RPC in its own process with no window behind it, so there it always answers "the formcut window is not open". -
No palette, no step names. formcut has no command palette, so contributed commands appear as Extensions menu items and as Run chips on each row. Its undo history has no step names, so
document.applyacceptslabeland does not show it; the call is still one undo step.
- Copy the contract's
examples/hellosomewhere, set itsproducttoformcut. - Write
extensions/formcut/dev.jsonunder FormPortal's folder (FORMPORTAL_ROOToverrides it) with that folder aspath. - Within 2 s formcut lists it as a Development extension. Open its panel, allow it, and it reads the project.
Pages
- Home
- Architecture
- Creator workflow
- Automation
- Extensions
- Packaging
- Translation
- Mobile notes
- Models
- Licences
In the repository
These pages are published from .docs/wiki/ in the repository. Edit them there;
a push to main updates this wiki. Editing a page here is overwritten by the
next publish.