Plugin API Reference

Plugin API Reference

This reference describes the public plugin SDK, contribution schemas, capability gates, and install checks provided with ChemDraft 1.0.0.

Contract and versioning

Runtime plugin source imports @chemdraft/plugin-api, ordinary npm dependencies, and its own relative modules. It must not import another @chemdraft/* package or reach into private app code. Document types referenced by the SDK, including ChemDraftDocument, DocumentObject, and DocumentPatch, are re-exported from this public boundary.

PluginApiVersion is 0.1.7. A plugin declares the caret requirement for the earliest API it needs. For this 0.x contract, the minor is the compatibility boundary: additive methods bump the patch; breaking changes bump the minor. A host must be at least the declared patch within that compatible minor.

API addition	Minimum caret requirement
Base plugin contract	^0.1.0
chemistry.nameToStructure	^0.1.1
chemistry.structureFromSmiles	^0.1.2
dialogs.promptText	^0.1.3
documents.applyPatch	^0.1.4
images.requestImage	^0.1.5
recognition.recognizeStructure	^0.1.6
chemistry.structureToName, chemicalName report section	^0.1.7

The app version and API version serve different purposes. Do not put the app's 1.0.0 into apiVersion.

Manifest and identifiers

The required manifest fields are id, name, version, apiVersion, entry, and permissions. Optional metadata includes description, author, and license. contributes contains the arrays below; omitted arrays default to empty when parsed. Use parsePluginManifest to validate and normalize source manifests.

Surface	Required naming convention
Commands	plugin.<pluginName>.<action>
Menus	menu.<pluginName>.<action>
Panels and inspectors	panel.<pluginName>.<name>
Analyzers	analyzer.<pluginName>.<name>
Toolsets	An ID beginning with plugin.

These are schema-enforced namespaces. A compatibility parser accepts the older plugin.* analyzer spelling used by an already-packaged NMR plugin and normalizes it to analyzer.*; new source uses the canonical form. Contributions cannot require permissions the manifest did not declare. Host registration also checks command references and conflicts in the shared command registry.

Contribution kinds

contributes key	Purpose and important fields
commands	Registered behavior: id, title, requiredPermissions; optional category, description, default shortcut, enabled state.
menus	id, title, commandId, location, requiredPermissions. Locations: file, edit, view, structure, tools, analyze, plugins.
panels	id, title, optional rerun commandId, permissions.
toolbarButtons	Command reference plus optional title, group, order.
toolsets	Named toolbar groups with command-backed items, optional icon data URIs and preferred window size. Gated by ui.toolbar.
inspectors	Panel-shaped contribution metadata.
templates	Template identity, title, optional category and command.
importers, exporters	Format identity, title, extensions, command.
analyzers	Namespaced analyzer identity, title, command.
transformers	Transformer identity, title, command.
recognizers	Recognizer identity, title, command, input kind: selected-image, pasted-image, or image-file.

A schema entry is not a promise that every desktop surface automatically renders a custom workflow. Commands, menu integration, declarative reports, and toolsets have concrete host paths; verify the intended host integration for other contribution metadata.

Permissions

This is the complete pluginPermissions list. The dangerous column follows the SDK's dangerousPluginPermissions list, including the image.read name itself.

Permission	Dangerous	Exposed role or limitation
document.read	No	Active-document snapshot; document-aware layout gate.
document.write	Yes	Command-scoped insertion only.
document.proposePatch	No	Reviewed document proposals.
selection.read	No	Selection snapshot.
selection.write	No	No general context method.
analysis.write	No	Session analysis store.
ui.panel	No	Reports and text prompts.
ui.toolbar	No	Toolbar/toolset contributions.
ui.menu	No	Menu contributions.
chemistry.compute	No	Host chemistry methods.
clipboard.read	Yes	No general context method.
clipboard.write	No	No general context method.
image.read	Yes	Command-scoped user-chosen image.
ml.inference	No	Recognition gate.
model.load	Yes	Recognition gate; no arbitrary model loader.
model.download	Yes	No general context method; forbidden for recognition plugins.
filesystem.read	No	No general context method.
filesystem.write	Yes	No general context method.
network.fetch	Yes	Reserved; desktop rejects this declaration.
native.execute	Yes	Gate for process-backed host services.
plugin.storage	No	Scoped key/value storage.

See Plugin Permissions for interpretation. Declaration and installation do not create APIs missing from the context.

Command context

A PluginCommandHandler receives PluginCommandContext. It may return a result, return { ok: false, error }, or throw; the desktop surfaces failures in its status channel.

Context member	Methods / information	Gate
plugin	ID, name, version, declared permissions	Always present
documents	getActiveDocument, proposePatch, optional applyPatch	Object is present; read/proposal calls enforce their respective permissions. applyPatch is absent without document.write.
selection	getSelection	selection.read
analysis	write, list, getLatest	analysis.write; reads restricted to the caller's records
panels	showReport	ui.panel
dialogs	promptText	ui.panel; owning command must be active
images	requestImage	image.read; owning command must be active
recognition	recognizeStructure	All four recognition permissions; same command's host-provided image
chemistry	isotopeEnvelope; optional methods below	chemistry.compute
storage	get, set, delete, listKeys	plugin.storage
hasPermission, requirePermission	Query / enforce a declaration	Available on context

nameToStructure additionally needs native.execute; structureFromSmiles needs document.read; structureToName needs native.execute and selection.read and is command-scoped. Missing engines return explicit unavailability or failure results. Do not turn those into guessed chemistry.

Image acquisition accepts PNG, JPEG, TIFF, and WebP as Uint8Array bytes. The host caps input at 25 MB and 8192 pixels per side. Results distinguish provided, cancelled, and unavailable; a permission declaration does not remove user choice or these limits.

Patches and reports

documents.applyPatch accepts a ProposedDocumentPatch envelope with reason and patch, returning { applied: true, objectIds }. Only addObject and addAnnotation are accepted, with fresh IDs, during the plugin's command and in its originating document. Inferred output and changes to existing content use proposePatch. Recognition plugins cannot declare document.write or model.download alongside all four recognition permissions.

PluginPanelReport has title, sections, optional source (objectId, sourceFingerprint), and optional rerunCommandId. Section kinds are text, keyValue, table, svg, chemicalName, and linkedFigure. Use Plugin Runtime and Panels for lifecycle and staleness.

Fail-closed distribution and install checks

Stage	Checks
Packaging	SDK import boundary; relative imports stay inside package; committed clean source; explicit licence file; separate package.json dataLicenses when bundling datasets.
Archive inspection	Size/path limits, CRC-32 for every entry, safe paths, valid packaged manifest and provenance, existing entry file, compatible API.
Manual checksum	Missing sidecar allowed; a present invalid or mismatched sidecar refuses installation.
Catalog download	Exact allowlisted release repository and assets; required sidecar; GitHub digest, sidecar, and bytes agree by SHA-256.
Registration	Available permissions, valid contributions, no forbidden recognition/write combination, no command conflicts, successful versioned worker handshake.
Serving	TypeScript and Rust reject traversal; native serving checks filesystem containment.

Packages remain co-located on the host origin: tauri://localhost on macOS and http://tauri.localhost on Windows. Install and replacement failures roll back rather than leaving a half-registered plugin. Checksums and provenance describe integrity and origin records; they are not publisher signatures.

See also

• End-to-end tutorial
• Installing and updating plugins
• Runtime and panels