initial commit

_bmad-output/implementation-artifacts/12-1-plugin-api-rust-trait.md

@@ -0,0 +1,37 @@
+---
+epic: 12
+story: 12.1
+title: "Plugin API (Rust Trait)"
+status: draft
+---
+
+## Epic 12 — Plugin & Extension System
+**Goal:** Let power users extend CalcPad.
+
+### Story 12.1: Plugin API (Rust Trait)
+
+As a Rust developer,
+I want to implement a `CalcPadPlugin` trait to extend CalcPad with custom functions, units, and variables,
+So that I can add domain-specific capabilities to the engine.
+
+**Acceptance Criteria:**
+
+**Given** the `CalcPadPlugin` trait is defined in the calcpad-engine crate
+**When** a developer implements the trait
+**Then** they can provide implementations for `register_functions()`, `register_units()`, and `register_variables()`
+**And** each method receives a registry to add new capabilities
+
+**Given** a developer compiles their plugin as a dynamic library (.dylib on macOS, .dll on Windows, .so on Linux)
+**When** CalcPad loads the plugin at startup
+**Then** the registered functions, units, and variables are available in expressions
+**And** conflicts with built-in names are reported as warnings
+
+**Given** a developer compiles their plugin as a WASM module
+**When** CalcPad loads the WASM plugin
+**Then** the registered functions, units, and variables are available in expressions
+**And** the WASM plugin runs in a sandboxed environment with no filesystem or network access
+
+**Given** a plugin registers a custom function (e.g., `bmi(weight, height)`)
+**When** a user types `bmi(80kg, 1.8m)` in a sheet
+**Then** the plugin function is invoked with the provided arguments
+**And** the result is displayed in the answer column