RFC 0002: Plugins defines the plugin API and phases. Phase 1 splits the host into two app-agnostic crates:
crates/craft-pluginowns the generic WIT contract, manifest, permissions, entry input schemas and typed host errors. It has no wasmtime dependency.crates/craft-plugin-wasmruns WebAssembly components against that contract with fuel, memory and stack limits. Its linker exposes no network imports.
An app implements PluginHost: it supplies command schemas, each command's
read or edit effect, command execution, transaction begin/commit/rollback,
and the folders that file grants may resolve to. One successful plugin call is
one undo step; a failed guest call rolls back the transaction. Granted file writes
are staged and published only after the guest succeeds and the app commits. A rollback
deletes staged files without replacing their targets. A filesystem failure during publication
after app commit is reported and may leave some files changed. App commands remain
JSON data rather than app-specific WIT types. Both crates are Shared crates;
cargo xtask layers forbids direct and indirect SolidCraft dependencies.
SolidCraft's adapter lives in crates/engine and uses the same command surface
as MCP. Entries appear as plugin_id.function; plugin.list and
engine.describe expose their declared inputs. Selection and target inputs
are lists. Entries may declare named menu or ribbon slots; each app decides
which slots exist and draws forms from the input schemas. Plugins ship no UI
code. SolidCraft retains approval, cancellation and plugin preferences.
Declare design@0.1 alongside commands@0.2 to import the optional
craft:plugin/design-state@0.2.0 interface. Its read-only get-token() returns
JSON { "document_id": "…", "revision": "0123456789abcdef0123456789abcdef:42" },
or null without an open design.
Existing plugins need no new imports or capabilities.
The host keeps the identity and revision in the open document's session, outside the authored document, saved files and undo snapshots. Every committed edit, undo and redo gets a fresh token, including a redo that restores earlier content. Tokens never identify different history states. Saving does not change the token. Opening or importing a design creates a fresh identity and token, including when reopening the same file; switching between open tabs retains each tab's identity. Different open documents have different identities. Display-only changes do not invalidate calculations. These observations add no metadata to saved designs and do not alter the authored bytes restored by cancellation or undo.
Both fields are bounded opaque strings. Compare the complete token for equality
and pass it back unchanged. A token is valid only for its open document session;
discard cached tokens after closing or reopening a design. Revisions do not order
edits across sessions.
Use this token for edit preconditions; document.revision reports the separate
observation revision, which also follows visibility and uncaptured positions.
An editing call may pass expected_design beside entry and params to
plugin.run, or beside approval and params to <plugin>.<entry>:
{
"path": "/plugins/example",
"approval": "PACKAGE_HASH",
"entry": "apply",
"expected_design": {
"document_id": "DESIGN_ID",
"revision": "0123456789abcdef0123456789abcdef:42"
},
"params": {}
}The host checks the token inside the edit transaction before invoking the guest.
A mismatch refuses the entire edit with typed stale_revision data containing
both expected and actual tokens. No history step is added. Omitting the token
preserves unconditional calls.
MCP clients can supply this precondition through execute with the wrapped
command arguments. Direct plugin tools keep the plugin's declared input schema.
A command plugin can declare invalidation listeners under the same capability:
"listeners": [{"entry": "refresh", "on": ["design.changed"]}]Place this in runtime; refresh must name a declared command entry with
"effect": "read". Approval covers the exact declaration and component. Disabled,
unapproved or replaced packages receive no background calls.
The window sends whole-document invalidations after finished host edits,
undo/redo, and active-document switches, opens and closes. A burst is coalesced
into the latest state, at most about ten deliveries a second. The entry receives
{"design":{"document_id":"…","revision":"0123456789abcdef0123456789abcdef:42"}},
or {"design":null} without an active design. Closing the window's last tab
creates a blank design, so that notification names the new active design.
Events carry no file contents and are not an edit log.
A listener can also opt in to linked-file observations:
"listeners": [{"entry": "refresh", "on": ["design.changed", "design.links_changed"]}]on must be a nonempty list of distinct events from design.changed and
design.links_changed; either event can be declared alone. Both use the existing
design@0.1 capability and read-only command entries. No WIT world or interface
changes are needed. The separate event preserves the exact payload and delivery
conditions of existing design.changed listeners.
When a declared design.links_changed event is pending, the entry receives:
{
"design": {"document_id": "…", "revision": "0123456789abcdef0123456789abcdef:42"},
"links": [{"component": 7, "name": "Bracket", "path": "/parts/bracket.sc", "read": false}]
}design is the active design's token, or null without an active design.
Each link names the numeric component id, its name (null if absent) and absolute
source path. read: false means a component.links check found a file differing
from the version the design has read. read: true means the design already read that version, including after
Update Links (component.update_links) or Relink Source (component.relink)
successfully read the changed source into the design. A disk-only observation does
not advance the design token or trigger design.changed.
Unread (read: false) entries require a source inside the plugin's approved read folders; read: true entries remain visible without that grant.
The host observes files only when it already checks links, including the window's
focus check, and after Update Links; it adds no filesystem watcher. A burst retains
the latest observation per component, so this is an invalidation, not a history of
every disk change. A listener declaring both events gets one invocation for the
coalesced state, including links only when a linked-file observation is pending.
A design-only invalidation still has exactly the {"design":…} payload. A listener
declaring only design.links_changed receives no design-only invalidations, and a
listener declaring only design.changed never receives links or disk-only
notifications.
Handlers run on the command worker, away from the window thread, with their own budget: at most 1,000,000 fuel, 16 MiB memory, 512 KiB stack and 100 ms execution time, further limited by their requested budgets. They may refresh caches or panel data. Editing, file writes and starting jobs are refused with existing typed permission errors. A failure is shown in Preferences › Plugins and never fails the action that triggered the notification. Each invocation uses a fresh guest instance. Handler results use the existing 1 MiB JSON reply limit; retained panel data is limited to 16 MiB in total. Exceeding either limit reports a typed limit error.
Panel support from #19516 is not present here. The host keeps the handler's bounded JSON result through a plain function for a future panel adapter.
A plugin entry with "effect": "read" can call inspect.classify_points through
the commands.run WIT import, without a command-group grant. MCP callers use the existing execute
tool with the same command and parameters:
{"body":"Block","points":[[5,5,5],[10,23,20]],"face":"F2:bore"}body is the name used by model.faces, including a placed copy's name. points
contains 1–256 world-space points in millimetres (each coordinate finite and less
than 1e9 in magnitude). Omit face to find each boundary point's face automatically;
when supplied it is a face name from model.faces or a point on that face.
The example face name must be replaced with one from the inspected body.
The reply is {body, results}, with one result per point in input order:
{"class":"inside"}, {"class":"outside"}, or
{"class":"on","face":"…","normal":[nx,ny,nz]}. Classification uses exact trimmed
geometry at the body's modelling tolerance. Holes and cavities are outside material;
a hole wall's unit normal points into the hole and a boss wall's points away from
its axis. Face names use the persistent naming system shared with model.faces.
At an edge or vertex, face selects which incident face supplies the normal;
otherwise the first containing face in model.faces order is used. Every on
point must lie on the selected face when one is supplied. Mesh bodies, invalid
references and points where a normal is undefined return an error. This command
leaves the design and undo history unchanged.
Install plugin… in Preferences > Plugins (desktop only) picks a plugin .zip.
One confirmation screen shows its name, version, summary, requested permissions and entry placements.
Each command group explains its access in plain words: files, designs, application settings or other plugins.
Enter an absolute local path for each requested folder. Each folder shows its requested read/write access.
When the plugin asks for more memory than the ceiling in Preferences > Plugins (128 MiB unless
changed), the screen says how much it asks for and what the ceiling is.
Install approves the displayed command groups, folders and memory, publishes the package and stores the
approvals; Cancel changes nothing. Installation never runs plugin code. Approved memory applies to
that exact package only: a replaced or changed package asks again. Fuel still has to fit the ceiling.
Programs use the same plugin.install command without opening dialogs:
{
"path": "gears.zip",
"approval": "COPY_THE_APPROVAL_FROM_THE_REVIEWED_DRY_RUN",
"approve": {
"command_groups": ["file"],
"folders": [{"name": "exports", "path": "/home/user/exports", "read": false, "write": true}],
"memory_mib": 1024
}
}Approvals may only narrow the manifest's requests. An unrequested group, folder name or access mode
returns a typed refusal. memory_mib is either omitted (the plugin runs under the app's ceiling) or
exactly the manifest's runtime.limits.memory_mib.
Omitting approve grants no groups, folders or memory, including when replacing a plugin.
Providing approve replaces that plugin id's stored approvals; grants the new manifest no longer requests
cannot survive replacement. plugin.run checks stored grants against the current manifest on every call.
A package copied into the plugin directory by hand also starts with no grants.
Set "dry_run": true to check and describe the zip, including approval validation, without writing
files or grants. The response includes an approval hash of the exact manifest and component.
It also includes archive, a hash of the whole .zip, which covers the plugin's other files too.
Send both as approval and archive when installing the reviewed package. A changed package returns
a typed invalid_input error for approval or archive before any files or grants are written. The dialog always
sends both hashes; programmatic callers may omit it to install directly without a prior review.
Replacing an installed plugin with the same id requires "replace": true.
The response includes name, version, description, capabilities, permissions, requested limits, the app's
host_limits, app commands,
namespaced entries, declared entry_points with input schemas and slots, replacement information,
the target folder and whether it was installed. A dry run reports installed: false.
Dry-run description is the package review path; there is no separate review command or folder installer.
A zip holds one plugin, with plugin.json and its component at the top or inside one top-level folder.
The existing solidcraft_io::safe_zip reader refuses absolute paths, .., symlinks and device entries.
The installer limits the archive to 256 entries, each file to 16 MiB (an importer component may be up to 64 MiB), and input and unpacked content to
64 MiB. The manifest has a separate 16 KiB cap. Before publication, the host parses the manifest and
refuses unknown or newer capabilities. It unpacks into a hidden .install-… folder beside the installed
plugins, then renames it to plugins/<id>/. The entries resolve immediately, with no restart.
Each installed plugin card in Preferences > Plugins has an enable switch and Remove action.
Remove asks for confirmation, then deletes the package folder and its stored grants. Cancelling
Preferences does not restore a removed package. Removing a plugin preserves its data in saved designs.
Approved grants and removal survive closing or resetting Preferences. Grants are host preferences,
never design data; preferences retain at most 256 plugin ids, four command groups and 32 folders per id.
The desktop app keeps them in the plugins folder's grant store too, which the command line and headless
MCP share when they run with --keep-plugin-approvals (see Headless use). The browser Plugins page remains desktop-only.
The command surface exposes management without opening dialogs:
| Command | Parameters | Result |
|---|---|---|
plugin.check |
{path}: a package folder or .zip |
{ok, id, name, version, kind, approval, entries, problems: [{severity, field, problem, fix}]}; installs nothing |
plugin.install |
{path, approval?, archive?, replace?, dry_run?, approve?: {command_groups, folders: [{name, path, read, write}], memory_mib?, input_folder?}} |
Package description and installation status, including declared entry_points |
plugin.list |
{} |
{plugins: [{manifest, commands, disabled}]} |
plugin.remove |
{id} |
{id, removed: true} |
plugin.grants |
{} |
{grants: [{id, status, package_hash, command_groups, folders, memory_mib?, input_folder?}]} |
plugin.revoke |
{id} |
{id, revoked} |
plugin.tools |
{name?} |
{tools: [{name, kind, plugin, entry, plugin_name, plugin_version, description, effect, extensions, input_schema, approval?}]}: every installed, enabled plugin's entries as tools for agents (below); approval only for the one tool name asks for |
All commands expose input and output schemas through engine.describe. Removal validates the id
and confines deletion to the host's plugin directory. Installation and removal do not edit the design.
On desktop, send plugin.install and plugin.remove as separate engine.execute requests.
engine.batch and engine.script refuse these external file operations before any earlier step runs.
Direct requests use a worker to keep the window responsive.
solidcraft-cli (run, exec, eval and the other local commands) and solidcraft-cli mcp --headless
use the same installed plugins as the desktop app. By default the approvals given in a run last for
that run only. With --keep-plugin-approvals they use the same approvals as the desktop app: a
plugin installed and approved in one such run, or in the desktop app, is used by a later one without
installing it again:
solidcraft-cli exec plugin.install '{"path":"importer.zip","dry_run":true}' # review: permissions, limits, approval
solidcraft-cli --keep-plugin-approvals exec plugin.install '{"path":"importer.zip","approval":"…","archive":"…","approve":{"memory_mib":2048,"input_folder":true}}'
solidcraft-cli --keep-plugin-approvals run import.json # a later run: file.import uses those approvals-
Where they are kept. Installed plugins are in the per-user plugins folder (
pluginsin SolidCraft's data folder:%LOCALAPPDATA%\SolidCraft,~/Library/Application Support/SolidCraft, or on Linux$XDG_DATA_HOME/solidcraft, which is~/.local/share/solidcraftwhenXDG_DATA_HOMEis not set), and their approvals in its hidden.grantsfolder, one<plugin id>.jsonrecord per plugin.--plugins-dir DIRpoints a run at another folder: a CI job or a script can keep its own plugins, and with--keep-plugin-approvalsits own approvals, there, apart from the user's. Withmcp, both need--headless; a connected desktop app uses its own plugins. -
What a record allows. A record holds what was approved at install: command groups, folders, memory and
input_folder, bound to the exact manifest and component reviewed (package_hash). A changed package, even one whose files were edited in place, runs only after it is installed and approved again (plugin.installwithreplace: trueandapprove); until then its import or run is refused. Nothing is granted implicitly: an install withoutapprovestores a record that grants nothing, and a plugin with no record (copied in by hand, or revoked) runs with nothing granted. A record that does not read, or holds more than an installation could approve, is ignored. -
Listing and revoking.
plugin.grantslists every record with itsstatus:current,changed(install and approve again),not_installedorunreadable.plugin.revoke {id}deletes a plugin's record and keeps the plugin installed;plugin.remove {id}deletes both. Both are commands, so the same calls work fromsolidcraft-cli exec, arunscript, MCP and the desktop app's control channel:solidcraft-cli --keep-plugin-approvals exec plugin.grants solidcraft-cli --keep-plugin-approvals --plugins-dir ci/plugins exec plugin.revoke '{"id":"dutchman"}'
-
Several programs at once. A record is written whole and renamed into place, so a program reading the store sees the old record or the new one. A running desktop app or MCP server takes in what another program installed, approved or revoked before it next runs or imports with a plugin.
-
Earlier approvals. The first time the desktop app starts with a grant store, the approvals it kept in its preferences move there. Once the store exists it is the only record: a plugin revoked from the command line stays revoked in the desktop app.
The Plugins group on the Model tab lists every installed plugin entry, including entries without slots; its label opens the Plugins menu. Manage plugins in Preferences › Plugins (File › Plugins… opens it): install, turn on or off, and remove. Disabled entries remain listed but cannot be selected. Discovery examines at most 1,024 package folders and 8,192 host slot items. Only enabled plugins contribute host menu and ribbon items. The host draws each slot item with the plugin's name, a plugin badge and the entry name. Plugins declare placement in their manifests and supply no widget, menu or ribbon code.
| Declared slot | Placement (names ignore case) |
|---|---|
menu named File or Help |
The existing File or Help menu; each item includes the plugin's name |
Any other menu name |
No host menu item; the entry remains in the Plugins menu |
ribbon named for an existing Design ribbon tab |
A group named for the plugin in that tab |
Any other ribbon name |
One Plugins ribbon tab, with a group per plugin |
The Design tab names are Model, Surface, Assemble, Insert, Inspect, Manage, View, Sketch,
Sheet Metal and Weldments. Existing tab visibility and workspace rules still apply.
For example, {"kind":"menu","name":"File"} places an entry in File;
{"kind":"ribbon","name":"Model"} places it in Model.
Clicking a File, Help or ribbon item opens the same input-schema dialog as the Plugins menu.
The host finds the entry by its namespaced <plugin-id>.<entry> command. The dialog uses the same
enabled state and grant checks from every placement. Missing command-group grants leave Run off
with an explanation. Opening the dialog executes no plugin code; for a command entry, Run submits the
existing plugin.run transaction. An importer entry is not a command: its dialog shows the options,
then its button chooses the file and opens it as a new design with file.import, as File > Open does.
Preferences and the Plugins menu share plugin_install::start(app) in
crates/ui-egui/src/plugin_install.rs. It selects a zip, calls plugin.install with dry_run: true,
draws the confirmation screen and submits plugin.install with the reviewed approval and archive hashes and selected approve object.
Successful installation persists grants in desktop preferences and the shared grant store; successful
removal and plugin.revoke delete them. SolveApp::share_plugin_grants, called once after the
preferences load, starts sharing; solidcraft_engine::plugin::configure_process_plugins does the
same for every session of a headless process started with --keep-plugin-approvals.
There is one package reader and one installation confirmation screen.
plugin_menu::list in crates/ui-egui/src/plugin_menu.rs and Preferences use the same package
inventory as slot discovery. The list includes each plugin's enabled state and requested
command groups. File, Help and ribbon clicks resolve their namespaced entry against that list,
then call plugin_menu::open_entry(app, p, e), as the Plugins menu does. Unknown menu names need no
fallback rows because the Plugins menu already lists every entry.
The shared dialog draws the entry's input schema and supplies the package's content approval hash when invoking
plugin.run. An entry without fields receives {}. Slot clicks alone do not execute a plugin.
Installing, enabling or discovering a plugin never runs an entry. Installation grants do not replace
execution consent or the manifest-and-component identity checked by plugin.run.
A string with a fixed set of values becomes a dropdown. With enum the dropdown shows the values
themselves; to show words instead, list the options as oneOf, each {"const": value, "title": shown}
(with an optional description). The dropdown shows the titles and the plugin receives the value:
"up_axis": {"type": "string", "title": "Up axis", "default": "as_is", "oneOf": [
{"const": "as_is", "title": "As in the file"},
{"const": "stand_up", "title": "Stand up (Y-up to Z-up)"}
]}This host adds forms@0.1 alongside the existing commands@0.1 and commands@0.2
capabilities. Require a host advertising forms@0.1; older hosts reject that capability
before executing the plugin. Existing plugins link unchanged and can keep making explicit
entry calls without adding the capability. A plugin that needs populated forms declares
"capabilities": ["commands@0.2", "forms@0.1"] and imports
craft:plugin/forms@0.2.0.open(entry, params) -> result<_, plugin-error>.
params is JSON with the target entry's normal input schema, including the selection objects
returned by selection fields. The target must be a command entry of the same plugin.
At most eight forms may be requested in one run; parameters are limited to 1 MiB.
The host opens requested forms only after a successful interactive run, on the design tab that
ran the entry. If another tab is active when the reply arrives, the reply waits until the original
tab is active again. Preview discards form requests.
A failed or cancelled run discards every request.
The application opening path is plugin_menu::open_form(app, plugin_id, entry, params).
It draws the usual form filled with the supplied values and picks. Opening it only validates
inputs; the entry runs on Apply, or on a scratch design when Preview is explicitly enabled.
From the application control surface, use:
{"method":"ui.start","params":{"command":"plugin.edit","params":{
"plugin":"my_cam","entry":"pocket_edit","params":{"depth":5,"edges":[]}
}}}Plugins-menu entry forms use this same form implementation. The panel work in #19516 is not
on main yet: its future Edit row action can call the plain opening function or ui.start above.
An entry that already has an unsubmitted form is refused rather than replacing its values.
Scripts and MCP use explicit parameters to call <plugin>.<entry> or plugin.run.
engine.execute("plugin.edit", ...) returns typed interactive_required, with the instruction
to call the entry with params instead. Control replies expose plugin_error.kind: "interactive_required";
MCP exposes the same data in structuredContent.plugin_error, with entry and
action: "call_entry_with_params". The forms.open import returns that same typed host
refusal for programmatic invocations (represented by WIT unsupported); it never opens a window.
The capability grants no permission to edit another plugin's form or bypass execution approval.
Stored values are treated as user edits: conditional defaults do not replace them, and the conditions below apply immediately. Schema-allowed extra properties are preserved in Preview and Apply. Invalid values and missing geometry appear beside the corresponding fields and keep Apply off. Validation runs on a cancellable worker; the form shows “Checking inputs…” until the current inputs and model have been checked. Results for older inputs or models are discarded. A stored edge or face must still match its exact indexed geometry and point. Approximate hit coordinates have an allowance of 0.1% of the exact body bounds diagonal, at least 0.001 mm and the body modelling tolerance. Only the supplied face or edge index is tested using exact geometry; there is no nearest-entity fallback. Display settings do not change this allowance. These selection objects are the current selection contract, not a new persistent naming format.
Preview starts off for a populated form. Enabling it computes on a scratch design; Cancel discards it and leaves the design equal to its
previous state. Apply invokes the entry once through the ordinary plugin.run transaction.
The plugin replaces its own saved operation using its operation id in params; the host does
not invent or reorder operations. One Undo restores the previous state, and Redo reapplies it.
The form captures document.revision and document identity on opening. Apply carries these in
plugin.run.form_guard; checking and execution happen in the same command transaction. If the
revision changed, the entry does not run: the form revalidates against the current design,
reports missing picks beside their fields, and asks the person to review and Apply again.
If the design changes while a worker computes, atomic command acceptance rejects its result.
No stale result can overwrite the current design.
Command dialogs evaluate declarative conditions on sibling scalar properties. Changing a field runs no plugin Wasm. The same evaluator checks agent, CLI and script inputs before execution. For example, a cabinet command can show either shelves or drawers:
"input_schema": {
"type": "object",
"required": ["storage", "shelf_count", "drawer_count"],
"properties": {
"storage": {
"type": "string", "title": "Inside", "default": "shelves",
"oneOf": [
{"const": "shelves", "title": "Shelves"},
{"const": "drawers", "title": "Drawers"}
]
},
"shelf_count": {
"type": "integer", "title": "Shelves", "default": 3, "minimum": 1,
"x-solidcraft-visible-when": {"field": "storage", "eq": "shelves"}
},
"drawer_count": {
"type": "integer", "title": "Drawers", "default": 4, "minimum": 1,
"x-solidcraft-visible-when": {"field": "storage", "eq": "drawers"}
},
"has_back": {"type": "boolean", "title": "Back panel", "default": true},
"back_thickness": {
"type": "number", "title": "Back thickness", "default": 6.0,
"x-solidcraft-enabled-when": {"field": "has_back", "eq": true}
}
}
}A false x-solidcraft-visible-when hides the row and omits its key from Run and live preview,
including when a program supplies that hidden key. A hidden property is not required. A false
x-solidcraft-enabled-when leaves the row visible and greyed; its value is kept and sent.
Conditions have exactly one of these forms, with no expression parser:
{"field": "storage", "eq": "drawers"}compares a sibling's scalar value.{"field": "storage", "in": ["shelves", "drawers"]}matches any listed value.{"all": [condition, ...]}requires every condition; an empty list is true.{"any": [condition, ...]}requires at least one condition; an empty list is false.{"not": condition}reverses a condition.
A missing or hidden controller matches neither eq nor in. Controllers must be sibling
properties with scalar types (string, boolean, number, integer or null). Conditions
cannot name nested paths. Missing properties, non-scalar controllers, values outside a
controller's type, enum, oneOf or bounds, malformed conditions and dependency cycles are
rejected when loading the plugin. solidcraft-cli plugin check reports these errors without
running Wasm. An invalid schema leaves the dialog's Run button off with the existing CLI/agent
note. Conditions are bounded in depth and size.
Hidden-key removal also follows the applicable oneOf and anyOf object branches, including
nested objects and arrays. A composition containing conditional object rules must have one
branch, or object branches distinguished pairwise by a required, unconditional scalar property
with disjoint const or enum values. The parent or every branch must declare "type":"object"
for these discriminators. This makes the applicable branch unambiguous before hidden keys are
removed. Conditional object rules inside ambiguous compositions or allOf are rejected
at load time with an invalid_manifest error naming the composition's schema location. Scalar
choice options using x-solidcraft-when remain supported. The 1,024-property condition limit
applies only to object scopes declaring conditional rules; plain object scopes skip that limit.
All applicable scopes share the same visible controller values. When any scope hides a controller, conditions in every scope see it as missing. Required checks and choice filters use that same view. Loading checks visibility dependency cycles across each combination of enclosing scopes and selected branches, including nested objects and array items. Mutually exclusive branches are checked separately.
Put x-solidcraft-when on a oneOf option to offer it only when its condition is true. If the
current choice becomes unavailable, the dialog selects a matching conditional default, or the
first available option in schema order. With no available option, the choice is empty; a required
choice keeps Run off. A program supplying an unavailable choice gets an invalid_input error
naming that field.
Conditional defaults use the first matching rule in x-solidcraft-defaults. The dialog applies
it on opening and when a controlling value changes, until the user edits that field. Custom
values survive later controller changes, except that unavailable choices must still reset.
Programs provide their own values; conditional defaults do not overwrite program inputs.
Command inputs and importer options with these annotations opt into validation and hidden-key
removal before direct calls.
Direct calls to schemas without conditional annotations keep their existing pass-through behaviour.
For example:
"units": {"type": "string", "enum": ["mm", "in"], "default": "mm"},
"size": {
"type": "string", "default": "metric", "oneOf": [
{"const": "metric", "title": "M6", "x-solidcraft-when": {"field": "units", "eq": "mm"}},
{"const": "imperial", "title": "1/4 inch", "x-solidcraft-when": {"field": "units", "eq": "in"}}
]
},
"clearance": {
"type": "number", "default": 6.5,
"x-solidcraft-defaults": [
{"when": {"field": "units", "eq": "mm"}, "value": 6.5},
{"when": {"field": "units", "eq": "in"}, "value": 0.25}
]
}These numeric defaults are plugin arguments: the plugin decides how to interpret the selected units. Every conditional default must satisfy the property's base schema. Defaults and option filters also participate in cycle detection.
Use declarative rules above for visibility, availability and defaults expressible as sibling
conditions. For computed defaults or lookups, add "dialog@0.1" to capabilities and
"dialog_hook": true to the individual entry. Export the additive dialog-provider interface:
update-fields: func(entry: string, values: string) -> result<string, plugin-error>;Both strings containing values are JSON objects. Existing command worlds keep their exports;
plugins without this capability need no new export and continue to link and run. The interface
is available alongside both supported craft:plugin WIT versions (0.1 and 0.2); use the
command-dialog-plugin world when building a command plugin with the hook.
A reply maps existing property names to patches, for example:
{
"clearance": {"default": 6.5, "hint": "Computed from the selected size"},
"size": {"choices": ["metric"], "enabled": true},
"details": {"visible": false}
}Only visible, enabled, choices, default, value and hint are accepted. Choices must be
an ordered subset of that property's own oneOf constants, satisfying declarative option
conditions. The hook cannot add properties, change types, enable or reveal a declaratively
unavailable field, or bypass the input schema. A malformed reply is ignored whole with a
warning. Defaults and values must satisfy the field schema and the narrowed choices. Hints are
at most 1024 bytes of printable text; input and reply are at most 1 MiB each.
Declarative conditions run first, then the validated patch, then the same input check used by programmatic calls. The hook never edits: it runs as a read entry, with no edit command or file write grants, in a fresh sandbox. Its independent budgets are at most 10,000,000 fuel, 16 MiB memory and 250 ms, further capped by the entry's approved runtime limits and host ceilings. Compilation and execution happen on the command worker, outside the window thread.
The dialog debounces changes for 120 ms. It remains interactive while waiting and drops replies
from older generations. Run uses the current fields: valid inputs remain runnable while the hook
is pending, and an invalid or missing value keeps Run off. A user's edited field is
never overwritten by the hook's value or default. A timeout, trap or error leaves the
declarative fields in place with a quiet note.
Scripts, plugin.run and namespaced MCP plugin tools call the same hook once before executing
the entry. Tool schemas accept omitted keys for hook defaults; the original required fields are
checked after the hook. Defaults fill omitted keys; supplied values are preserved. A value outside narrowed
choices fails with invalid_input naming params.<field>. An exhausted time/fuel budget returns
a typed exhausted error, and the entry does not run. Programmatic calls never open a dialog.
A field can take geometry picked in the viewport, with the same pick control as Extrude's
Profiles and Chamfer's Edges. Mark an array property with x-solidcraft-selection; the property's
key is the argument the plugin receives. The design follows the
native selection proposal
(#16274).
"edges": {"type": "array", "title": "Edges", "description": "The rims to seat", "minItems": 1,
"x-solidcraft-selection": {"version": 1, "accept": ["edge"]}},
"body": {"type": "array", "title": "Body to modify", "maxItems": 1,
"x-solidcraft-selection": {"version": 1, "accept": ["body"]}}- What it takes.
acceptlists one or more ofprofile,edge,face,body,sketch_pointandsketch_curve. Sketch points and curves are picked with their sketch, because ids repeat from one sketch to the next. A profile field takes profiles from any number of sketches; the plugin decides what it accepts. The annotation has exactlyversion(1) andaccept. An unknown version or category, or any other keyword on the property (uniqueItems, a detaileditemsschema), leaves Run off with the note to run the entry from the agent or the CLI. - How many.
minItemsandmaxItemsare the counts Run checks. WithmaxItems: 1a pick replaces the last one; otherwise a click adds an item, and clicking it again takes it out.requiredwithminItemsof 1 or more needs a pick; required with no minimum sends[]; an optional field with nothing picked is left out. - What the plugin receives. Each item is the app's selection reference, as
select.settakes it:{"type": "edge", "body": "Body1", "index": 3, "point": [x, y, z]},{"type": "face", ...},{"type": "body", "name": "Body1"},{"type": "profile", "sketch": 2, "index": 0},{"type": "external_sketch_point", "sketch": 2, "id": "p3"}and{"type": "external_sketch_curve", "sketch": 2, "id": "c1"}, in pick order.items, if given, is only{"type": "object"}. - Reserved lists. Without the annotation,
bodiesandbody_idstake bodies and send their names (itemsmay be{"type": "string"}), andselection,targetandtargetstake edges, faces and bodies as references. Any other array still leaves Run off. - Picking. The first selection field takes the viewport's picks when the dialog opens, and starts with what is selected that it takes. The other fields start empty, so one selection never fills two fields. Clicking a field makes it the one that picks; its clear button, its list of picks and the hover highlight work as in the native tools. One tool picks at a time: while a native tool is open, clicking a plugin field says to finish or cancel it first (a sketch tool too). Escape and Cancel close the dialog and stop the picking.
- References stay true. In ordinary plugin forms, picks belong to the design they were made on.
Any change to the design while the dialog is open (an edit, an undo) clears them and the dialog says so; turning
the view or changing the selection does not. Picking runs no plugin code; Run sends the picks
through the same
plugin.runrequest. Programs callingplugin.runpass the same references themselves; nothing fills them from the selection. Populated forms for editing stored operations retain stale picks and validate them beside their fields, so they can be corrected.
To fit a custom fastener into an existing bore, accept face and edge picks in a selection
field. Call parts.seats with those references in picks before creating hardware. Each seat
supplies a world-space point and outward normal, and an origin that can be passed directly
as side A of joint.create. Place the screw with its head facing outward, then use a rigid
joint to attach its seating point to the bore. Declare both commands in the plugin manifest.
A plugin can ship vector images in its package and name them with x-solidcraft-icon, a
relative path to an .svg file inside the package:
"input_schema": {"type": "object", "x-solidcraft-icon": "icons/seat.svg", "properties": {
"series": {"type": "string", "title": "Type", "default": "standard", "oneOf": [
{"const": "standard", "title": "Standard", "x-solidcraft-icon": "icons/standard.svg"},
{"const": "short", "title": "Short", "x-solidcraft-icon": "icons/short.svg"}
]}}}- At the top of the schema it is the command's icon: its ribbon button, its rows in the Plugins, File and Help menus, and its dialog's header. Without one the command has the generic plugin icon.
- On a
oneOfoption it is that option's picture in the dropdown. Pictures show when every option of the choice names one that passed the check below; otherwise the dropdown shows the titles alone. - The image is drawn like the app's own icons, and must be one: SolidCraft's icon SVG subset
(the check the built-in icons pass, see
crates/look/icons/design/tools/lint_icons.py).viewBox="0 0 64 64"; absoluteM L C Q A Zpaths, circles, groups with a clip or opacity, masks and clip paths. Every colour is one of the icon palette's role colours (crates/look/icons/design/palette.toml, thesourcevalues) orcurrentColor, so the image follows the light and dark themes, the accent and the colour-vision setting as the app's icons do. Text, raster images,<use>, links, scripts, styles and any other element or colour are refused. - The path uses forward slashes and plain names (letters, digits,
.,_,-), ends in.svgand stays inside the package: no.., no absolute path, no link. A file is at most 64 KiB and a package names at most 64 images. Images are read from the installed package when the plugins are listed; nothing is fetched from the network. A refused or missing image is logged and left out, and the command works as before. - Images are not part of the
approvalhash: changing one changes only what is drawn.
An option may also name a material swatch with x-solidcraft-swatch. This is a separate
annotation for PNG or JPEG artwork whose own colours are preserved, including transparency;
the icon palette rules do not apply. For example:
{"const": "oak", "title": "Natural oak", "x-solidcraft-swatch": "swatches/oak.png"}Ship the image inside the plugin package. Paths follow the icon rules: plain relative paths,
no . or .., no absolute paths or links, and nothing fetched from the network. Use .png,
.jpg or .jpeg, at most 64 KiB and at most 256 × 256 decoded pixels. 128 × 128 pixels is
recommended. A package may name at most 256 distinct swatches. The host draws fixed-size
tiles and loads and decodes each distinct image once
when it loads the package, then caches its texture. A missing, corrupt, wrongly typed or oversized
swatch is omitted with a warning in plugin check and the install review; the plugin still works.
A partially illustrated choice shows tiles beside the option titles in its dropdown. When every
available option has a usable swatch, the dialog offers a grid with a search box; search matches a
case-insensitive substring of the title. Choosing either presentation still sends the option's
const value. MCP and scripts use exactly the same input values as before.
After Run commits the result, the app applies the run's last view command. view.fit
frames the result, keeping the view direction; view.home frames it from the home direction.
A run with no view command leaves the camera unchanged.
In an ordinary plugin form, a command entry that edits the design is previewed the way native tools are: while its fields make parameters, the host runs the entry on a scratch copy of the design and draws what it would change in the viewport (new material tinted, removed material as a see-through ghost). An ordinary plugin form has a Preview box, on when it opens; with it off, nothing runs until Run. A populated form for editing a stored operation starts with Preview off and retains stale picks for field validation. Nothing runs until Apply or an explicit Preview request.
- The preview is a dry run of the same
plugin.run: the plugin's code is unchanged and declares nothing new. It runs on a scratch session that is thrown away, so the design, the undo history and the selection never change. The run has none of the plugin's folder or command-group grants, so it reads and writes no file and reaches nothing past the design; a plugin that needs them shows "Preview:" with the refusal under its fields, and Run still runs it with its grants. - It runs again only when the parameters or the design change, under the plugin's own fuel, memory and deadline limits, off the window's thread. A run left behind by newer inputs is dropped.
- When the first successful preview is drawn, the app applies that run's last view command once
if it is
view.fitorview.home. Fit includes previewed sketch geometry when there are no bodies; even an empty result consumes this first-preview action. Later field changes leave the camera alone, so you can move it freely. A run with no view command leaves the camera unchanged. Reopening the dialog starts fresh: its first preview applies its view command again. - The most recently opened dialog on the design is previewed (the one picking in the viewport, when one is). While a native tool is open, its own preview is the one shown. Read entries and importers are not previewed.
The WIT package is craft:plugin@0.2.0. Its capability commands@0.2 runs app commands, logs,
reports progress and cancellation, reads named files and a clock, and exports the entry. A plugin's
plugin.json lists what it needs, for example "capabilities": ["commands@0.2"]; the host refuses
an unknown or newer capability when it reads the manifest, with a plain message such as "needs
commands 0.3; update SolidCraft or the plugin". formats@0.2 adds file-format slots: importers and
exporters; evaluate@0.2 lets an importer check its result, and storage@0.1 keeps data in a
design (below). ui and viewport arrive later as their own versioned interfaces. While a version
is 0.x, a minor version may break the one before it.
0.2 added one error, plugin-error.unsupported(string): the input is valid, but this plugin does
not handle it, such as a file with no solids or a newer version of its format. Use it instead of
invalid-input, which means the input is broken; SolidCraft then says "Sample does not support
bracket.smp: ..." instead of an "invalid" file. Plugins built against 0.1 (commands@0.1,
formats@0.1, evaluate@0.1) still run unchanged: the host reads the WIT version from the
component's own imports and exports, and serves the frozen 0.1 WIT
(crates/craft-plugin/wit-0.1/plugin.wit) to those. A component that names a version the host does
not run, or two versions at once, is refused before any of its code runs.
A plugin can call every command in the MCP catalog that its manifest lists. Commands that reach
past the open design are grouped (file, doc, app, plugin) and refused unless the
manifest asks for the group in permissions.command_groups and the user grants it.
File access requires approved folder grants. The reserved net permission is
refused with a typed error. Traps, missing permissions, failed commands, limits
and invalid manifest fields return structured errors (see Errors below). Phase 2 adds importers
and exporters (below) and the author tools (plugin check and plugin test, below); browser
execution follows.
Every installed, enabled plugin's entries are tools for the assistant chat and for MCP clients, beside the built-in tools, so an agent can find and use what a plugin offers without opening it (RFC 0002 section 6c).
-
Named tools. A command entry is the tool
<plugin>.<entry>, with its input schema as the tool's arguments. An importer entry is the tool<plugin>.<entry>titled "Open .ext files with Plugin name", takingpathand the importer'soptions; it opens the file as a new design throughfile.import. Export slots get their tools when exporters land. -
Fresh every listing.
tools/listasksplugin.toolseach time, so a plugin turned off or removed is gone from the next listing, and calling its tool is an unknown tool. -
Strict arguments. MCP tool arguments are checked against the entry's declared schema: declared types, required fields, fixed values and ranges. Object schemas accept only declared fields unless they allow others with
additionalPropertiesor use unsupported schema keywords. Composition options do not implicitly close objects. Nothing runs when the arguments don't fit. Existing<plugin>.<entry>engine calls keep passing inputs through to the plugin unchanged. -
Headless, under existing grants. A tool call opens none of the plugin's dialogs and runs with the grants it was given at install, as one undo step, like any command.
-
A
readentry stays read-only. Whoever runs it, a person or a tool call, the host refuses it edit commands and the file-writing host importwrite-file, whatever folders the plugin was granted. The refusal names the import (or command). -
A missing grant is an error, never a prompt. A call that needs a grant the plugin lacks (a folder, a command group, more memory than the ceiling, or approval of a changed package) fails with an error that names the plugin, the grant and how to approve it: in Preferences › Plugins by installing the plugin again and allowing it, or headlessly with
plugin.installand itsapproveobject. Over MCP the result also carries it as data,structuredContent.plugin_error:{plugin, grant, approve}, or{plugin, entry, refused_import}and{plugin, entry, refused_command}for a read entry. -
Marked as plugin tools. Each definition has a
pluginfield ({id, name, version, entry, kind, effect}), and its description starts "Plugin tool" and puts the plugin's own description between<plugin-text>and</plugin-text>, as text to read, not instructions to follow. -
The assistant asks first. In the assistant chat a plugin tool call goes through the same approval as every other tool call, and it always asks, whatever the permission mode or an earlier Always allow: running a plugin's code needs your go each time. An importer tool, and any
file.importordoc.openthat would run an importer plugin, asks the same way. -
Described like commands.
engine.describe(MCPdescribe_command) of<plugin>.<entry>returns the entry with the same schema astools/list(tool.input): a command entry as the<plugin>.<entry>command (approvalandparams), an importer as the tool that opens its files, withfile.importnamed.
Installed plugins are read with the app's own authority (a tool names a plugin, never a path), so
an agent confined to its folders (only the folder of its input file, say) still sees them in
plugin.list, plugin.tools and engine.describe, and doc.open and file.import still find an
installed importer. The input file itself must be in the agent's folders; when it isn't, the
refusal names it. The files a plugin reads or writes stay within its grants and the agent's folders.
Writing a plugin walks from an empty folder to a working command plugin and importer.
plugin.check(solidcraft-cli plugin check <folder|plugin.zip>) checks a package without running it, through the code Install and a call use: the installer's reader and limits, the manifest, the permissions (netis refused), the limits against the app's ceilings, and the component against its world (command-plugin,importer-pluginorexporter-plugin) and this app's WIT version, with no WASI or network import. Each problem has a severity, the field, what is wrong and how to fix it. In a folder,tests/and hidden files are left out. It runs no plugin code, installs nothing and never opens a dialog.solidcraft-cli plugin test <folder|plugin.zip> [--json] [--out DIR] [--require-cases]checks the package, installs it into a scratch plugins folder with the app's installer, and runs its test cases,tests/*.json, throughplugin.run,file.importandfile.exportwith the app's limits. An exporter writes into the scratch folder. A folder's cases are in itstests/folder; a.zip's are thetests/folder it holds, so a.zipmade without one has none. A case names the entry, its parameters or file, the grants (default: everything the manifest asks for, stored in the scratch folder's grant store as an install stores them, see Headless use), and what to expect: an error kind, values in the reply, valuesinspect.measuregives, files written. An entry with no case runs once with its defaults when it needs nothing else, and is reported as skipped otherwise. It exits with an error when a case fails, and with--require-casesalso when an entry is skipped, in a folder or a.zipalike: use it in CI so an untested entry fails the run. Atests/folder that cannot be read, a grant the manifest does not ask for, and a fixture folder (from) that is a link fail the case or the run; nothing is skipped silently.
An importer turns a file of another format into a SolidCraft design. Its manifest says
"capabilities": ["formats@0.2"], and each of its entries has "kind": "importer" and the
extensions it claims, lowercase without the dot. An importer's effect is open: it opens a file
as a new design and leaves the open one as it is. It need not say so; plugin.list and
plugin.install report it, and an importer that says "effect": "edit" is still read as open.
Only an importer may say open.
{"id": "sample", "name": "Sample", "version": "1.0.0", "capabilities": ["formats@0.2"],
"runtime": {"module": "sample.wasm", "commands": [],
"entries": [{"name": "convert", "kind": "importer", "extensions": ["smp"],
"input_schema": {"type": "object", "properties": {"units": {"type": "string", "enum": ["mm", "in"], "default": "mm"}}}}],
"limits": {"fuel": 100000000000, "memory_mib": 1024, "deadline_ms": 300000, "stack_kib": 16384},
"permissions": {"input_folder": true}}}- Opening.
doc.openopens a file SolidCraft does not read itself with the installed, enabled importer that claims its extension.file.importalways uses an importer, andformat(plugin_id.entry, listed inplugin.list'simporters) picks one for either command, for example for a.fcstdfile SolidCraft also reads.optionspasses the entry's declared options. Two importers claiming one extension needformat. An entry's optionallabelnames its group in the Open dialog (default: the plugin's name), as for an export slot. File › Open offers the claimed extensions, and the Plugins menu has each importer's entry: its dialog shows the options, then chooses the file. - The world. The component implements
importer-plugin: it exportsimporter.import-file(entry, file, options)and importssource(the file, read in chunks of at most 1 MiB),design(where it writes a SolidCraft design file),log,controlandclock. It has nocommandsimport: an importer makes a design, it does not edit the open one. - The result. The design opens as a new design that is not saved anywhere yet, named after
the file unless the design names itself. The call returns a loss report,
{"summary": "...", "items": [{"severity": "info|degraded|dropped", "title": "...", "subject": "...", "message": "...", "code": "..."}], "details": {...}}.titlenames the kind of loss in the user's words, the same for every item of that kind ("Parts of the file kept as they are");codeis the importer's stable code for it. Both may be empty. The Import report window shows the summary, then one line per title with how many items it covers, worst first, and folds every item with its code, subject and message under Details; programs get the whole report in the reply.detailsis the importer's own JSON (for example how far it checked the history it rebuilt, and each feature it mapped or could not). The window shows it under From the importer as folding lines: each field a line with its key read as words (final_bodyreads "Final body"), each object or list a group, a list's element named by itsname(ortitle,label,subject,stage,id,kindorcode) and itsstatus, and empty values left out. Copy report puts the whole report on the clipboard as text, and Save report… saves it as a.txtfile, or as a.jsonfile in the shape of the reply. After OK, Plugins › Last import report… shows the last import's report again. Nothing changes unless the whole import succeeds. - Assemblies.
source.read,source.sizeandsource.resolvewith path""reach the file being imported. Any other path is relative to that file's folder (an assembly's parts) and needs theinput_folderpermission. The install review shows it and Install approves it, stored with the plugin's other grants for that exact package; a plugin copied in by hand, or one whose grant is for another package, reads only the file itself. Hidden names, links and paths outside the folder are refused; an import reads at most 1 GiB and writes a design of at most 256 MiB. - Checking the result (capability
evaluate@0.2, besideformats@0.2). A converter that rebuilds a design's history can check it the way it would with the app's command line: it stages a design file it made withevaluate.stage(1 MiB per call, 256 MiB in all), andevaluate.runopens that design in a private session, apart from every open design and every file, and runs one ofdocument.inspect,inspect.measure,model.edges,model.facesortimeline.roll_toon it, returning the command's JSON reply (or{"error": "..."}when the command fails). Staging again starts a new design;evaluate.resetdiscards it, and nothing outlives the import. The session reads no files, not even fonts or linked designs, and runs no command that writes; its time counts against the import's deadline, and Cancel stops the import between commands. A design the app can't open, a command outside the list or a reply over 1 MiB is an error for that call only, so the importer can report its history as unchecked instead of failing. - Failures. A failure fails that one import, named with the plugin and the file ("Sample
could not open bracket.smp: ...", or "Sample does not support bracket.smp: ..." for
unsupported), and the next one gets a fresh instance. The compiled component stays in memory, so the next file opens without compiling again; nothing compiled is written to disk. - Limits. An importer's component may be up to 64 MiB, its deadline up to 10 minutes, and its
stack_kibup to 64 MiB (a command may ask for at most 1 MiB). Its fuel has to fit the user's ceiling in Preferences › Plugins, and its memory too unless the user approved more at install. Build it forwasm32-unknown-unknownand wrap it withwasm-tools component new: the host links no WASI, so a component that imports any is refused.
An exporter writes the open design as a file of another format. It is an export slot in the sense
of RFC 0015 §4: its manifest says "capabilities": ["formats@0.2"], and each of its entries has
"kind": "exporter", the extensions it writes, an optional label for the Export list, and its
options as input_schema, drawn as a form before the export. The commands it reads the design with
are listed in runtime.commands:
{"id": "sample-mesh", "name": "Sample Mesh", "version": "1.0.0", "capabilities": ["formats@0.2"],
"runtime": {"module": "sample.wasm", "commands": ["document.inspect", "model.mesh"],
"entries": [{"name": "write", "kind": "exporter", "extensions": ["smp"], "label": "Sample mesh",
"input_schema": {"type": "object", "properties": {"units": {"type": "string", "enum": ["mm", "in"], "default": "mm"}}}}],
"limits": {"fuel": 100000000000, "memory_mib": 512, "deadline_ms": 120000}}}- Exporting.
file.exportwrites a file whose extension SolidCraft does not write itself with the installed, enabled exporter that claims it;format(plugin_id.entry, listed inplugin.list'sexporters) picks one for any path, andoptionspasses the slot's options. Two exporters claiming one extension needformat. File › Export lists each slot as "Export (.ext)…", and the Plugins menu has it too: its dialog shows the options, then chooses where to save. Neither the command nor a script ever opens a dialog. - The world. The component implements
exporter-plugin: it exportsformats-provider.export-file(slot, options), which returns the file's bytes (at most 256 MiB), and importscommands,log,controlandclock.commands.runruns only the commands the manifest lists, only those that read the design (effect: read) and reach no file or other design; a manifest that lists another is refused when it is read. The commands run on a copy of the open design that is thrown away, so an export never changes the design or its undo history. - Files. The plugin reaches no file at all: it has no
filesimport and may ask for no folder, command group orinput_folder. The app writes the bytes it returns to the path the user chose (subject to the caller's file scope), in one step through a temporary file beside it, and only when the whole export succeeded. An export that fails, traps, runs out of fuel or is cancelled leaves the folder as it was. - Plugin data.
"needs_plugin_data": truemarks a slot that will also read the design's own data of its plugin (RFC 0015 §5). The flag is accepted, but exporters do not yet receive plugin data. The export runs without it and its reply carries a warning saying so. Thestorage@0.1capability is available to command plugins (below). - Limits. As an importer: a component of up to 64 MiB, a deadline of up to 10 minutes and a
stack_kibof up to 64 MiB, with fuel and memory within the user's ceilings. - One kind per plugin. A runtime's entries are all commands, all importers or all exporters, so a format that is both read and written ships as two plugins for now.
Every plugin failure starts with the plugin's name, and an importer's or exporter's with the file's name too.
Programs get the structured error (kind and its fields) from the engine as well as the text. The
text comes from the message catalog (plugin_error.*) in the window's language; the command line
and MCP give the English.
| What happened | What the user reads |
|---|---|
unsupported from the plugin |
Sample does not support sketch.smp: the model has no solids |
invalid-input from the plugin |
Sample could not open broken.smp: (its reason) |
| More memory than plugins may use | Sample could not open big.smp: it asks for 2048 MiB of memory, and plugins may use 128 MiB. Install the plugin again and allow its memory request, or raise Max plugin memory (MiB) in Preferences › Plugins (in solidcraft-cli, max_memory_mib in the --plugin-limits file). |
| More fuel than plugins may use | ... it asks for N fuel, and plugins may use M. Raise Max plugin fuel in Preferences › Plugins (in solidcraft-cli, max_fuel in the --plugin-limits file). |
| It ran out of fuel, memory, stack or time | ... it used all N fuel it asks for and was stopped. Ask its author to raise its fuel limit. (memory in MiB, stack in KiB, time in seconds) |
| Its design is over 256 MiB | ... the design it made is larger than 256 MiB, the most a plugin can hand over. |
| A trap | ... it stopped on an error inside the plugin (details). Report this to its author. |
plugin.inspect words limits_error the same way. The structured kinds are unsupported
(reason), over_ceiling (limit is fuel or memory_mib, with requested and allowed) and
exhausted (limit is fuel, memory_mib, stack_kib, deadline_ms or design_mib, with
allowed). The engine's own numbers for a stopped run (fuel used and left) go to the debug log.
A design container reserves plugins/<plugin-id>/ for a plugin's own files. They are kept and
saved back untouched when the plugin is missing, and opening a design never fails because a plugin
is missing.
A command plugin keeps its own data there with the storage@0.1 capability and a data format
number. Its manifest lists the storage.* commands it calls, like any other command, and it
reads and writes its files' bytes through the storage interface (plugin.wit), never as text:
{"id": "gears", "name": "Gears", "version": "1.4.0", "capabilities": ["commands@0.2", "storage@0.1"],
"runtime": {"module": "gears.wasm", "entries": ["make"], "data_format": 3,
"commands": ["solid.box", "storage.get", "storage.patch"]}}- What it keeps. One main JSON document (
data.json, at most 16 MiB) and files of its own (blobs/<name>; withcache: true,cache/<name>, files it can make again). Files are at most 256 MiB per plugin per design, and all plugin data in a design at most 256 MiB. SolidCraft writesmeta.jsonbeside them: the plugin's id, name and version and the data's format. - Reading.
storage.getreturns the main document, the data'sformat, the running plugin'splugin_format,read_onlyand the list of files with their sizes. A main document larger than the 1 MiB a command result may be is read in parts as its saved JSON bytes:storage.get-document(plugin?, offset, len), up to 1 MiB each; join them and parse. A file is read the same way,storage.get-blob(plugin?, name, offset, len), its bytes as they are; past its end the bytes are empty. Inside a plugin's run these reach only that plugin's own data. Agents and scripts read any plugin's data by naming it:storage.get {"plugin": "gears"}. - Writing.
storage.set {document},storage.patch {patch}(an RFC 7396 merge patch),storage.put-blob(name, data, cache, append)(the file's bytes, up to 1 MiB a call;appendwrites a large file in parts) andstorage.delete_blob {name}change only the running plugin's own data, and only from its run: the whole run is one undo step, and a failed run changes nothing. Called from anywhere else they are refused. Areadentry can't call them. - Formats. Every write saves the data in the plugin's
data_format. Whenstorage.getsaysformatis lower thanplugin_format, the data is from an older version of the plugin: the plugin reads it, converts it and writes it back, which saves it in the new format as one undo step. Whenformatis higher, the data is from a newer version: this version reads it, and every write is refused with "saved by a newer version of the plugin". - Without the plugin. The design opens as usual and the status line says so: "Contains Gears
data (plugin 1.4.0). Install it to edit." (or turn it on, or update it, when it's off or older
than the data). The data is saved back byte for byte. Nothing is downloaded, installed or run.
storage.listlists every plugin that keeps data in the open design, with itsstatus(ready,migrate,missing,disabledorolder) and size.