feat: v0.1.0 — Studio Plugin SDK

First release of the SDK that Studio plugins depend on.

What v0.1 ships:

- WIT contract under wit/ (studio-plugin.wit +
  deps/platform/world.wit, both verbatim from
  fai/platform/wit/).
- wit-bindgen 0.36 generate! call with pub_export_macro
  enabled so the emitted __export_studio_plugin_impl! macro
  is reachable from downstream plugin crates.
- export_plugin!(MyType) convenience macro that wraps the
  bindgen-generated impl macro.
- README documenting usage + v0.1 limits (single-world ->
  all-three-hooks-required, no proc-macro yet, edition
  2021 pinned by wit-bindgen output).

What v0.1 doesn't yet do:

- Plugins still declare all three Guest impls (theme,
  translate, output-view). v0.2 splits the WIT into one
  world per hook.
- No #[plugin(...)] proc-macro. v0.2 wraps generate! +
  Guest impl generation into a single attribute.
- Host-side: the hub doesn't yet load studio-plugin-world
  components or expose InvokePlugin RPC — that's the next
  push.

Validated against the in-tree studio-theme-solarized
plugin: 22 KiB stripped .wasm artefact, valid Component
Model, passes wasm-tools component wit inspection.

Signed-off-by: flemming-it <sf@flemming.it>

wit/deps/platform/world.wit

@@ -0,0 +1,99 @@
+// =============================================================
+// FROZEN. Wire contract between hub and modules.
+// =============================================================
+//
+// This file is the stable wire contract between the F∆I Hub
+// and any module compiled against it. It is **frozen at v1.0**.
+//
+// Frozen means:
+//
+//   - No removal, rename, or signature change of any existing
+//     interface, function, type, field, or variant case.
+//   - Additive changes (new types, new variant cases at the end,
+//     new fields with stable defaults) require a minor bump
+//     (1.0 -> 1.1) and a coordinated review.
+//   - Any breaking change requires a major bump (1.0 -> 2.0)
+//     and a parallel-world transition plan.
+//
+// The fai_runtime crate ships a snapshot test that fails if
+// this file changes without an intentional, reviewed update.
+// See `crates/fai_runtime/tests/wit_freeze.rs`.
+//
+// Module authors do NOT depend on this file directly. They
+// use `fai-module-sdk`, which wraps these bindings behind a
+// stable, ergonomic surface. That is what protects modules
+// from any future evolution of this contract.
+
+package fai:platform@1.0.0;
+
+/// Types that flow between the host (hub) and modules.
+interface types {
+  /// A typed value passed between the host and a module.
+  variant payload {
+    /// Plain UTF-8 text.
+    text(string),
+    /// Arbitrary JSON encoded as a string.
+    json(string),
+    /// Raw bytes with a MIME type.
+    bytes(bytes-value),
+    /// A reference to a file, by URI.
+    file-ref(file-ref),
+  }
+
+  /// Inline byte content.
+  record bytes-value {
+    mime-type: string,
+    data: list<u8>,
+  }
+
+  /// File reference by URI.
+  record file-ref {
+    uri: string,
+    mime-type: string,
+    size-bytes: u64,
+    sha256: string,
+  }
+
+  /// Context passed with every invocation.
+  record invocation-context {
+    invocation-id: string,
+    capability-namespace: string,
+    capability-name: string,
+    deadline-ms: u64,
+  }
+
+  /// Structured error type returned by modules.
+  variant invocation-error {
+    invalid-input(string),
+    permission-denied(string),
+    resource-exhausted(string),
+    deadline-exceeded,
+    internal(string),
+  }
+}
+
+/// The host-provided interface that modules can import to talk back.
+interface host {
+  /// Log a structured message. Level is "trace", "debug", "info", "warn", "error".
+  log: func(level: string, message: string);
+}
+
+/// The core interface every module exports.
+interface invoke {
+  use types.{payload, invocation-context, invocation-error};
+
+  /// Invoke the module with inputs, receive outputs or an error.
+  invoke: func(
+    ctx: invocation-context,
+    inputs: list<tuple<string, payload>>,
+  ) -> result<list<tuple<string, payload>>, invocation-error>;
+}
+
+/// The world a module component targets.
+///
+/// Modules `export` the invoke interface to be callable by the hub.
+/// Modules `import` the host interface to emit logs.
+world module {
+  import host;
+  export invoke;
+}

wit/studio-plugin.wit

@@ -0,0 +1,187 @@
+// =============================================================
+// DRAFT. Studio plugin contract — NOT yet frozen.
+// =============================================================
+//
+// This file is the v0-draft WIT contract for the Studio plugin
+// subsystem described in `docs/advanced/studio-plugins.md`.
+//
+// Status: draft. Subject to break-change until the first
+// in-tree plugin (studio.theme.solarized) round-trips through
+// the Studio plugin-host implementation. Once it does, this
+// file moves to v0.1 and follows the same freeze-rules as
+// `world.wit`.
+//
+// Why a separate WIT file:
+//
+//   - `world.wit` defines the host-to-module wire for *flow
+//     modules* (text.extract, llm.chat etc.). Those modules
+//     speak in payloads + flow capabilities — concepts the
+//     plugin layer doesn't need.
+//   - Studio plugins are also WASM modules sandboxed by the
+//     hub, but their host is the Studio GUI, not the flow
+//     engine. They want a different surface: theme tokens,
+//     translation calls, output-view widget specs.
+//
+// Plugins target the `studio-plugin` world below. The host
+// (Studio) instantiates the component, calls the relevant
+// hook function per declared `studio_extension.hook` in
+// module.yaml, and renders / wires the result.
+
+package fai:studio-plugin@0.1.0;
+
+// =============================================================
+// Shared types
+// =============================================================
+
+interface plugin-types {
+  /// What kind of hook the plugin satisfies. The hub reads
+  /// this from `module.yaml#studio_extension.hook`. A single
+  /// plugin module can declare multiple hooks (e.g. a theme
+  /// plugin that also provides a translation back-end) by
+  /// exporting more than one of the hook interfaces; the hub
+  /// matches each exported hook against the declared hook
+  /// list.
+  enum hook-kind {
+    translate,
+    output-view,
+    theme,
+  }
+
+  /// Studio renders in a Material 3 color-scheme. Plugins
+  /// produce one for each brightness; both are required so
+  /// the operator's light/dark toggle keeps working.
+  record color-scheme {
+    /// "light" or "dark". The plugin returns one scheme per
+    /// brightness via separate `theme-for` calls.
+    brightness: string,
+    /// 32-bit ARGB packed colors. Order matches Material 3:
+    /// primary, on-primary, secondary, on-secondary,
+    /// tertiary, on-tertiary, error, on-error, surface,
+    /// on-surface, surface-variant, on-surface-variant,
+    /// outline, outline-variant.
+    /// Studio fills any missing slot from its built-in
+    /// fallback before applying.
+    tokens: list<u32>,
+  }
+
+  /// Describes how to render a single flow output. Returned
+  /// from `output-view.render`. Studio reads `kind` and
+  /// builds the matching widget tree.
+  variant rendered-output {
+    /// Plain text — Studio shows a SelectableText.
+    text(string),
+    /// Markdown — Studio shows a Markdown widget with the
+    /// shared FaiTheme.markdownStyle.
+    markdown(string),
+    /// Already-pretty-printed JSON — Studio shows it in a
+    /// code-block container.
+    pretty-json(string),
+    /// PNG / JPEG image data, ready to feed Image.memory.
+    /// MIME stays out because Flutter sniffs it; the plugin
+    /// is responsible for delivering a real image format.
+    image(list<u8>),
+    /// Bag-of-fields the plugin couldn't render but wants
+    /// passed through. Studio falls back to its built-in
+    /// renderer. `reason` is operator-visible — explain why
+    /// the plugin declined.
+    passthrough(string),
+  }
+
+  /// Generic error a plugin can return without panicking.
+  variant plugin-error {
+    /// The plugin understands the request but refused (e.g.
+    /// translate called with from==to). Studio falls back
+    /// to the built-in renderer.
+    declined(string),
+    /// The plugin is mis-configured (e.g. translate plugin
+    /// pointed at an unreachable Ollama endpoint). Operator
+    /// sees the message in the friendly-error mapper.
+    misconfigured(string),
+    /// Generic catch-all. Avoid when one of the above fits.
+    internal(string),
+  }
+}
+
+// =============================================================
+// Hook interfaces — each is optional. A plugin exports the
+// ones it satisfies; the hub only calls those.
+// =============================================================
+
+/// `translate` hook. Used by Studio to translate server-supplied
+/// English text (MCP tool descriptions, n8n endpoint names, LLM
+/// output) into the active locale. The honest `[EN]` badge stays
+/// the fallback when no translate plugin is installed or every
+/// installed plugin declines.
+interface translate {
+  use plugin-types.{plugin-error};
+
+  /// Translate `text` from `from-locale` to `to-locale`.
+  /// BCP-47 codes (e.g. "en", "de", "en-US"). Empty
+  /// `from-locale` lets the plugin auto-detect; an empty
+  /// `to-locale` is an error — the host always knows the
+  /// target locale.
+  translate: func(
+    text: string,
+    from-locale: string,
+    to-locale: string,
+  ) -> result<string, plugin-error>;
+}
+
+/// `output-view` hook. Used by Studio's FaiFlowOutput widget
+/// to ask a plugin "do you want to render this payload?". The
+/// plugin returns either a rendered-output variant or
+/// `passthrough` so Studio falls back. Plugins are queried in
+/// operator-configured priority order; the first non-
+/// `passthrough` answer wins.
+interface output-view {
+  use plugin-types.{rendered-output, plugin-error};
+
+  /// `mime-type` is the value from the bytes/file payload
+  /// (e.g. "application/pdf", "image/png"). Empty when the
+  /// payload kind doesn't carry one (text / json).
+  /// `data` is the payload's raw content. Text/json payloads
+  /// arrive UTF-8 encoded; bytes/file payloads stay raw.
+  /// The plugin decides whether to handle the type.
+  render: func(
+    mime-type: string,
+    data: list<u8>,
+  ) -> result<rendered-output, plugin-error>;
+}
+
+/// `theme` hook. Used by Studio's theme selector at startup.
+/// The plugin returns one color-scheme per brightness; Studio
+/// merges with its built-in fallback for unspecified tokens.
+interface theme {
+  use plugin-types.{color-scheme, plugin-error};
+
+  /// `brightness` is "light" or "dark". The host calls the
+  /// function twice at theme-apply time (once per brightness)
+  /// so plugins can implement both in one place.
+  theme-for: func(brightness: string) -> result<color-scheme, plugin-error>;
+}
+
+// =============================================================
+// World — what a plugin component looks like to the host.
+// =============================================================
+
+/// A Studio plugin component. Plugins target this world via
+/// `cargo build --target wasm32-wasip2` after declaring it in
+/// their Cargo.toml's `[package.metadata.component]`.
+///
+/// Plugins export only the hooks they implement. The hub
+/// probes which exports exist via component-introspection
+/// before issuing the matching call — so a plugin that only
+/// declares `hook: theme` in module.yaml needs to export only
+/// the `theme` interface, not the others.
+world studio-plugin {
+  /// Plugins import the same `host` interface as flow modules,
+  /// so they can emit structured logs without a separate
+  /// bridge. Logs flow into the hub's event log.
+  import fai:platform/host@1.0.0;
+
+  /// Hook exports. Each is optional; the hub introspects the
+  /// component to learn which the plugin supports.
+  export translate;
+  export output-view;
+  export theme;
+}