feat(plugin-sdk): add video packet types, source node support, and host-side tick loop

[staging-devin-ai-integration]

Summary

Implements Phases 1–3 of the native plugin SDK infrastructure to support video output pins with proper pixel format metadata and source nodes (zero inputs, tick-driven output). This is groundwork for turning nodes like the Slint renderer into standalone plugins.

Phase 1 — Video packet types in C ABI (addresses #169):

• CPixelFormat enum (Rgba8/I420/Nv12) and CRawVideoFormat struct
• CPacketType::RawVideo (8) and CPacketType::EncodedVideo (9) discriminants
• raw_video_format field on CPacketTypeInfo
• Bidirectional conversions (pixel_format_to_c/from_c, raw_video_format_to_c/from_c, video frame ↔ CPacket)
• native_plugin_entry! macro updated to emit proper video pin metadata instead of mapping to Binary
• NATIVE_PLUGIN_API_VERSION bumped from 2 → 3
• Note: CPacketType::EncodedVideo discriminant exists for forward-compat, but inbound conversion maps to Binary until a CVideoCodec enum is added (TODO in code)

Phase 2 — Source node trait and macro in SDK:

• SourceConfig struct with from_fps() / from_interval_us() helpers
• NativeSourceNode trait (metadata, source_config, new, tick, update_params, cleanup)
• native_source_plugin_entry! macro generating tick/get_source_config FFI exports and a stub process_packet
• CSourceConfig and CTickResult C ABI types with convenience constructors
• CNativePluginAPI extended with Option<fn> fields for get_source_config and tick (backward-compatible v3)

Phase 3 — Host-side wrapper for source plugins:

• PluginMetadata gains is_source, tick_interval_us, max_ticks
• Source capability detected during load() via temporary instance probe with get_source_config (warns if probe fails)
• NativeNodeWrapper::run() split into run_processor() (existing input-driven loop) and run_source() (new tick-driven loop)
• run_source() implements Initializing → Ready → Start → Running → tick → Stopped lifecycle
• Tick timing uses tokio::time::interval with MissedTickBehavior::Skip (matching existing video nodes)
• Zero tick_interval_us clamped to 1µs to prevent tokio::time::interval panic
• Cancellation-aware inter-tick wait via tokio::select!
• All exit paths (including pre-start) emit Stopped state for consistent lifecycle
• Tick loop breaks on output channel close (source nodes lack the input-close backstop)
• register_plugins() handles empty inputs for source plugins

Compositor fix — frame-aligned sync in oneshot mode:

• In oneshot mode with multiple sources producing at different rates (e.g. colorbars vs slint), the compositor consumed frames from the faster source ahead of the slower one, causing asymmetric slot removal and producing frames with missing layers (black background + overlay)
• Fix: check readiness of all active (non-closed) slots via is_empty() before dequeuing, ensuring frame-aligned consumption regardless of production rate differences

Closes #169

Review & Testing Checklist for Human

• Compositor frame-aligned sync: Verify the oneshot frame-sync change doesn't break existing single-source oneshot pipelines (e.g. video_colorbars.yml). The change only affects multi-source oneshot compositing — single-source should behave identically since all slots trivially have frames.
• C ABI correctness: Verify CPacketTypeInfo layout with raw_video_format field — ensure no padding/alignment issues across compilers. Check that the v3 Option fields in CNativePluginAPI are ABI-safe (nullable function pointers).
• Source node lifecycle: Verify the Ready→Start handshake integrates correctly with the pipeline coordinator. The run_source() implementation assumes NodeControlMessage::Start is sent after all downstream nodes are ready.
• Video frame round-trip: Test that a plugin declaring PacketType::RawVideo(RawVideoFormat { width: Some(1920), height: Some(1080), pixel_format: Rgba8 }) correctly preserves metadata through the C ABI boundary.
• Backward compatibility: Load an existing v2 plugin (without get_source_config/tick) against the v3 host and verify it still works as a processor.

Suggested test plan:

1. Run video_colorbars.yml oneshot pipeline — should produce exactly 300 frames as before.
2. Run video_slint_watermark.yml (from PR feat(nodes): extract Slint overlay into standalone video::slint node #237) — should produce exactly 300 composited frames and terminate cleanly, with no extra black+overlay frames.
3. Write a minimal source plugin using native_source_plugin_entry!, build, load, and verify tick loop runs correctly.

Notes

• just lint and just test both pass clean (all 68 compositor tests pass).
• Macro duplication between native_plugin_entry! and native_source_plugin_entry! (~530 lines shared metadata logic) is a known fast-follow to extract into a helper macro.
• Phase 4 (porting the Slint node to a plugin) is deferred to a follow-up PR.

Link to Devin session: https://staging.itsdev.in/sessions/41c6ad828d354ab8a388cfe3cbe6475f
Requested by: @streamer45

---

[staging-devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring

[staging-devin-ai-integration]

Devin Review found 4 potential issues.

View 3 additional findings in Devin Review.

Debug

Playground

[staging-devin-ai-integration]

🚩 Source config probed with no-params instance may diverge from actual runtime config

During plugin loading at crates/plugin-native/src/lib.rs:122-144, a temporary instance is created with null params to probe get_source_config. The tick_interval_us and max_ticks values are cached in PluginMetadata and used later by run_source at crates/plugin-native/src/wrapper.rs:648-649. If a source plugin's tick interval depends on constructor parameters (e.g., a configurable frame rate), the probed values will be stale because the real instance is created later with actual params via create_node. The NativeSourceNode::source_config(&self) method signature allows per-instance config, but the host only reads it once at load time from the no-params probe. This is a documented design choice ("If instance creation fails we fall back to treating it as a processor plugin") but could surprise plugin authors whose tick rate depends on params.

---

Was this helpful? React with 👍 or 👎 to provide feedback.

Debug

Playground

[staging-devin-ai-integration]

Valid point. This is a deliberate design trade-off documented in the code — source plugins must support parameterless construction for the probe to work. The alternative (a static API query without instance creation) would require adding another function pointer to CNativePluginAPI and changing the macro contract. For now, the fallback behavior (treating the plugin as a processor) is safe, and the NativeSourceNode trait's new() signature already takes Option<serde_json::Value>, so well-behaved source plugins will handle None params gracefully.

If this becomes a friction point for plugin authors, we can add a static get_source_config variant (no instance required) in a future API revision.

[staging-devin-ai-integration]

Good refinement of the earlier point. You're right that the probed tick_interval_us/max_ticks could diverge from the real instance's config if the source plugin adjusts tick rate based on params.

In practice this is acceptable for now — the probe establishes that the plugin is a source and provides reasonable defaults. If we later need per-instance tick config, the fix is straightforward: query get_source_config again on the real instance inside run_source() after create_instance is called with actual params, and use those values instead of the metadata cache. That would be a small additive change in wrapper.rs.