standard_plugin/
lib.rs

1//! Write Standard Code plugins in Rust.
2//!
3//! Every plugin is a wasm component against the WIT package
4//! `standard:plugin@2.0.0`, built for `wasm32-wasip2`. This crate wraps the
5//! generated bindings in a safe API:
6//!
7//! - **UI plugins** ([`UiPlugin`], [`#[ui]`](macro@ui)) run in every viewer and paint
8//!   [`Surface`]s in the cell model ([`Cells`]) or the graphics model
9//!   ([`Pixels`]). They are side-effect free: effects that must happen once
10//!   go through [`claims`](mod@claims) or a companion daemon ([`calls`](mod@calls)), and
11//!   [`view::is_driving`] says whether the user is controlling this viewer.
12//! - **Daemon plugins** ([`daemon::DaemonPlugin`], [`#[daemon]`](macro@daemon))
13//!   run inside `standardd` with an async `run` loop on a small executor.
14//!
15//! The account interfaces ([`values`](mod@values), [`live`](mod@live), [`events`](mod@events), [`calls`](mod@calls),
16//! [`config`](mod@config), [`secrets`](mod@secrets), [`account`](mod@account)) are shared by both. Every call the
17//! plugin's manifest grants do not cover returns [`Error::GrantDenied`].
18//!
19//! A UI plugin is `#![no_std]` (the `std` library would import the WASI CLI
20//! world, which a viewer does not offer); `alloc` is available and this
21//! crate's default `runtime` feature supplies the allocator and panic
22//! handler. A UI plugin, in full:
23//!
24//! ```rust,ignore
25#![doc = include_str!("../examples/clock_card.rs")]
26//! ```
27//!
28//! More: the [`guide`] pages (the same Markdown files are this crate's
29//! `docs/` directory, and `standard-plugin guide` prints them), and the
30//! compiled examples in this crate's `examples/` directory. `testing` (on
31//! non-wasm targets) runs a plugin against an in-process host in ordinary
32//! `cargo test`.
33#![no_std]
34
35extern crate alloc;
36#[cfg(any(feature = "std", not(target_arch = "wasm32")))]
37extern crate std;
38
39#[cfg(target_endian = "big")]
40compile_error!("the shared surface buffer is little-endian");
41
42mod bindings;
43mod colour;
44mod error;
45mod geometry;
46mod host;
47mod input;
48mod local;
49#[cfg(all(target_arch = "wasm32", not(feature = "std")))]
50mod runtime;
51mod ui_runtime;
52
53pub mod api;
54pub mod daemon;
55pub mod draw;
56pub mod surface;
57#[cfg(not(target_arch = "wasm32"))]
58pub mod testing;
59
60pub use api::{
61    Json, Target, account, calls, capabilities, claims, config, events, health, live, secrets, url,
62    values, view,
63};
64pub use colour::{Attrs, Colour, Rgba, Style, ThemeSlot, recede};
65pub use draw::{Area, Image, Shapes, font};
66pub use error::{Error, Result};
67pub use geometry::{Geometry, Rect};
68pub use input::{Button, Key, KeyCode, KeyPhase, Modifiers, Pointer, PointerKind};
69pub use surface::{AnySurface, AnySurfaceMut, Cell, Cells, Instances, Pixels, Surface};
70pub use ui_runtime::{Context, Event, Frame, Power, UiPlugin};
71
72/// Exports the annotated type, which implements [`UiPlugin`], as the
73/// component's `ui-plugin` world. Put it on the plugin's struct or enum, or
74/// on its `impl UiPlugin for ...` block; once per plugin crate.
75pub use standard_plugin_macros::ui;
76
77/// Exports the annotated type, which implements [`daemon::DaemonPlugin`],
78/// as the component's `daemon-plugin` world.
79pub use standard_plugin_macros::daemon;
80
81/// Floating-point maths for `no_std` plugins (`libm::sinf`, `sqrtf`, ...):
82/// `core` has no `f32::sin`.
83pub use libm;
84
85/// What most plugins import: `use standard_plugin::prelude::*;`.
86pub mod prelude {
87    pub use crate::daemon::DaemonPlugin;
88    pub use crate::{
89        AnySurface, Area, Attrs, Button, Cells, Colour, Context, Error, Event, Frame, Geometry,
90        Instances, Json, Key, KeyCode, Modifiers, Pixels, Pointer, PointerKind, Rect, Rgba, Shapes,
91        Style, Surface, Target, ThemeSlot, UiPlugin,
92    };
93    pub use alloc::borrow::ToOwned;
94    pub use alloc::boxed::Box;
95    pub use alloc::format;
96    pub use alloc::string::{String, ToString};
97    pub use alloc::vec;
98    pub use alloc::vec::Vec;
99}
100
101/// The sources this SDK version is built from, for tools: the
102/// `standard-plugin` CLI checks components against [`sources::WIT`] and
103/// scaffolds new plugins from the examples, so both always match the SDK
104/// the new plugin depends on.
105pub mod sources {
106    /// The WIT package `standard:plugin@2.0.0` (`wit/plugin.wit`): the one
107    /// copy the SDK bindings, the viewer and daemon hosts and the CLI use.
108    pub const WIT: &str = include_str!("../wit/plugin.wit");
109
110    /// The compiled examples `standard-plugin new` starts from.
111    pub mod examples {
112        /// A cell-model sidebar card (`examples/clock_card.rs`).
113        pub const CLOCK_CARD: &str = include_str!("../examples/clock_card.rs");
114        /// A daemon plugin (`examples/heartbeat_daemon.rs`).
115        pub const HEARTBEAT_DAEMON: &str = include_str!("../examples/heartbeat_daemon.rs");
116        /// The UI half of a companion pair (`examples/together_ui.rs`).
117        pub const TOGETHER_UI: &str = include_str!("../examples/together_ui.rs");
118        /// The companion daemon (`examples/together_companion.rs`).
119        pub const TOGETHER_COMPANION: &str = include_str!("../examples/together_companion.rs");
120    }
121
122    /// One guide of this SDK version: its name, the file stem in `docs/`
123    /// (`standard-plugin guide <name>`), and its Markdown text.
124    #[derive(Clone, Copy, Debug, PartialEq, Eq)]
125    pub struct Guide {
126        pub name: &'static str,
127        pub text: &'static str,
128    }
129
130    impl Guide {
131        /// The text of its first heading, else its name.
132        #[must_use]
133        pub fn title(&self) -> &'static str {
134            self.text
135                .lines()
136                .next()
137                .and_then(|line| line.strip_prefix("# "))
138                .unwrap_or(self.name)
139        }
140    }
141
142    /// Every guide in this crate's `docs/` directory, in reading order,
143    /// the index first ([`crate::guide`] shows the same pages).
144    pub const GUIDES: &[Guide] = &[
145        Guide {
146            name: "README",
147            text: include_str!("../docs/README.md"),
148        },
149        Guide {
150            name: "getting-started",
151            text: include_str!("../docs/getting-started.md"),
152        },
153        Guide {
154            name: "agent-guide",
155            text: include_str!("../docs/agent-guide.md"),
156        },
157        Guide {
158            name: "manifest",
159            text: include_str!("../docs/manifest.md"),
160        },
161        Guide {
162            name: "grants",
163            text: include_str!("../docs/grants.md"),
164        },
165        Guide {
166            name: "rendering",
167            text: include_str!("../docs/rendering.md"),
168        },
169        Guide {
170            name: "input",
171            text: include_str!("../docs/input.md"),
172        },
173        Guide {
174            name: "handlers",
175            text: include_str!("../docs/handlers.md"),
176        },
177        Guide {
178            name: "previews",
179            text: include_str!("../docs/previews.md"),
180        },
181        Guide {
182            name: "working-together",
183            text: include_str!("../docs/working-together.md"),
184        },
185        Guide {
186            name: "daemon-plugins",
187            text: include_str!("../docs/daemon-plugins.md"),
188        },
189        Guide {
190            name: "testing",
191            text: include_str!("../docs/testing.md"),
192        },
193        Guide {
194            name: "publishing",
195            text: include_str!("../docs/publishing.md"),
196        },
197        Guide {
198            name: "abi",
199            text: include_str!("../docs/abi.md"),
200        },
201        Guide {
202            name: "other-languages",
203            text: include_str!("../docs/other-languages.md"),
204        },
205    ];
206}
207
208/// The guides, as pages of this documentation. The same Markdown files are
209/// this crate's `docs/` directory, where links between guides resolve, and
210/// `standard-plugin guide` prints them for the SDK version a plugin's
211/// `Cargo.lock` resolves.
212pub mod guide {
213    #[doc = include_str!("../docs/README.md")]
214    pub mod index {}
215    #[doc = include_str!("../docs/getting-started.md")]
216    pub mod getting_started {}
217    #[doc = include_str!("../docs/agent-guide.md")]
218    pub mod agent_guide {}
219    #[doc = include_str!("../docs/manifest.md")]
220    pub mod manifest {}
221    #[doc = include_str!("../docs/grants.md")]
222    pub mod grants {}
223    #[doc = include_str!("../docs/rendering.md")]
224    pub mod rendering {}
225    #[doc = include_str!("../docs/input.md")]
226    pub mod input {}
227    #[doc = include_str!("../docs/handlers.md")]
228    pub mod handlers {}
229    #[doc = include_str!("../docs/previews.md")]
230    pub mod previews {}
231    #[doc = include_str!("../docs/working-together.md")]
232    pub mod working_together {}
233    #[doc = include_str!("../docs/daemon-plugins.md")]
234    pub mod daemon_plugins {}
235    #[doc = include_str!("../docs/testing.md")]
236    pub mod testing {}
237    #[doc = include_str!("../docs/publishing.md")]
238    pub mod publishing {}
239    #[doc = include_str!("../docs/abi.md")]
240    pub mod abi {}
241    #[doc = include_str!("../docs/other-languages.md")]
242    pub mod other_languages {}
243}
244
245/// Used by the export macros; not part of the public API.
246#[doc(hidden)]
247pub mod __private {
248    pub use crate::bindings::{daemon as daemon_bindings, ui as ui_bindings};
249    pub use crate::daemon::runtime::DaemonRuntime;
250    pub use crate::ui_runtime::UiRuntime;
251    pub use alloc::string::String;
252}
253
254/// Exports a [`UiPlugin`] type; `#[standard_plugin::ui]` expands to this.
255#[doc(hidden)]
256#[macro_export]
257macro_rules! __export_ui {
258    ($plugin:ty) => {
259        const _: () = {
260            static RUNTIME: $crate::__private::UiRuntime<$plugin> =
261                $crate::__private::UiRuntime::new();
262
263            struct Export;
264
265            impl $crate::__private::ui_bindings::Guest for Export {
266                fn activate(config: $crate::__private::String) {
267                    RUNTIME.activate(config);
268                }
269
270                fn frame(
271                    now_ms: u64,
272                    interval_ms: u32,
273                    power: $crate::__private::ui_bindings::Power,
274                ) -> Option<u64> {
275                    RUNTIME.frame(now_ms, interval_ms, power.into())
276                }
277
278                fn event(event: $crate::__private::ui_bindings::Event) {
279                    RUNTIME.event(event.into());
280                }
281
282                fn deactivate() {
283                    RUNTIME.deactivate();
284                }
285            }
286
287    $crate::__export_ui_plugin_impl!(Export with_types_in $crate::__private::ui_bindings);
288        };
289    };
290}
291
292/// Exports a [`daemon::DaemonPlugin`] type; `#[standard_plugin::daemon]`
293/// expands to this.
294#[doc(hidden)]
295#[macro_export]
296macro_rules! __export_daemon {
297    ($plugin:ty) => {
298        const _: () = {
299            static RUNTIME: $crate::__private::DaemonRuntime<$plugin> =
300                $crate::__private::DaemonRuntime::new();
301
302            struct Export;
303
304            impl $crate::__private::daemon_bindings::Guest for Export {
305                fn activate(config: $crate::__private::String) {
306                    RUNTIME.activate(config);
307                }
308
309                fn event(event: $crate::__private::daemon_bindings::Event) {
310                    RUNTIME.event(event.into());
311                }
312
313                fn drive(now_ms: u64) -> Option<u64> {
314                    RUNTIME.drive(now_ms)
315                }
316
317                fn deactivate() {
318                    RUNTIME.deactivate();
319                }
320            }
321
322            impl $crate::__private::daemon_bindings::exports::standard::plugin::daemon_events::Guest
323                for Export
324            {
325                fn handle_event(
326                    event: $crate::__private::daemon_bindings::exports::standard::plugin::daemon_events::DaemonEvent,
327                ) {
328                    RUNTIME.event(event.into());
329                }
330            }
331
332            impl $crate::__private::daemon_bindings::exports::standard::plugin::companion::Guest
333                for Export
334            {
335                fn handle_call(
336                    method: $crate::__private::String,
337                    payload: $crate::__private::String,
338                    from: $crate::__private::daemon_bindings::exports::standard::plugin::companion::Caller,
339                ) -> Result<
340                    $crate::__private::String,
341                    $crate::__private::ui_bindings::standard::plugin::types::CallError,
342                > {
343                    RUNTIME
344                        .handle_call(&method, payload, from.into())
345                        .map_err(Into::into)
346                }
347            }
348
349            // Only a component exports. Natively, interface exports are
350            // `<interface>#<function>` symbols, and `#` starts a comment in
351            // the macOS linker's exported-symbols list.
352            #[cfg(target_family = "wasm")]
353            $crate::__export_daemon_plugin_impl!(
354                Export with_types_in $crate::__private::daemon_bindings
355            );
356
357            // A native build (tests, `cargo check`) still uses the plugin
358            // through the same entry points.
359            #[cfg(not(target_family = "wasm"))]
360            #[allow(dead_code)]
361            fn native_entry_points() {
362                use $crate::__private::daemon_bindings::Guest as _;
363                use $crate::__private::daemon_bindings::exports::standard::plugin::companion::Guest as _;
364                use $crate::__private::daemon_bindings::exports::standard::plugin::daemon_events::Guest as _;
365                let _ = (
366                    Export::activate,
367                    Export::event,
368                    Export::handle_event,
369                    Export::drive,
370                    Export::deactivate,
371                    Export::handle_call,
372                );
373            }
374        };
375    };
376}
standard_plugin/lib.rs

standard_plugin/
lib.rs
