Installing and Updating Plugins

Installing and Updating Plugins

This page explains desktop package installation, explicit update review, and where ChemDraft keeps installed plugins on macOS and Windows.

Install from the catalog

1. Open Plugins → Add or Remove Plugins….
2. In Available, choose Install beside the plugin you want.
3. Wait for ChemDraft to fetch and inspect the release package.
4. Review the plugin's name, ID, version, permissions, unpacked size, source commit, SDK version, and SHA-256 digest.
5. Choose Install in the package review.

The catalog is compiled into the app. Plugins cannot add their own catalog entries or update URLs. A listed plugin without a published release can remain visible while installation reports that no release is available. The catalog is therefore a list of known sources, not a live claim about release availability.

Orthonym and MolScribe catalog installs also disclose their required local engines. Engine installation can fail or be cancelled independently of package installation. If the plugin remains installed but its engine is missing, the manager offers Install engine. Follow the engine's disk-space and platform messages. MolScribe recognition is explicitly experimental.

Install a downloaded ZIP

1. Obtain a built ChemDraft plugin package from a source you trust. Leave the ZIP intact.
2. If supplied, keep the matching .zip.sha256 file beside the ZIP with its original matching name.
3. Open Plugins → Add or Remove Plugins… and choose Add plugin from package….
4. Select the ZIP in the file picker.
5. Read the inspection and choose Install.

The adjacent checksum is read automatically by native code. A missing sidecar permits installation but the review says no .sha256 sidecar found. An existing sidecar that is malformed, unreadable, unsafe, or mismatched refuses installation. Every archive entry's CRC-32 check still runs when no sidecar exists. CRC-32 checks for archive corruption; SHA-256 checks the archive against the supplied digest. Neither identifies a trustworthy author.

A source archive produced by plugin:extract is intended for developers composing a host. Desktop installation needs the built package produced by plugin:package, with manifest.json, the compiled worker entry, and its assets.

Enable, disable, or remove

The manager's enable control changes whether a plugin's commands and contributions are registered. Disabling tears down its worker and closes its panels. Re-enabling creates a usable runtime again; it does not keep an old command running in the background.

Removing an installed package removes its registration and staged package. Optional engine management has its own controls, so inspect the engine row when you also want to reclaim an engine's disk space. Pending document proposals survive a plugin disable or unregister operation until reviewed; an update must not silently discard a result awaiting your decision.

Check and apply updates

1. In the manager, choose Check for plugin updates.
2. For an available replacement, choose Review update….
3. Read the downloaded package review, including its version and permissions.
4. Choose Update to start replacement.

Checks and replacements are user-initiated. Automatic update sources exist only for plugin IDs in the host's allowlist. The host reads the latest stable GitHub release from the exact catalog repository, checks versioned asset names and download paths, and requires both ZIP and checksum assets. The published checksum must agree with GitHub's recorded asset digest; downloaded bytes must agree with that checksum.

A candidate update is staged separately and must complete its worker handshake. Only then does the host swap registration and commit the new install record. Failures before that commit roll back the candidate and preserve or restore the prior package. The disabled preference survives replacement. This is an integrity-checked replacement transaction, not a cryptographic publisher-signature system.

Storage and platform differences

Packages live in installed-plugins under Tauri's app-data directory; installed-plugins.json holds the install records. Here $APPDATA/installed-plugins/ means the application's data location, not a universal shell variable to paste on both systems. macOS uses its Application Support location; Windows uses its app-data location. Development builds have separate identities and data from the stable app.

The packaged app serves these files at /installed-plugins/ on its existing origin:

Platform	App origin
macOS	tauri://localhost
Windows	http://tauri.localhost

The development server mirrors that path. Keeping entry modules, chunks, nested workers, and data together lets relative imports resolve. Moving an individual JavaScript file or serving it from another origin breaks that contract. App updates replace program files while keeping identifier-scoped app data, so installed plugins normally survive an app replacement.

If installation fails

Read the specific message. Wrong checksums, invalid manifests, unsupported permissions, incompatible API requirements, unsafe paths, duplicate IDs, missing entries, and worker-startup failures all refuse installation. Correct the package or obtain a compatible release; bypassing a gate is not a repair. A failed handshake does not count as an installed plugin.

See also

• Plugin permissions
• Official plugins and engine requirements
• Troubleshooting
• API and package-validation reference