Rust SDK authoring

Minimal plugin type

#![allow(unused)]
fn main() {
use pixelflow_plugin_sdk::{
    FilterRegistration, MetadataKind, MetadataRegistration, Plugin, RegistrationContext, Result,
    pixelflow_plugin,
};

#[derive(Default)]
pub struct SamplePlugin;

impl Plugin for SamplePlugin {
    fn name(&self) -> &'static str {
        "pixelflow-sample-plugin"
    }

    fn register(&self, registry: &mut RegistrationContext<'_>) -> Result<()> {
        registry.register_filter(FilterRegistration::new(
            "sample.identity",
            "pixelflow",
            "sample",
        ))?;
        registry.register_metadata(MetadataRegistration::new(
            "pixelflow/sample:enabled",
            MetadataKind::Bool,
        ))
    }
}

pixelflow_plugin!(SamplePlugin);
}

What register() does

register() declares filters and metadata keys through RegistrationContext.

In current SDK surface:

• register_filter(FilterRegistration::new(...)) declares one filter name plus publisher and plugin namespaces.
• register_metadata(MetadataRegistration::new(...)) declares one metadata key and its MetadataKind.
• Registration is synchronous. Host accepts or rejects each declaration during plugin load.

Keep register() focused on capability declaration. Do not hand-write ABI tables or exported symbols.

Entry point export

pixelflow_plugin! exports pixelflow_plugin_entry_v1 and is supported path.

Macro requires plugin type to implement:

• Plugin
• Default
• 'static

SDK wraps entry-table export and registration callbacks with panic guards so plugin panics do not unwind across FFI boundary.

Source of truth

Start with examples/sample-rust-plugin/src/lib.rs for smallest working plugin. Read crates/pixelflow-plugin-sdk/src/lib.rs for Plugin, pixelflow_plugin!, ABI versioning, and entry-point behavior.

Also useful while authoring:

• crates/pixelflow-plugin-sdk/src/builders.rs for FilterRegistration and MetadataRegistration
• crates/pixelflow-plugin-sdk/src/registration.rs for RegistrationContext
• crates/pixelflow-plugin-sdk/tests/plugin_contracts.rs for SDK behavior and failure contracts

Practical authoring notes

• Keep plugin name() stable. Host uses it for diagnostics.
• Register plugin metadata keys before filters or scripts rely on them.
• Use committed sample plugin as smallest working template, not handwritten FFI.
• If host rejects registration callback, SDK surfaces structured plugin error instead of silent success.