docs(cli-rs): document the plugin ABI without its rollout history

Put allocator ownership, table negotiation, effect ordering and panic handling first. Describe the current contracts for surfaces, geometry and worker threads. Schema and task checks passed (31 tests).
This commit is contained in:
Simon Klee
2026-11-18 20:39:16 +01:00
Unverified
parent 6d804352b1
commit 27805b87b9
15 changed files with 370 additions and 563 deletions
+5 -5
View File
@@ -1,16 +1,16 @@
[package]
name = "opencode-plugin-abi"
description = "The C ABI of native TUI plugins for opencode-native (P.4), and plugin! for plugins written in Rust."
description = "C ABI and Rust SDK for native TUI plugins."
version.workspace = true
edition.workspace = true
license.workspace = true
publish.workspace = true
[features]
# For the host only (provisional): the host constructs and matches the contract's types whole, so a type a later
# 2.x extends breaks the host's build until it handles the addition. It is not part of the SDK's compatibility
# promise: a crate that turns it on may break on any later 2.x. A plugin never turns it on; without it the types are
# `#[non_exhaustive]`, and what a later 2.x adds is no break of a plugin's source (carbon-4).
# For the host only (provisional): the host constructs and matches the contract's types whole, so a type a later 2.x
# extends breaks the host's build until it handles the addition. It is not part of the SDK's compatibility promise: a
# crate that turns it on may break on any later 2.x. A plugin never turns it on; without it the types are
# `#[non_exhaustive]`, and what a later 2.x adds is no break of a plugin's source.
host = []
# What a later 2.x adds, for the SDK's own test that a pinned plugin's source builds through it (`tests/sdk.rs`).
# No plugin and no host turns it on.
@@ -1,4 +1,4 @@
//! Constructors and setters of the types a plugin builds (carbon-4, big-boi 14). The contract's types are
//! Constructors and setters of the types a plugin builds. The contract's types are
//! `#[non_exhaustive]` to a plugin's crate, so it builds one from `Type::new(what it must have)` (or `Default`) and a
//! setter for each other field, named for the field; a field or a variant a later 2.x adds is then no break of its
//! source. Struct variants a plugin builds (a scroll verb, a target, an edit) do not grow: a later 2.x adds a variant
@@ -596,8 +596,6 @@ impl Node {
mod tests {
use super::*;
// Expected: each kind of setter does what the macro says: a value converts, an option is set to `Some`, and a
// flag is set; a constructor sets what it takes and leaves the rest as the type's default.
#[test]
fn setters_convert_wrap_and_flag() {
let command = Command::new("a.b").title("Title").group("Group").palette().arguments().scope(Scope::Base);
@@ -607,7 +605,7 @@ mod tests {
);
assert!(command.palette && command.arguments && !command.description.is_some());
assert_eq!(command.scope, Scope::Base);
// Contract ergonomics 2.5: enabled unless it says otherwise, which the JSON carries only then.
// Enabled unless it says otherwise, which the JSON carries only then.
assert!(command.enabled && !Command::new("a.b").disabled().enabled);
assert_eq!(serde_json::to_value(Command::new("a.b").disabled()).unwrap()["enabled"], false);
assert!(serde_json::to_value(Command::new("a.b")).unwrap().get("enabled").is_none());
@@ -636,8 +634,6 @@ mod tests {
assert_eq!((toast.title.as_deref(), toast.session), (Some("t"), None));
}
// Expected: a prompt is a struct inside the dialog, and its JSON is what the struct variant wrote: the tag beside
// the fields, and no placeholder when it has none.
#[test]
fn a_prompt_writes_the_json_of_the_variant() {
let dialog = crate::Dialog::Prompt(Prompt::new("Name", Action::command("n")).placeholder("type"));
@@ -654,7 +650,6 @@ mod tests {
assert_eq!((json["value"].as_str(), json["description"].as_str()), (Some("Old title"), Some("/tmp/project")));
}
// Expected: the diff setters reach a diff, and leave any other node as it was.
#[test]
fn node_setters_reach_their_variant_only() {
let diff = Node::diff(Source::Text("x".to_owned())).filetype("rust").hunks("h").diff_padding(2);
@@ -1,5 +1,4 @@
//! Typed calls: a request from [`crate::client`] sent as a [`Fetch`] and its reply decoded as the operation's output
//! (`design/contract-ergonomics.md` 2.2 B). [`Cx::call`], [`Cx::call_on_thread`] and [`Cx::send`] send them.
//! Typed calls: a request from [`crate::client`] sent as a [`Fetch`] and its reply decoded as the operation's output. [`Cx::call`], [`Cx::call_on_thread`] and [`Cx::send`] send them.
//!
//! ```
//! # use opencode_plugin_abi::*;
@@ -1,6 +1,6 @@
//! A canvas's display list (synthesis 4.2, layer 2 of `boundary-fable.md`): what a plugin draws into a
//! [`crate::v2::Node::Canvas`], which the host keeps and replays on every frame it paints until the plugin presents
//! another. The plugin owns the cells inside the canvas; the host owns its rectangle, its clip and the clock.
//! A canvas's display list: what a plugin draws into a [`crate::v2::Node::Canvas`], which the host keeps and replays
//! on every frame it paints until the plugin presents another. The plugin owns the cells inside the canvas; the host
//! owns its rectangle, its clip and the clock.
//!
//! A list is bytes, the same on every carrier: a version byte, then records. A record is its operation (one byte), the
//! length of its payload (`u32`, little-endian) and the payload, so a reader skips an operation it does not know.
@@ -527,8 +527,6 @@ mod tests {
const RED: Rgba = Rgba::new(255, 0, 0, 255);
const BLUE: Rgba = Rgba::new(0, 0, 255, 128);
// Expected: the builder writes the bytes of the format's table, written out here by hand, and they read back as
// the operations it was given.
#[test]
fn a_list_is_the_bytes_of_its_table() {
let style = Style { fg: Some(RED), bold: true, underline: true, ..Style::new() };
@@ -556,8 +554,6 @@ mod tests {
);
}
// Expected: every operation reads back as written, cells in their order with their styles, and a rect without a
// background reads back without one; each style bit alone reads back as that bit; the run counts its cells.
#[test]
fn every_operation_reads_back() {
let lit = Style::new().bg(BLUE).fg(RED);
@@ -587,7 +583,6 @@ mod tests {
assert_eq!(check(list.as_bytes()), Ok(Checked { ops: 6 }), "a run of three cells counts three");
}
// Expected: a record of a kind this version does not know is counted and skipped, and the records after it read.
#[test]
fn an_unknown_operation_is_skipped() {
let mut bytes = vec![VERSION, 99, 3, 0, 0, 0, 1, 2, 3];
@@ -599,10 +594,6 @@ mod tests {
assert_eq!(ops(&bytes).count(), 2);
}
// Expected: bytes that are not a list are refused whole, whatever came before the fault: no version, another
// version, a record cut short or longer than the list, a fixed record of another length, text that is not UTF-8,
// a character that is not one, alone or in a run of cells, a partial cell, cells of no width, an unknown border,
// and a pop without a clip.
#[test]
fn a_list_the_host_cannot_read_is_refused() {
let good = List::new().fill(0, 0, 1, 1, RED).clone().into_bytes();
@@ -637,8 +628,6 @@ mod tests {
assert!(malformed(List::new().pop().as_bytes()));
}
// Expected: a list at a limit is drawn, and one over it is not: one byte, one operation, one cell of a run, one
// byte of a text, one clip open more. Each is a resource limit; a list that is malformed too is refused as such.
#[test]
fn a_list_over_a_limit_is_not_drawn() {
let over = |list: &List| match check(list.as_bytes()) {
+4 -15
View File
@@ -1,19 +1,8 @@
//! Renderer claims of contract 2.0 (`rich-plugins/synthesis.md` 4.2 and 4.11, phase Pr): a plugin claims the tool
//! calls of one tool, or the Markdown fences of one language, and draws each claimed part in the transcript with a
//! keyed tree ([`v2::Node`]), as a surface does. The host's own row is the fallback: it draws the part whenever the
//! claim declines it (its view returns `None`), and when the claim cannot (its plugin failed, a view took longer than
//! the overrun limit, it returned a tree the host refused, the plugin is disabled or reloads). A tree refused for a keep
//! the host does not hold is asked for once more, whole.
//! A renderer claim draws a tool call or fenced block as a keyed tree. The host shows its own row if the claim
//! declines or fails. If a keep refers to a missing subtree, the host asks once for a complete tree.
//!
//! Each claimed part is a mount ([`v2::MountId`]) with a generation of its own; what the view gave the host (content,
//! memo values) goes with the part. The view gets the part as it is now ([`Part`]), and the surface input with the
//! part's width; its height is 0, as a part is as tall as its tree. It runs in the frame that first shows the part,
//! again when the part or its width changes, and while the part streams (the same state with new content) at most
//! once a frame, with the newest content, whichever row shows the part until then. A part that leaves the transcript
//! forgets its tree.
//!
//! A plugin registers claims with [`crate::Setup::claim`], on either carrier: in process with Rust values, and over the
//! C ABI as [`crate::Manifest::claims`] and [`crate::Request::Claim`], answered by a [`Reply`].
//! Each part owns its mount, content handles and memo values. Its width comes from the transcript; its height
//! comes from its tree. Streaming revisions within one phase coalesce to the newest value per frame.
use std::rc::Rc;
@@ -1,19 +1,7 @@
//! Contract 2.0's input and surfaces (`rich-plugins/synthesis.md` 3.8 and 4.2, phase P2): a docked panel and an
//! overlay beside the route and the slot ([`crate::v2::Place`]); focus; key layers with scopes, priorities and modes,
//! whose handler returns [`Handled::Consume`] or [`Handled::Pass`]; a listener of every key ([`Layer::any`]); pointer
//! and hover events of a node ([`Interact`]); and the geometry of a mount's nodes ([`crate::Read::rect`]).
//! Input events, key layers, panels and overlays for plugin surfaces. The host applies handler effects before
//! routing the next event in the batch, so a mode change affects the next key.
//!
//! A handler runs on the UI thread, inline, as a command does. The host applies what it asks for (an edit of the
//! composer, a mode, a focus) when it returns, before it routes the next event of the same batch, so a key that
//! switches a mode is never overtaken by the key after it.
//!
//! Everything a mount makes is the mount's: its layers, its mode, its pointer capture, the keys a hold buffers and the
//! overlays it opened. When the mount ends, the host revokes all of it. A layer registered in setup
//! ([`crate::Setup::layer`]) is the plugin's and lives until the plugin leaves `active`.
//!
//! A library has all of it over the C ABI: a handler is the request [`crate::Request::Input`], the host's verbs and
//! reads are requests of the plugin's ([`crate::HostRequest::Focus`] and the rest), and it behaves as a plugin of
//! [`crate::Plugin`] does (`carrier-equal`).
//! A mount owns its layers, mode, pointer capture, held keys and overlays. Setup layers live until deactivation.
use std::rc::Rc;
@@ -21,7 +9,7 @@ use serde::{Deserialize, Serialize};
use crate::{Color, Host};
/// What a handler did with an event: took it, or passed it on down the host's order (synthesis 4.2).
/// What a handler did with an event: took it, or passed it on down the host's order.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
#[cfg_attr(not(feature = "host"), non_exhaustive)]
@@ -56,11 +44,11 @@ pub enum Event {
/// has ended ([`crate::Dialog::Surface`]).
#[cfg_attr(not(feature = "host"), non_exhaustive)]
Closed { surface: String },
/// P3: a scroll of the mount: the user moved one that asks with `user_scroll`, or a step of the plugin's own
/// landed. The answer does not matter.
/// A scroll of the mount: the user moved one that asks with `user_scroll`, or a step of the plugin's own landed.
/// The answer does not matter.
#[cfg_attr(not(feature = "host"), non_exhaustive)]
Scroll { event: crate::v2::ScrollEvent },
/// P3: the text of the mount's [`crate::v2::Node::Input`] `node` changed, after each edit. `seq` numbers the edit,
/// The text of the mount's [`crate::v2::Node::Input`] `node` changed, after each edit. `seq` numbers the edit,
/// higher for each later one, which a view's [`crate::v2::Node::Input`] `seen` names. The answer does not matter.
#[cfg_attr(not(feature = "host"), non_exhaustive)]
Change {
@@ -69,16 +57,16 @@ pub enum Event {
#[serde(default)]
seq: u64,
},
/// P3: the mount's [`crate::v2::Node::Input`] `node` was submitted: enter on one line, the submit key on many. The
/// The mount's [`crate::v2::Node::Input`] `node` was submitted: enter on one line, the submit key on many. The
/// answer does not matter.
#[cfg_attr(not(feature = "host"), non_exhaustive)]
Submit { node: String, text: String },
/// P6a: mount `mount` began (`mounted`), before its first view, or it is ending, for a surface that asks
/// Mount `mount` began (`mounted`), before its first view, or it is ending, for a surface that asks
/// ([`crate::v2::Surface::mounts`]), as a 1.x claim's `on_mount`. A new mount may begin before the one it replaces
/// ends, also with the same input: `mount` tells them apart. `slot` is a slot surface's input. The plugin hears it,
/// not the mount, at the begin as at the end, which has no mount left: what its handler starts is the plugin's and
/// outlives the mount, as a fetch of setup is the activation's ([`Host::try_fetch`]). So a read a next mount shows
/// survives the mount that asked, which may end first. The answer does not matter.
/// ends, also with the same input: `mount` tells them apart. `slot` is a slot surface's input. The plugin hears
/// it, not the mount, at the begin as at the end, which has no mount left: what its handler starts is the plugin's
/// and outlives the mount, as a fetch of setup is the activation's ([`Host::try_fetch`]). So a read a next mount
/// shows survives the mount that asked, which may end first. The answer does not matter.
#[cfg_attr(not(feature = "host"), non_exhaustive)]
Mount {
mount: crate::v2::MountId,
@@ -252,9 +240,9 @@ pub struct Bind {
/// key from its own thread.
#[serde(default, skip_serializing_if = "is_false")]
pub hold: bool,
/// P6c: the name of the user's keybind for it, such as `diff.next_hunk`: the config's keys for that name take it,
/// else the keybind's default, and `key` when the host knows no keybind of that name. [`Read::shortcut`] of the
/// name shows them.
/// The name of the user's keybind for it, such as `diff.next_hunk`: the config's keys for that name take it, else
/// the keybind's default, and `key` when the host knows no keybind of that name. [`Read::shortcut`] of the name
/// shows them.
///
/// [`Read::shortcut`]: crate::Read::shortcut
#[serde(default, skip_serializing_if = "Option::is_none")]
@@ -306,8 +294,8 @@ pub struct PanelInput {
pub fullscreen: bool,
/// The panel has the input.
pub focused: bool,
/// P6c: full screen because the session's room is too narrow to show the panel beside it; an open of the panel
/// beside the session shows it full screen still.
/// Full screen because the session's room is too narrow to show the panel beside it; an open of the panel beside
/// the session shows it full screen still.
#[serde(default, skip_serializing_if = "is_false")]
pub forced: bool,
}
@@ -317,8 +305,7 @@ pub struct PanelInput {
#[cfg_attr(not(feature = "host"), non_exhaustive)]
pub struct OpenPanel {
pub surface: String,
/// The session it shows beside, which must be on screen; without one, the session on screen (TS
/// `ui.panel.open`).
/// The session it shows beside, which must be on screen; without one, the session on screen.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub session: Option<String>,
#[serde(default, skip_serializing_if = "is_false")]
File diff suppressed because it is too large Load Diff
+5 -19
View File
@@ -1,23 +1,9 @@
//! Threads and messages of ABI 2.0 (`rich-plugins/synthesis.md` 4.2, "Threads and wakes"): a plugin's own threads
//! send messages to its [`crate::Setup::messages`] handler, which the host runs on the UI thread as the plugin's
//! `update`.
//! Plugin worker threads send messages to a bounded mailbox; the UI thread runs [`crate::Setup::messages`].
//! [`Sender::send`] returns the message if the mailbox is full or closed. [`Sender::replace`] coalesces pending
//! messages with the same nonempty key.
//!
//! The host holds one mailbox a plugin, of [`BOUND`] entries. A send never blocks and never drops a message in
//! silence: [`Sender::send`] puts the message at the end, or hands it back as [`SendError::Full`] at once, and as
//! [`SendError::Closed`] once the plugin has left `active` (it was disabled, failed, or replaced). [`Sender::replace`]
//! keeps one entry a key: the newer message takes the place of the one that waits, so a flood of progress holds one
//! entry; an empty key is no key. A thread decides what `Full` means: wait, merge, or give up.
//!
//! A message is what JSON carries: a library gets it as JSON, so on every carrier a send first writes the message as
//! JSON and reads it back as `M`, on the sending thread, and hands back one that does not come back as itself
//! ([`SendError::Unencodable`]: a `NaN`, a map with keys that are not strings, a serializer that fails). The host
//! keeps the sender's JSON text as it is, and in process the value that text reads back as, with the text's length,
//! which counts against the mailbox's bytes as the text does over the C ABI (review carbon-10): so what one carrier
//! delivers and refuses, the other does too.
//!
//! [`Spawner::spawn`] starts a thread named after the plugin, with a [`Stop`] flag that is set when the plugin leaves
//! `active`, and catches a panic on it: the host fails the plugin and says so once. A thread cannot be killed; it ends
//! when it sees the flag.
//! Messages must round-trip through JSON even in process; the encoded length counts against the mailbox budget.
//! Threads stop cooperatively through [`Stop`]. An uncaught worker panic fails the plugin.
use std::any::Any;
use std::marker::PhantomData;
@@ -1,8 +1,5 @@
//! The JSON Schema of the plugin ABI 2.0 (synthesis 4.6), generated from the Rust types without a dependency (O-132):
//! the tree a view returns and the calls of P3 here, the envelopes and replies of the C ABI in [`wire`]. Each
//! definition names every field and variant of its type, without `..`, so a field or a variant added to a type does
//! not compile until its schema has it; enum values are what serde writes. A test checks a corpus of trees against
//! both the schema and serde, and every message of the conformance transcripts against the schema.
//! JSON Schema for the plugin ABI. The macros exhaustively match Rust fields and variants so additions require
//! a schema update. [`wire`] defines the request and reply envelopes.
use serde::Serialize;
use serde_json::{Value, json};
@@ -569,8 +566,8 @@ mod tests {
}
/// Whether `value` conforms to `schema`, for the keywords [`schema`] and the OpenAPI document write, but the
/// patterns of the OpenAPI document's strings. A schema with nothing to check, such as an annotation alone, panics:
/// a binding could not check it either (bigboi's re-review). `{}` takes anything.
/// patterns of the OpenAPI document's strings. A schema with nothing to check, such as an annotation alone,
/// panics: a binding could not check it either. `{}` takes anything.
fn conforms(value: &Value, schema: &Value, defs: &Value) -> bool {
if *schema == json!({}) {
return true;
@@ -693,10 +690,6 @@ mod tests {
read
}
// Expected (big-boi 14, carbon-13): every message of the golden transcripts, as the reference and the C library
// wrote them, conforms to the schema: each request to its side's envelope, each answer of status OK to the
// definition `x-messages` names for its request's type, and each draw's bytes to the list's format. A request type
// `x-messages` does not name is answered with null.
#[test]
fn the_schema_takes_every_message_of_the_transcripts() {
let schema = shipped();
@@ -755,15 +748,10 @@ mod tests {
}
}
assert!(requests > 100 && replies > 100, "{requests} requests and {replies} replies checked");
// A completed call, whose output the host keeps from the claim's view (bigboi's final pass).
// A completed call, whose output the host keeps from the claim's view.
assert!(completed > 0, "no completed tool claim in the transcripts");
}
// Expected (bigboi's re-review, finding 14): the shipped schema resolves without Rust. Every reference it makes
// names a definition of its own or a component of the HTTP API's OpenAPI document, whose key in Pascal case is the
// generated Rust type; none is an annotation alone, which the validator refuses. Against the shipped file, a
// `describe` without a nonempty ID is refused as `define` refuses it, and an API value of the wrong shape is refused
// through its reference.
#[test]
fn the_shipped_schema_resolves_its_references_and_refuses_what_the_host_refuses() {
let schema = shipped();
@@ -813,7 +801,7 @@ mod tests {
assert!(conforms(&Value::Null, session, defs));
assert!(!conforms(&json!({ "info": 1, "status": "idle" }), session, defs));
assert!(!conforms(&json!({ "info": {}, "status": "idle" }), session, defs), "an empty Session.Info");
// A request ID is never 0, in what `fetch` answers and in a reply (bigboi's last pass).
// A request ID is never 0, in what `fetch` answers and in a reply.
let fetched = &schema["x-messages"]["host"]["fetch"];
assert!(conforms(&json!(1), fetched, defs) && !conforms(&json!(0), fetched, defs));
let reply = |id| {
@@ -822,9 +810,6 @@ mod tests {
assert!(conforms(&reply(1), &defs["Request"], defs) && !conforms(&reply(0), &defs["Request"], defs));
}
// Expected (big-boi 14): the envelopes take and refuse what serde takes and refuses: an unknown request type, a
// field left out that is required, a newtype variant's fields beside its tag, and a mount left out of a surface's
// input, which a mount's begin and end do.
#[test]
fn the_envelopes_take_what_serde_takes() {
for (value, taken) in [
@@ -873,9 +858,6 @@ mod tests {
));
}
// Expected (O-132): what serde writes for every variant, with every field set, conforms to its definition, and a
// corpus of trees is taken or refused alike by the schema and by serde: a required field left out, an unknown
// variant, a number out of range, a color in either case.
#[test]
fn the_schema_takes_what_serde_takes() {
let span = Span {
@@ -1039,7 +1021,6 @@ mod tests {
assert!(!agree::<Frame>("Frame", frame(json!("drawn"), json!({ "secs": 0, "nanos": 0 }))));
assert!(!agree::<Frame>("Frame", frame(json!("first"), json!({ "secs": 0 }))));
assert!(!agree::<Frame>("Frame", frame(json!("first"), json!({ "secs": -1, "nanos": 0 }))));
// The calls of P3, every variant with every field set.
let anchor = AnchorAt { id: "d#1".into(), owner: "d".into(), index: 1, variant: "v".into(), row: -3 };
let verbs = [
Scroll::To { node: "n".into(), align: ScrollAlign::Nearest { inset: 2 } },
@@ -1,7 +1,4 @@
//! The schema of the envelopes and replies of the C ABI (big-boi 14, carbon-13): what `describe` and `create` answer,
//! the requests each side sends and what each answers, and the binary list a draw answers. As in the parent, each
//! definition names every field and variant of its type, so a field or a variant added to one does not compile until
//! its schema has it.
//! Wire schemas for plugin metadata, manifests, requests, replies and binary draw lists.
use super::*;
use crate::claim::{self, FencePart, ToolPart};
@@ -30,7 +27,6 @@ type ScreenEdge = interact::Edge;
type Overlay = interact::Overlay;
type OpenPanel = interact::OpenPanel;
/// The definitions of the envelopes and replies, beside the parent's of the tree and the calls of P3.
pub(super) fn definitions() -> Vec<(&'static str, Value)> {
vec![
("Metadata", {
@@ -569,7 +565,7 @@ pub(super) fn definitions() -> Vec<(&'static str, Value)> {
let _ = |value: &RequestId| {
let RequestId(_) = value;
};
// 0 names no request (bigboi's last pass).
// 0 names no request.
described(
json!({ "type": "integer", "minimum": 1, "maximum": u64::MAX }),
"What a `fetch` or a `foreground` the host takes answers, which its one reply names; never 0, which \
@@ -732,7 +728,7 @@ pub(super) fn messages() -> Value {
("draw", reference("DrawList")),
("layout", reference("LayoutReply")),
("input", reference("Handled")),
// A command that declines the key that ran it answers "pass" (contract ergonomics 2.5).
// A command that declines the key that ran it answers "pass".
("command", json!({ "enum": [null, "pass"] })),
("search", array(string())),
("*", json!({ "type": "null" })),
@@ -804,7 +800,7 @@ pub(super) fn messages() -> Value {
/// A claim's tool call: the HTTP API's assistant tool part, but that a completed call's `content`, what it returned,
/// is empty, since a `part-output` source names it and the host reads it (`claim::ToolPart`); an error's is left out,
/// and metadata past 4096 bytes of JSON is empty. The HTTP API requires a completed call's content, so its own
/// definition would refuse every completed claim (bigboi's final pass).
/// definition would refuse every completed claim.
fn claim_tool() -> Value {
let tool = |pointer: &str| api(&format!("Session.Message.Assistant.Tool/properties/{pointer}"));
let completed = json!({
+7 -31
View File
@@ -1,5 +1,4 @@
//! Tasks: a handler that waits for a dialog's answer or a reply in a straight line, as TS awaits them
//! (`design/contract-ergonomics.md` 2.1).
//! Tasks: a handler that waits for a dialog's answer or a reply in a straight line, as TS awaits them.
//!
//! [`crate::Setup::tasks`] gives the plugin a [`Tasks`] handle, and a handler starts a task with it:
//!
@@ -117,10 +116,10 @@ impl Tasks {
}
}
/// How many answer commands the dialogs take turns on. A dialog takes a command no dialog holds, and holds it until its
/// answer or its close runs. The host runs a dialog's answer before its close, so no answer can still come for a
/// command once it is free: an answer reaches the one dialog that holds its command (big-boi `acf-1`). A dialog that
/// finds every command held, as more dialogs wait unclosed than that, answers `None` at once.
/// How many answer commands the dialogs take turns on. A dialog takes a command no dialog holds, and holds it until
/// its answer or its close runs. The host runs a dialog's answer before its close, so no answer can still come for a
/// command once it is free: an answer reaches the one dialog that holds its command. A dialog that finds every command
/// held, as more dialogs wait unclosed than that, answers `None` at once.
pub const ANSWERS: usize = 64;
/// The most [`Cx::blocking`] threads a plugin runs at once.
@@ -654,9 +653,8 @@ impl Shared {
}
/// Runs `deliver` and polls the tasks that are ready until none is, with `host` as their host, each under its own
/// owner ([`Host::set_owner`]): what a task asks for is its starting call's owner's, whichever call goes on with it
/// (carbon `tm2-1`). Inside a poll (a task that spawns), it only delivers: the poll that runs goes on with what is
/// ready.
/// owner ([`Host::set_owner`]): what a task asks for is its starting call's owner's, whichever call goes on with
/// it. Inside a poll (a task that spawns), it only delivers: the poll that runs goes on with what is ready.
fn enter(&self, host: &dyn Host, deliver: impl FnOnce(&Self)) {
if self.host.get().is_some() {
return deliver(self);
@@ -1192,9 +1190,6 @@ mod tests {
assert!(registered.manifest().wake);
}
// Expected (carbon ac-2): a task waiting on a dialog that another task's dialog replaces does not go on in that
// task's call, whose host may be a mount's: it goes on in its close's call, so what it asks for next is the
// activation's, not the mount's.
#[test]
fn a_replaced_dialogs_task_goes_on_in_its_close_not_in_the_call_that_replaced_it() {
let (registered, tasks, _) = plugin();
@@ -1209,9 +1204,6 @@ mod tests {
assert_eq!((mount.fetches.get(), closing.fetches.get()), (0, 1));
}
// Expected (carbon tm2-1): a task keeps the owner of the call that started it. A mount's task resumed by a reply,
// which is the activation's call, asks for its next fetch and its next sleep under the mount, as an `every` whose
// tick awaits a fetch does; so they end with the mount.
#[test]
fn a_task_asks_under_the_owner_of_the_call_that_started_it() {
let (registered, tasks, _) = plugin();
@@ -1229,8 +1221,6 @@ mod tests {
assert_eq!(activation.forced.get(), None, "the call did not get its own owner back");
}
// Expected (carbon tm2-1): a task of the activation's that goes on in a mount's call (here another task wakes it)
// asks under the activation, not the mount, so the mount's close cancels none of its work.
#[test]
fn a_task_woken_in_a_mounts_call_keeps_the_activations_owner() {
let (_registered, tasks, _) = plugin();
@@ -1265,8 +1255,6 @@ mod tests {
assert_eq!(mount.forced.get(), None);
}
// Expected (carbon tm2-3): a sleep dropped before its time, as the loser of a race, lets its timer go, so it holds
// no place among the plugin's timers; one that slept its time lets nothing go.
#[test]
fn a_dropped_sleep_lets_its_timer_go() {
let (registered, tasks, _) = plugin();
@@ -1315,8 +1303,6 @@ mod tests {
}
}
// Expected (carbon ar-2): a failed plugin's abandon drops its tasks, each inside a catch: destructors that use
// their `Cx` with no host fail alone, never unwind into the host, and nothing drops later outside a catch.
#[test]
fn abandoning_drops_the_tasks_under_a_catch() {
let (mut registered, tasks, _) = plugin();
@@ -1329,7 +1315,6 @@ mod tests {
assert!(log.borrow().is_empty());
}
// Expected (carbon ar-2): registrations dropped with neither a dispose nor an abandon drop their tasks the same way.
#[test]
fn dropping_the_registrations_drops_the_tasks_under_a_catch() {
let (registered, tasks, _) = plugin();
@@ -1339,7 +1324,6 @@ mod tests {
assert!(log.borrow().is_empty());
}
// Expected (carbon ar-3): the closure that builds a task runs with the host lent, as the task does.
#[test]
fn a_task_is_built_with_the_host_lent() {
let (_registered, tasks, _) = plugin();
@@ -1351,7 +1335,6 @@ mod tests {
assert_eq!(*host.toasts.borrow(), ["built"]);
}
// Expected (carbon ar-3): a wait dropped before its reply leaves no entry behind; a reply to it reaches nobody.
#[test]
fn a_dropped_wait_leaves_no_entry() {
let (registered, tasks, _) = plugin();
@@ -1367,8 +1350,6 @@ mod tests {
assert_eq!(replies(), 0);
}
// Expected (carbon ar-3): at most MAX_THREADS blocking jobs run at once a plugin; the others wait their turn, and
// every one gives its value.
#[test]
fn blocking_runs_at_most_its_threads_at_once() {
let (registered, tasks, _) = plugin();
@@ -1401,8 +1382,6 @@ mod tests {
assert!(most <= MAX_THREADS, "{most} blocking jobs ran at once");
}
// Expected (typed-client): a typed call sends the fetch its builder describes, and its reply decodes as the
// operation's output, out of `data` where the operation answers in `data`; a reply of another shape is the error.
#[test]
fn a_call_sends_its_request_and_decodes_its_output() {
use crate::types::{SessionID, SessionInboxListInput, SessionListInput};
@@ -1431,8 +1410,6 @@ mod tests {
assert!(logged.starts_with("Ok(0) Err(\"MalformedResponse: invalid type"), "{logged}");
}
// Expected (typed-client): a call the host's fetch cannot carry fails at once and sends nothing: a header, or a
// stream of events.
#[test]
fn a_call_the_fetch_cannot_carry_fails_at_once() {
use crate::types::{EventSubscribeInput, SessionID};
@@ -1458,7 +1435,6 @@ mod tests {
drop(registered);
}
// Expected (typed-client): `call_on_thread` asks for the reply's bytes and decodes them off the UI thread, `data` too.
#[test]
fn a_call_on_a_thread_decodes_the_bytes_there() {
use crate::types::{SessionID, SessionInboxListInput};
+44 -62
View File
@@ -1,15 +1,6 @@
//! Contract 2.0 of the rich-plugin design (`rich-plugins/synthesis.md` 4.1 to 4.6), as phase P1 builds it: a keyed
//! tree of host-owned widgets per surface, which the host reconciles by key ([`Node`], [`Node::Keep`]), mounts with
//! generations ([`MountId`]), content by handle ([`Source`]), a host-scrolled [`Node::Scroll`], and the palette in a
//! surface's input ([`SurfaceInput`]). P5 adds [`Node::Canvas`], drawn by a retained display list
//! ([`crate::canvas`]) that [`Surface::draw`] returns.
//!
//! P1 runs it on the linked path only: a built-in registers a surface with [`crate::Setup::surface`] and the host
//! calls its view with Rust values. The C ABI of 2.0 is P4's; until then a surface of an external plugin is never
//! mounted. The leaf types (colors, spans, layout, clicks) are those of ABI 1.x.
//!
//! The schema of these types is generated from them (`bun script/gen/plugin-schema.ts`, which runs the `schema`
//! example) into `crates/plugin-abi/schema/v2.json`.
//! Keyed surface trees for the plugin ABI. Each [`MountId`] identifies one generation of a mounted surface.
//! [`Node::Keep`] reuses a subtree from the last accepted view. A [`Node::Canvas`] replays the display list
//! returned by [`Surface::draw`].
use std::any::Any;
use std::collections::{BTreeMap, HashMap, HashSet};
@@ -69,20 +60,20 @@ pub enum Node {
/// Whether what does not fit in the box draws outside it.
#[serde(default, skip_serializing_if = "is_visible")]
overflow: Overflow,
/// P3: pinned to this edge of its scroll while its parent is in view, never past the parent's end.
/// Pinned to this edge of its scroll while its parent is in view, never past the parent's end.
#[serde(default, skip_serializing_if = "Option::is_none")]
sticky: Option<geometry::Edge>,
/// P3: one of a group of its scroll's anchors; it needs an id.
/// One of a group of its scroll's anchors; it needs an id.
#[serde(default, skip_serializing_if = "Option::is_none")]
anchor: Option<Anchor>,
/// P3: a row whose first child the user resizes by dragging; it needs an id, which keeps the width.
/// A row whose first child the user resizes by dragging; it needs an id, which keeps the width.
#[serde(default, skip_serializing_if = "Option::is_none")]
split: Option<Split>,
/// Focus, pointer and hover ([`crate::interact`]); its fields sit beside the box's own.
#[serde(default, flatten)]
interact: Interact,
/// P6a: `false` hides the box and all it holds, which then take no room, not even a gap (TS `visible`). A slot
/// surface whose root box is hidden shows nothing in its slot, as a 1.x claim's `Render::Hide`.
/// `false` hides the box and all it holds, which then take no room, not even a gap. A slot surface whose root
/// box is hidden shows nothing in its slot, as a 1.x claim's `Render::Hide`.
#[serde(default = "yes", skip_serializing_if = "is_true")]
visible: bool,
},
@@ -144,19 +135,19 @@ pub enum Node {
layout: Layout,
#[serde(default)]
children: Vec<Node>,
/// P3: `layout` is called when the top anchor of this group changes.
/// `layout` is called when the top anchor of this group changes.
#[serde(default, skip_serializing_if = "Option::is_none")]
notify_top: Option<String>,
/// P3: the surface hears [`ScrollEvent::UserScroll`] when the user moves it.
/// The surface hears [`ScrollEvent::UserScroll`] when the user moves it.
#[serde(default, skip_serializing_if = "is_false")]
user_scroll: bool,
/// A scrollbar shows while its content overflows (TS's `<scrollbox>`).
/// A scrollbar shows while its content overflows.
#[serde(default, skip_serializing_if = "is_false")]
scrollbar: bool,
},
/// A patch in the host's diff view: its own highlighting, colors and line numbers. An added file over 3,000
/// lines mounts its chunks near the view. 2.0 (P6c): `#[non_exhaustive]`: build it with [`Node::diff`] and the
/// `with_` setters, so a field a later 2.x adds is no break of a plugin's source.
/// A patch in the host's diff view: its own highlighting, colors and line numbers. An added file over 3,000 lines
/// mounts its chunks near the view. `#[non_exhaustive]`: build it with [`Node::diff`] and the `with_` setters, so
/// a field a later 2.x adds is no break of a plugin's source.
#[non_exhaustive]
Diff {
#[serde(default, skip_serializing_if = "Option::is_none")]
@@ -167,17 +158,17 @@ pub enum Node {
/// The language to highlight as, such as `rust`.
#[serde(default, skip_serializing_if = "Option::is_none")]
filetype: Option<String>,
/// P3: the first row of each hunk is anchor `{id}#{index}` of this group; it needs an id.
/// The first row of each hunk is anchor `{id}#{index}` of this group; it needs an id.
#[serde(default, skip_serializing_if = "Option::is_none")]
hunks: Option<String>,
/// P6c: how its lines wrap; at words by default.
/// How its lines wrap; at words by default.
#[serde(default, skip_serializing_if = "is_word")]
wrap: Wrap,
/// P6c: cells inside its left and right edges.
/// Cells inside its left and right edges.
#[serde(default, skip_serializing_if = "is_zero")]
padding: u16,
},
/// P3: a text field whose text and cursor are the host's. With an id, the surface's handler hears
/// A text field whose text and cursor are the host's. With an id, the surface's handler hears
/// [`crate::interact::Event::Change`] with the text after each edit, and [`crate::interact::Event::Submit`] on
/// enter (one line) or the submit key, and, on a host with [`crate::FOCUS_INPUT`], [`crate::Host::focus`] gives it
/// the focus, as a click does. A changed `value` replaces the text, unless it is the echo of an edit (`seen`).
@@ -201,7 +192,7 @@ pub enum Node {
#[serde(default, skip_serializing_if = "Option::is_none")]
seen: Option<u64>,
},
/// P3: a list the host scrolls and windows: only the items near the view have widgets. An item is the unit of
/// A list the host scrolls and windows: only the items near the view have widgets. An item is the unit of
/// reconcile: a [`Node::Keep`] in a list names one of its items or a node inside the same item.
#[cfg_attr(not(feature = "host"), non_exhaustive)]
List {
@@ -221,7 +212,7 @@ pub enum Node {
#[serde(default, skip_serializing_if = "is_false")]
user_scroll: bool,
},
/// P3: source code in the host's code view, highlighted as `filetype` with the host's grammars and theme.
/// Source code in the host's code view, highlighted as `filetype` with the host's grammars and theme.
#[cfg_attr(not(feature = "host"), non_exhaustive)]
Code {
#[serde(default, skip_serializing_if = "Option::is_none")]
@@ -235,7 +226,7 @@ pub enum Node {
#[serde(default, skip_serializing_if = "is_default_layout")]
layout: Layout,
},
/// P3: an image from content bytes (PNG, JPEG, WebP or GIF), in the host's image view.
/// An image from content bytes (PNG, JPEG, WebP or GIF), in the host's image view.
#[cfg_attr(not(feature = "host"), non_exhaustive)]
Image {
#[serde(default, skip_serializing_if = "Option::is_none")]
@@ -250,12 +241,12 @@ pub enum Node {
/// hold in the last accepted tree is a contract error: the host refuses the tree whole.
#[cfg_attr(not(feature = "host"), non_exhaustive)]
Keep { key: String },
/// Cells the plugin draws itself (P5): its surface's [`Surface::draw`] returns a display list
/// ([`crate::canvas`]), which the host keeps under the canvas's id while the id stays in the mount and replays on
/// every frame it paints. The host asks for a list as it paints the canvas, at the canvas's size in that frame: when
/// it first shows, when its size or `version` changed, and once a frame while `animate` is set; never while it is
/// hidden, out of view or of no size, and what it missed meanwhile it asks for in the frame that shows it. Its
/// cells cannot be selected or copied. A canvas must have an id.
/// Cells the plugin draws itself: its surface's [`Surface::draw`] returns a display list ([`crate::canvas`]),
/// which the host keeps under the canvas's id while the id stays in the mount and replays on every frame it
/// paints. The host asks for a list as it paints the canvas, at the canvas's size in that frame: when it first
/// shows, when its size or `version` changed, and once a frame while `animate` is set; never while it is hidden,
/// out of view or of no size, and what it missed meanwhile it asks for in the frame that shows it. Its cells
/// cannot be selected or copied. A canvas must have an id.
#[cfg_attr(not(feature = "host"), non_exhaustive)]
Canvas {
#[serde(default, skip_serializing_if = "Option::is_none")]
@@ -284,7 +275,7 @@ pub enum Node {
layout: Layout,
},
/// A kind a later 2.x minor adds, which only the SDK's own tests and its `next` feature have: what an author's
/// fallback for an older host is checked against (big-boi 13). No host knows it.
/// fallback for an older host is checked against. No host knows it.
#[cfg(any(test, feature = "next"))]
#[doc(hidden)]
Later {
@@ -391,15 +382,15 @@ pub struct SurfaceInput {
/// A panel surface's presentation; `None` elsewhere. A change of it calls the view again.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub panel: Option<PanelInput>,
/// P6a: what changed since the mount's last view, as a 1.x render hears it: `all` on its first view and on a
/// whole tree ([`Self::full`]), the change batch that called it, `local` or `size` for a change of the host's own
/// state or of the room, and `woken` after the plugin's own handlers, a wake, or a `layout` that asked to draw
/// again. A view that reads the host's state may answer [`Node::Keep`] of its last tree's root when nothing it read
/// changed: the host then keeps the mount as it is, with no work. A claim's view always hears `all`.
/// What changed since the mount's last view, including `all` on its first view and on a whole tree
/// ([`Self::full`]), the change batch that called it, `local` or `size` for a change of the host's own state or of
/// the room, and `woken` after the plugin's own handlers, a wake, or a `layout` that asked to draw again. A view
/// that reads the host's state may answer [`Node::Keep`] of its last tree's root when nothing it read changed: the
/// host then keeps the mount as it is, with no work. A claim's view always hears `all`.
#[serde(default, skip_serializing_if = "is_unchanged")]
pub changed: Changed,
/// P6a: a slot surface's input, as a 1.x claim gets it (the session, the prompt's state); `None` elsewhere. Its
/// size is [`Self::width`] and [`Self::height`].
/// A slot surface's input, including the session and the prompt state; `None` elsewhere. Its size is
/// [`Self::width`] and [`Self::height`].
#[serde(default, skip_serializing_if = "Option::is_none")]
pub slot: Option<SlotInput>,
}
@@ -450,8 +441,8 @@ pub struct MountId {
pub generation: u64,
}
/// Where a surface shows: a route of the plugin, or a slot claim (P1); a docked panel or an overlay, which the plugin
/// opens with [`crate::Host::open_panel`] and [`crate::Host::overlay`] (P2).
/// Where a surface shows: a route of the plugin, or a slot claim; a docked panel or an overlay, which the plugin opens
/// with [`crate::Host::open_panel`] and [`crate::Host::overlay`].
#[derive(Clone, Debug, PartialEq, Eq)]
#[cfg_attr(not(feature = "host"), non_exhaustive)]
pub enum Place {
@@ -479,14 +470,14 @@ pub struct Surface {
pub view: ViewFn,
/// Draws the surface's canvases ([`Node::Canvas`]); without it a canvas shows nothing.
pub draw: Option<DrawFn>,
/// P3: called after geometry is final, in a frame where something in `notify` changed.
/// Called after geometry is final, in a frame where something in `notify` changed.
pub layout: Option<LayoutFn>,
pub notify: Vec<Notify>,
/// What its events come to: its layers' keys, its nodes' pointer and hover, an overlay's close.
pub handler: Option<HandlerFn>,
/// The key layers each mount of it registers, which end with the mount.
pub layers: Vec<Layer>,
/// P6a: its handler hears [`crate::interact::Event::Mount`] as each mount begins and ends.
/// Its handler hears [`crate::interact::Event::Mount`] as each mount begins and ends.
pub mounts: bool,
}
@@ -584,10 +575,10 @@ impl<'a> View<'a> {
(self.release)(handle)
}
/// `node`, when the host serving the plugin has its kind, else what `fallback` builds (synthesis 4.6, big-boi 13):
/// a kind a later 2.x minor or an optional feature adds ([`Node::since`], [`Node::feature`]) is lowered here, by
/// the author, so the tree the SDK encodes for an older host holds no kind that host does not know. A tree that
/// still holds one is refused by the SDK before it crosses ([`unknown_to`], [`unknown_feature`]).
/// `node`, when the host serving the plugin has its kind, else what `fallback` builds: a kind a later 2.x minor or
/// an optional feature adds ([`Node::since`], [`Node::feature`]) is lowered here, by the author, so the tree the
/// SDK encodes for an older host holds no kind that host does not know. A tree that still holds one is refused by
/// the SDK before it crosses ([`unknown_to`], [`unknown_feature`]).
pub fn or(&mut self, node: Node, fallback: impl FnOnce(&mut Self) -> Node) -> Node {
let abi = self.read.abi();
let known = abi.has_minor(node.since()) && node.feature().is_none_or(|feature| abi.has_feature(feature));
@@ -721,9 +712,7 @@ impl Memo {
/// value whose [`Node::Keep`] it holds, with the values inside it; the rest goes. The host calls it once it
/// accepted the view's tree.
pub fn finish(&mut self, accepted: &[Node]) {
// A view that answered a keep of its whole tree (P6a: it heard nothing it shows change, whether or not its memos
// ran) leaves the table as it was: every subtree its values built is still in the tree, and none it built now
// is (review carbon-2).
// Keeping the whole root preserves all previously accepted memo values.
if let [Node::Keep { .. }] = accepted {
self.staged.clear();
self.hits.clear();
@@ -1189,9 +1178,6 @@ mod tests {
node
}
// Expected (`keep-full`): memo remembers a value only for the node the accepted tree holds: a candidate the view
// built and left out for another node with its id, a slot, which carries no id, and a duplicate key all build
// again. A memo inside a kept one stays with it, so after the outer value changes an unchanged inner one keeps.
#[test]
fn memo_remembers_only_what_the_host_accepted() {
let text = |text: &str| Node::text(vec![Span::new(text)]);
@@ -1234,8 +1220,6 @@ mod tests {
assert_eq!(children[0], Node::Keep { key: "commit".into() }, "the inner memo was dropped with its kept parent");
}
// Expected: memo builds on first use and keeps while the value is equal; a changed value, a full input, or a key
// the view before did not use builds again, with the key as the subtree's id.
#[test]
fn memo_keeps_an_equal_value_and_builds_otherwise() {
let mut memo = Memo::default();
@@ -1252,8 +1236,6 @@ mod tests {
assert!(matches!(view(&mut memo, false, card(2)), Node::Text { .. }));
}
// Expected (big-boi's review of P6c): a view that keeps its whole tree with a literal keep of its root keeps every
// value, so the next view keeps the cards that did not change.
#[test]
fn a_literal_keep_of_the_root_keeps_every_value() {
let mut memo = Memo::default();
@@ -1,19 +1,6 @@
//! Phase P3 of contract 2.0 (synthesis 3.5, 4.2, 4.4): scroll behaviors as node data, scroll verbs, geometry reads,
//! the `layout` call after the solve, and the published `Viewport::Transcript`.
//!
//! - **Behaviors** are node data the host resolves after each solve, with no plugin call: [`Edge`] on a box pins it
//! to its scroll's edge while its parent is in view (CSS sticky); [`Anchor`] makes a node one of a named group a
//! [`Scroll::Step`] or [`Read::top_anchor`](crate::Read::top_anchor) walks; a [`super::Node::Diff`] with `hunks`
//! publishes the first row of each hunk as anchor `{id}#{index}`.
//! - **Verbs** ([`Scroll`]) are effects of a handler: they apply when the call returns. [`Scroll::To`] resolves after
//! the solve of the frame, against its final geometry, again in each round until it moves nothing; the others
//! resolve at once, against the last settled frame. A [`Scroll::Step`] reports where it landed as
//! [`ScrollEvent::Landed`] before the next event is routed.
//! - **Reads** ([`ScrollState`], [`AnchorAt`], [`TranscriptView`]) answer from the last settled frame and the current
//! offset, so a handler after a wheel step reads what is on screen.
//! - **`layout`** ([`super::Surface::layout`]) runs after geometry is final, only in a frame where something the
//! surface named ([`Notify`]) changed. It returns paint-time properties ([`Paint`]) or asks for a view again; it
//! cannot move anything, so it never starts another solve.
//! Scroll commands and geometry for plugin surfaces. Reads use the last settled frame and the current scroll
//! offset. [`Scroll::To`] resolves against final layout; [`Scroll::Step`] reports [`ScrollEvent::Landed`] before
//! the next input event. A layout callback can request a repaint or another view, but cannot move a widget.
use serde::{Deserialize, Serialize};
@@ -228,8 +215,8 @@ pub struct Top {
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
#[cfg_attr(not(feature = "host"), non_exhaustive)]
pub struct Geometry {
/// The mount this call is for (big-boi 4): two mounts of one surface, with the same tree and the same rects, tell
/// their models apart by it. A 2.0 host names it in every call.
/// The mount this call is for: two mounts of one surface, with the same tree and the same rects, tell their models
/// apart by it. A 2.0 host names it in every call.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub mount: Option<MountId>,
/// The rects of the nodes it named.
@@ -1,7 +1,7 @@
//! An author's plugin, pinned to the source of the 2.0 SDK (big-boi 14, carbon-4). `tests/sdk.rs` builds it as an
//! outside crate against this SDK, and against what a later 2.x adds (the SDK's `next` feature: a node kind and an
//! event kind more). Do not edit it to follow the SDK: a change this crate would need is a break of the 2.x source
//! promise (`README.md`, "Source compatibility within 2.x").
//! An author's plugin, pinned to the source of the 2.0 SDK. `tests/sdk.rs` builds it as an outside crate against this
//! SDK, and against what a later 2.x adds (the SDK's `next` feature: a node kind and an event kind more). Do not edit
//! it to follow the SDK: a change this crate would need is a break of the 2.x source promise (`README.md`, "Source
//! compatibility within 2.x").
//!
//! A route whose every mount keeps a pad of its own. A key counts in the mount it is pressed in, an edit keeps that
//! mount's draft, the layout tells the mount its width, a note is content the view gives the host and releases when
+2 -10
View File
@@ -1,5 +1,5 @@
//! The public SDK alone (O-67): the quick start and a plugin author's fixture under `crates/plugin/examples` build on
//! this crate and pull in no OpenTUI and no crate of the TUI.
//! The public SDK alone: the quick start and a plugin author's fixture under `crates/plugin/examples` build on this
//! crate and pull in no OpenTUI and no crate of the TUI.
use std::path::Path;
use std::process::Command;
@@ -39,9 +39,6 @@ fn plugins_on_the_sdk_pull_in_no_tui() {
}
}
// Expected (big-boi 14, carbon-4): the pinned author crate, written against the 2.0 SDK, builds as a crate outside the
// workspace on this SDK, and on what a later 2.x adds (the `next` feature: a node kind and an event kind more), so the
// 2.x source promise holds for a plugin with two mounts, a key, a layout, released content, a worker and a wildcard.
#[test]
fn a_pinned_plugin_builds_through_the_next_sdk() {
let crate_dir = Path::new(env!("CARGO_MANIFEST_DIR"));
@@ -54,8 +51,6 @@ fn a_pinned_plugin_builds_through_the_next_sdk() {
}
}
// Expected: the README's quick start shows `examples/hello` as it is, so what an author copies is what the tests build
// and load (`the_quick_start_plugin_loads_from_a_plugins_directory_and_runs` in `opencode-plugin`).
#[test]
fn the_readme_quick_start_is_the_hello_example() {
let crate_dir = Path::new(env!("CARGO_MANIFEST_DIR"));
@@ -74,9 +69,6 @@ fn the_readme_quick_start_is_the_hello_example() {
}
}
// Expected: the guide (`docs/plugins.md`) shows its examples as the files the tests build, load and run: the quick
// start in Rust, in Luau (with its manifest) and in TypeScript, and the task module's own example, which the doc tests
// compile. The guide's Luau wait is run from the guide itself (`the_guides_luau_wait_runs_as_written`).
#[test]
fn the_guide_shows_its_examples_as_they_are() {
let crate_dir = Path::new(env!("CARGO_MANIFEST_DIR"));