pi-oxidized 0.1.1

package/crates/pi-ext/src/protocol.rs

@@ -0,0 +1,1880 @@
+//! Versioned extension-host / pi-tui protocol (UTF-8 JSONL frames).
+//!
+//! One frame is a single JSON object on one line, at most [`MAX_FRAME_BYTES`]
+//! UTF-8 bytes (excluding the trailing newline):
+//!
+//! ```json
+//! {"id":1,"kind":"req","method":"hello","payload":{"protocolVersion":1,"compatibilityVersion":"0.80.10"}}
+//! ```
+//!
+//! Rust is the authoritative validation boundary. TypeScript mirrors live in
+//! `packages/pi-tui-protocol` and share golden JSONL fixtures under that
+//! package's tests.
+
+use std::collections::BTreeMap;
+use std::fmt;
+use std::str;
+
+use serde::{Deserialize, Serialize};
+use serde_json::{Map, Value};
+use thiserror::Error;
+/// Host-control method that synchronizes validated extension flag values.
+pub const FLAGS_SET_METHOD: &str = Method::FlagsSet.as_str();
+
+/// Host-control method that dispatches one effective extension shortcut.
+pub const SHORTCUT_EXECUTE_METHOD: &str = Method::ShortcutExecute.as_str();
+
+// Local wire copies of overlay layout value types (camelCase). Kept here so
+// the protocol module does not depend on pi-tui compile health for validation.
+// Field names match `pi_tui::layout::{SizeValue, OverlayAnchor, OverlayMargin, OverlaySpec}`.
+
+/// Absolute cells or percent of a reference dimension.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum SizeValue {
+    /// Absolute size in terminal cells.
+    Cells(u16),
+    /// Percentage of the reference size (`0..=100`).
+    Percent(u8),
+}
+
+impl Serialize for SizeValue {
+    fn serialize<S: serde::Serializer>(
+        &self,
+        serializer: S,
+    ) -> std::result::Result<S::Ok, S::Error> {
+        match *self {
+            Self::Cells(n) => serializer.serialize_u16(n),
+            Self::Percent(n) => serializer.serialize_str(&format!("{n}%")),
+        }
+    }
+}
+
+impl<'de> Deserialize<'de> for SizeValue {
+    fn deserialize<D: serde::Deserializer<'de>>(
+        deserializer: D,
+    ) -> std::result::Result<Self, D::Error> {
+        struct Visitor;
+        impl serde::de::Visitor<'_> for Visitor {
+            type Value = SizeValue;
+            fn expecting(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+                f.write_str("a cell count number or a percent string like \"50%\"")
+            }
+            fn visit_u64<E: serde::de::Error>(self, v: u64) -> std::result::Result<Self::Value, E> {
+                u16::try_from(v)
+                    .map(SizeValue::Cells)
+                    .map_err(|_| E::custom("size value exceeds u16"))
+            }
+            fn visit_i64<E: serde::de::Error>(self, v: i64) -> std::result::Result<Self::Value, E> {
+                if v < 0 {
+                    return Err(E::custom("size value must be non-negative"));
+                }
+                self.visit_u64(v.cast_unsigned())
+            }
+            fn visit_str<E: serde::de::Error>(
+                self,
+                v: &str,
+            ) -> std::result::Result<Self::Value, E> {
+                let stripped = v
+                    .strip_suffix('%')
+                    .ok_or_else(|| E::custom(format!("invalid percent size: {v}")))?;
+                if stripped.is_empty() || !stripped.bytes().all(|b| b.is_ascii_digit()) {
+                    return Err(E::custom(format!("invalid percent size: {v}")));
+                }
+                let n: u32 = stripped.parse().map_err(E::custom)?;
+                Ok(SizeValue::Percent(
+                    u8::try_from(n.min(100)).map_err(E::custom)?,
+                ))
+            }
+        }
+        deserializer.deserialize_any(Visitor)
+    }
+}
+
+/// Anchor point for overlay placement.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum OverlayAnchor {
+    /// Center of the available area.
+    #[default]
+    Center,
+    /// Top-left corner.
+    TopLeft,
+    /// Top-right corner.
+    TopRight,
+    /// Bottom-left corner.
+    BottomLeft,
+    /// Bottom-right corner.
+    BottomRight,
+    /// Top edge, horizontally centered.
+    TopCenter,
+    /// Bottom edge, horizontally centered.
+    BottomCenter,
+    /// Left edge, vertically centered.
+    LeftCenter,
+    /// Right edge, vertically centered.
+    RightCenter,
+}
+
+/// Per-side overlay margin from terminal edges.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase", default)]
+pub struct OverlayMargin {
+    /// Top margin in rows.
+    pub top: u16,
+    /// Right margin in columns.
+    pub right: u16,
+    /// Bottom margin in rows.
+    pub bottom: u16,
+    /// Left margin in columns.
+    pub left: u16,
+}
+/// Wire margin accepts either a uniform scalar or per-side object.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(untagged)]
+pub enum OverlayMarginWire {
+    /// Uniform margin applied to all four sides.
+    Uniform(u16),
+    /// Individually specified sides.
+    Sides(OverlayMargin),
+}
+
+/// Serializable overlay layout specification for `uiSlot.overlayOptions`.
+#[derive(Debug, Clone, PartialEq, Eq, Default, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase", default)]
+pub struct OverlaySpec {
+    /// Width in columns, or percentage of terminal width.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub width: Option<SizeValue>,
+    /// Minimum width in columns.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub min_width: Option<u16>,
+    /// Maximum height in rows, or percentage of terminal height.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub max_height: Option<SizeValue>,
+    /// Anchor point when `row`/`col` are unset (default center).
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub anchor: Option<OverlayAnchor>,
+    /// Horizontal offset from the resolved position (positive = right).
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub offset_x: Option<i16>,
+    /// Vertical offset from the resolved position (positive = down).
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub offset_y: Option<i16>,
+    /// Absolute or percent row position (overrides vertical anchor).
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub row: Option<SizeValue>,
+    /// Absolute or percent column position (overrides horizontal anchor).
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub col: Option<SizeValue>,
+    /// Margin from terminal edges: a uniform scalar or per-side object.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub margin: Option<OverlayMarginWire>,
+    /// When true, showing the overlay does not capture keyboard focus.
+    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
+    pub non_capturing: bool,
+}
+
+/// Wire protocol version negotiated in [`Hello`] / [`HelloAck`].
+pub const PROTOCOL_VERSION: u32 = 1;
+
+/// Compatibility target: reference `@earendil-works/pi-coding-agent` version.
+pub const COMPATIBILITY_VERSION: &str = "0.80.10";
+
+/// Maximum UTF-8 byte length of one frame line (excluding the trailing newline).
+pub const MAX_FRAME_BYTES: usize = 8 * 1024 * 1024;
+
+/// Correlation identifier for request/response/error frames.
+///
+/// Event frames use `0` when unsolicited, or the parent request id when
+/// streaming updates for that call.
+pub type FrameId = u64;
+
+/// Result type for protocol encode/decode/validation operations.
+pub type Result<T, E = ProtocolError> = std::result::Result<T, E>;
+/// Protocol encode, decode, validation, or handshake failure.
+#[derive(Debug, Error, Clone, PartialEq, Eq)]
+pub enum ProtocolError {
+    /// Frame line exceeded [`MAX_FRAME_BYTES`] before a newline arrived.
+    #[error("frame exceeds maximum size of {MAX_FRAME_BYTES} bytes")]
+    FrameTooLarge,
+    /// Bytes were not valid UTF-8.
+    #[error("invalid UTF-8 in protocol stream: {0}")]
+    InvalidUtf8(String),
+    /// A complete line was not valid JSON.
+    #[error("invalid JSON frame: {0}")]
+    InvalidJson(String),
+    /// JSON decoded but was not a protocol frame object.
+    #[error("malformed frame: {0}")]
+    MalformedFrame(String),
+    /// Frame kind/id/method rules were violated.
+    #[error("invalid frame: {0}")]
+    InvalidFrame(String),
+    /// Hello handshake versions are incompatible.
+    #[error("protocol version mismatch: remote={remote} local={local}")]
+    VersionMismatch {
+        /// Remote peer protocol version.
+        remote: u32,
+        /// Local protocol version.
+        local: u32,
+    },
+    /// Compatibility string does not match the supported coding-agent version.
+    #[error("compatibility version mismatch: remote={remote} local={local}")]
+    CompatibilityMismatch {
+        /// Remote compatibility version string.
+        remote: String,
+        /// Local compatibility version string.
+        local: String,
+    },
+    /// Method name is not in the bridge/host-control allowlist.
+    #[error("unknown protocol method: {0}")]
+    UnknownMethod(String),
+    /// Stream ended while a partial line was still buffered.
+    #[error("truncated protocol frame at end of stream")]
+    Truncated,
+}
+
+/// Frame kind discriminant on the wire (`req` | `res` | `event` | `error`).
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default, Serialize, Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum FrameKind {
+    /// Correlated request; requires nonzero [`Frame::id`].
+    Req,
+    /// Correlated success response; requires nonzero [`Frame::id`].
+    Res,
+    /// Unsolicited or streaming event; id may be `0` or a parent request id.
+    #[default]
+    Event,
+    /// Correlated or unsolicited error; nonzero id when correlated.
+    Error,
+}
+
+impl FrameKind {
+    /// Wire string for this kind.
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Req => "req",
+            Self::Res => "res",
+            Self::Event => "event",
+            Self::Error => "error",
+        }
+    }
+
+    /// Parse a wire kind string.
+    #[must_use]
+    pub fn parse(raw: &str) -> Option<Self> {
+        match raw {
+            "req" => Some(Self::Req),
+            "res" => Some(Self::Res),
+            "event" => Some(Self::Event),
+            "error" => Some(Self::Error),
+            _ => None,
+        }
+    }
+
+    /// Whether this kind requires a nonzero frame id.
+    #[must_use]
+    pub const fn requires_nonzero_id(self) -> bool {
+        matches!(self, Self::Req | Self::Res)
+    }
+}
+
+impl fmt::Display for FrameKind {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str(self.as_str())
+    }
+}
+
+/// Allowlisted bridge and host-control methods.
+///
+/// Lifecycle event methods reuse the exact `type` discriminants from the
+/// reference extension API and are carried as open method strings on
+/// [`Frame`]; this enum covers the fixed bridge surface plus host-control
+/// dialog / input / slot methods that have typed payloads in this module.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub enum Method {
+    /// Protocol handshake request/response.
+    Hello,
+    /// Extension tool partial UI/result update.
+    ToolUpdate,
+    /// Extension custom-provider stream event.
+    ProviderEvent,
+    /// Host-rendered UI slot push (structured runs).
+    UiSlot,
+    /// Dispose a previously pushed UI slot.
+    DisposeSlot,
+    /// Non-retryable extension failure notification.
+    ExtensionError,
+    /// Native select dialog.
+    Select,
+    /// Native confirm dialog.
+    Confirm,
+    /// Native single-line input dialog.
+    Input,
+    /// Native multi-line editor dialog.
+    Editor,
+    /// Fire-and-forget notification.
+    Notify,
+    /// Raw terminal input to a registered host handler / focused slot.
+    TerminalInput,
+    /// Synchronize validated extension flag values.
+    #[serde(rename = "flags.set")]
+    FlagsSet,
+    /// Dispatch one effective extension shortcut.
+    #[serde(rename = "shortcut.execute")]
+    ShortcutExecute,
+    /// Structured UI event delivered to a focused host component.
+    UiEvent,
+    /// Request a host component measure for a given width/theme generation.
+    Measure,
+    /// Request a host component render for a given width/theme generation.
+    Render,
+}
+
+impl Method {
+    /// All allowlisted methods in stable order.
+    pub const ALL: &'static [Self] = &[
+        Self::Hello,
+        Self::ToolUpdate,
+        Self::ProviderEvent,
+        Self::UiSlot,
+        Self::DisposeSlot,
+        Self::ExtensionError,
+        Self::Select,
+        Self::Confirm,
+        Self::Input,
+        Self::Editor,
+        Self::Notify,
+        Self::TerminalInput,
+        Self::FlagsSet,
+        Self::ShortcutExecute,
+        Self::UiEvent,
+        Self::Measure,
+        Self::Render,
+    ];
+
+    /// Wire method string.
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Hello => "hello",
+            Self::ToolUpdate => "toolUpdate",
+            Self::ProviderEvent => "providerEvent",
+            Self::UiSlot => "uiSlot",
+            Self::DisposeSlot => "disposeSlot",
+            Self::ExtensionError => "extensionError",
+            Self::Select => "select",
+            Self::Confirm => "confirm",
+            Self::Input => "input",
+            Self::Editor => "editor",
+            Self::Notify => "notify",
+            Self::TerminalInput => "terminalInput",
+            Self::FlagsSet => "flags.set",
+            Self::ShortcutExecute => "shortcut.execute",
+            Self::UiEvent => "uiEvent",
+            Self::Measure => "measure",
+            Self::Render => "render",
+        }
+    }
+
+    /// Parse an allowlisted method string.
+    #[must_use]
+    pub fn parse(raw: &str) -> Option<Self> {
+        match raw {
+            "hello" => Some(Self::Hello),
+            "toolUpdate" => Some(Self::ToolUpdate),
+            "providerEvent" => Some(Self::ProviderEvent),
+            "uiSlot" => Some(Self::UiSlot),
+            "disposeSlot" => Some(Self::DisposeSlot),
+            "extensionError" => Some(Self::ExtensionError),
+            "select" => Some(Self::Select),
+            "confirm" => Some(Self::Confirm),
+            "input" => Some(Self::Input),
+            "editor" => Some(Self::Editor),
+            "notify" => Some(Self::Notify),
+            "terminalInput" => Some(Self::TerminalInput),
+            "flags.set" => Some(Self::FlagsSet),
+            "shortcut.execute" => Some(Self::ShortcutExecute),
+            "uiEvent" => Some(Self::UiEvent),
+            "measure" => Some(Self::Measure),
+            "render" => Some(Self::Render),
+            _ => None,
+        }
+    }
+
+    /// Whether `raw` is an allowlisted bridge/host-control method.
+    #[must_use]
+    pub fn is_allowlisted(raw: &str) -> bool {
+        Self::parse(raw).is_some()
+    }
+}
+
+impl fmt::Display for Method {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str(self.as_str())
+    }
+}
+/// Wire name for [`Method::UiSlot`].
+#[must_use]
+pub const fn ui_slot_method() -> &'static str {
+    "uiSlot"
+}
+
+/// Wire name for [`Method::DisposeSlot`].
+#[must_use]
+pub const fn dispose_slot_method() -> &'static str {
+    "disposeSlot"
+}
+
+/// Wire name for [`Method::ToolUpdate`].
+#[must_use]
+pub const fn tool_update_method() -> &'static str {
+    "toolUpdate"
+}
+
+/// Wire name for [`Method::ProviderEvent`].
+#[must_use]
+pub const fn provider_event_method() -> &'static str {
+    "providerEvent"
+}
+
+/// Wire name for [`Method::ExtensionError`].
+#[must_use]
+pub const fn extension_error_method() -> &'static str {
+    "extensionError"
+}
+
+/// Compatibility validation message helper used by the host client.
+pub struct FrameValidationError;
+
+impl FrameValidationError {
+    /// Generic validation message for a rejected frame.
+    #[must_use]
+    pub const fn message_for(_frame: &Frame) -> &'static str {
+        "invalid protocol frame"
+    }
+}
+
+/// One protocol frame.
+#[derive(Debug, Clone, PartialEq, Default, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct Frame {
+    /// Correlation id (`0` only for unsolicited events / uncorrelated errors).
+    pub id: FrameId,
+    /// Frame kind.
+    pub kind: FrameKind,
+    /// Method name (bridge, host-control, or lifecycle event type).
+    pub method: String,
+    /// Method-specific JSON payload (object for typed methods).
+    #[serde(default)]
+    pub payload: Value,
+}
+
+impl Frame {
+    /// Build a frame with a typed method.
+    #[must_use]
+    pub fn new(id: FrameId, kind: FrameKind, method: Method, payload: Value) -> Self {
+        Self {
+            id,
+            kind,
+            method: method.as_str().to_owned(),
+            payload,
+        }
+    }
+
+    /// Build a request frame.
+    #[must_use]
+    pub fn request(id: FrameId, method: Method, payload: Value) -> Self {
+        Self::new(id, FrameKind::Req, method, payload)
+    }
+
+    /// Build a response frame.
+    #[must_use]
+    pub fn response(id: FrameId, method: Method, payload: Value) -> Self {
+        Self::new(id, FrameKind::Res, method, payload)
+    }
+
+    /// Build an event frame.
+    #[must_use]
+    pub fn event(id: FrameId, method: Method, payload: Value) -> Self {
+        Self::new(id, FrameKind::Event, method, payload)
+    }
+
+    /// Build an error frame with a structured error body.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`ProtocolError::InvalidJson`] if the error body cannot be
+    /// serialized (should not occur for well-formed [`ErrorPayload`] values).
+    pub fn error_frame(id: FrameId, method: Method, error: &ErrorPayload) -> Result<Self> {
+        let payload = serde_json::to_value(error)
+            .map_err(|e| ProtocolError::InvalidJson(format!("serialize error payload: {e}")))?;
+        Ok(Self::new(id, FrameKind::Error, method, payload))
+    }
+
+    /// Parse the method field as an allowlisted [`Method`].
+    #[must_use]
+    pub fn method_enum(&self) -> Option<Method> {
+        Method::parse(&self.method)
+    }
+
+    /// Validate id/kind rules and, when `require_allowlisted`, the method set.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`ProtocolError::InvalidFrame`] or
+    /// [`ProtocolError::UnknownMethod`] when validation fails.
+    pub fn validate(&self, require_allowlisted: bool) -> Result<()> {
+        if self.kind.requires_nonzero_id() && self.id == 0 {
+            return Err(ProtocolError::InvalidFrame(format!(
+                "kind {} requires nonzero id",
+                self.kind
+            )));
+        }
+        if self.method.is_empty() {
+            return Err(ProtocolError::InvalidFrame(
+                "method must be a non-empty string".to_owned(),
+            ));
+        }
+        if require_allowlisted && !Method::is_allowlisted(&self.method) {
+            return Err(ProtocolError::UnknownMethod(self.method.clone()));
+        }
+        // Reject scalar payloads; typed methods use objects (arrays allowed for open payloads).
+        match &self.payload {
+            Value::Null | Value::Object(_) | Value::Array(_) => {}
+            Value::Bool(_) | Value::Number(_) | Value::String(_) => {
+                return Err(ProtocolError::InvalidFrame(
+                    "payload must be a JSON object or array".to_owned(),
+                ));
+            }
+        }
+        if self.method == Method::UiSlot.as_str() {
+            let slot: UiSlot = serde_json::from_value(self.payload.clone()).map_err(|error| {
+                ProtocolError::InvalidFrame(format!("invalid uiSlot payload: {error}"))
+            })?;
+            slot.validate()?;
+        }
+        Ok(())
+    }
+}
+
+/// Client → host hello request payload.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct Hello {
+    /// Protocol version (`1`).
+    pub protocol_version: u32,
+    /// Reference coding-agent compatibility version.
+    pub compatibility_version: String,
+}
+
+impl Hello {
+    /// Local hello payload for the current build.
+    #[must_use]
+    pub fn local() -> Self {
+        Self {
+            protocol_version: PROTOCOL_VERSION,
+            compatibility_version: COMPATIBILITY_VERSION.to_owned(),
+        }
+    }
+
+    /// Validate remote hello against local constants.
+    ///
+    /// # Errors
+    ///
+    /// Returns version or compatibility mismatch errors.
+    pub fn validate_remote(&self) -> Result<()> {
+        if self.protocol_version != PROTOCOL_VERSION {
+            return Err(ProtocolError::VersionMismatch {
+                remote: self.protocol_version,
+                local: PROTOCOL_VERSION,
+            });
+        }
+        if self.compatibility_version != COMPATIBILITY_VERSION {
+            return Err(ProtocolError::CompatibilityMismatch {
+                remote: self.compatibility_version.clone(),
+                local: COMPATIBILITY_VERSION.to_owned(),
+            });
+        }
+        Ok(())
+    }
+}
+
+/// Host → client hello acknowledgment payload.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct HelloAck {
+    /// Protocol version accepted by the peer.
+    pub protocol_version: u32,
+    /// Compatibility version accepted by the peer.
+    pub compatibility_version: String,
+}
+
+impl HelloAck {
+    /// Local acknowledgment payload.
+    #[must_use]
+    pub fn local() -> Self {
+        Self {
+            protocol_version: PROTOCOL_VERSION,
+            compatibility_version: COMPATIBILITY_VERSION.to_owned(),
+        }
+    }
+}
+
+/// Structured error payload for `kind: "error"` frames.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ErrorPayload {
+    /// Stable machine-readable error code.
+    pub code: String,
+    /// Human-readable message.
+    pub message: String,
+    /// Whether the caller may retry the same side effect (always false for
+    /// extension failures per host policy).
+    pub retryable: bool,
+    /// Optional structured detail.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub data: Option<Value>,
+}
+
+impl ErrorPayload {
+    /// Non-retryable error without detail data.
+    #[must_use]
+    pub fn new(code: impl Into<String>, message: impl Into<String>) -> Self {
+        Self {
+            code: code.into(),
+            message: message.into(),
+            retryable: false,
+            data: None,
+        }
+    }
+}
+
+/// Allowlisted text style for structured UI runs (no raw ANSI).
+#[derive(Debug, Clone, PartialEq, Eq, Default, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase", default)]
+pub struct Style {
+    /// Bold emphasis.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub bold: Option<bool>,
+    /// Dim/faint emphasis.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub dim: Option<bool>,
+    /// Italic emphasis.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub italic: Option<bool>,
+    /// Underline.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub underline: Option<bool>,
+    /// Reverse video.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub reverse: Option<bool>,
+    /// Strikethrough.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub strikethrough: Option<bool>,
+    /// Foreground color.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub fg: Option<WireColor>,
+    /// Background color.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub bg: Option<WireColor>,
+    /// Optional validated hyperlink (OSC 8 fields).
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub link: Option<Hyperlink>,
+}
+
+/// Allowlisted color encoding for styled runs.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(tag = "type", rename_all = "camelCase")]
+pub enum WireColor {
+    /// Named 8/16-color palette entry.
+    Named {
+        /// Palette name (`black`, `red`, …, `brightWhite`).
+        name: NamedColor,
+    },
+    /// 256-color index.
+    Indexed {
+        /// Palette index `0..=255`.
+        index: u8,
+    },
+    /// Truecolor RGB triple.
+    Rgb {
+        /// Red channel.
+        r: u8,
+        /// Green channel.
+        g: u8,
+        /// Blue channel.
+        b: u8,
+    },
+}
+
+/// Named ANSI palette colors (standard + bright).
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub enum NamedColor {
+    /// Black.
+    Black,
+    /// Red.
+    Red,
+    /// Green.
+    Green,
+    /// Yellow.
+    Yellow,
+    /// Blue.
+    Blue,
+    /// Magenta.
+    Magenta,
+    /// Cyan.
+    Cyan,
+    /// White.
+    White,
+    /// Bright black / gray.
+    BrightBlack,
+    /// Bright red.
+    BrightRed,
+    /// Bright green.
+    BrightGreen,
+    /// Bright yellow.
+    BrightYellow,
+    /// Bright blue.
+    BrightBlue,
+    /// Bright magenta.
+    BrightMagenta,
+    /// Bright cyan.
+    BrightCyan,
+    /// Bright white.
+    BrightWhite,
+}
+
+/// Validated OSC 8 hyperlink fields (http/https only on the Rust boundary).
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct Hyperlink {
+    /// Optional link id (≤ 128 bytes when validated).
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub id: Option<String>,
+    /// Absolute URI (`http` / `https`, ≤ 2048 bytes when validated).
+    pub uri: String,
+}
+
+impl Hyperlink {
+    /// Maximum accepted id length in bytes.
+    pub const MAX_ID_BYTES: usize = 128;
+    /// Maximum accepted URI length in bytes.
+    pub const MAX_URI_BYTES: usize = 2048;
+
+    /// Validate scheme and size limits.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`ProtocolError::InvalidFrame`] when the link is rejected.
+    pub fn validate(&self) -> Result<()> {
+        if let Some(id) = &self.id
+            && id.len() > Self::MAX_ID_BYTES
+        {
+            return Err(ProtocolError::InvalidFrame(format!(
+                "hyperlink id exceeds {} bytes",
+                Self::MAX_ID_BYTES
+            )));
+        }
+        if self.uri.len() > Self::MAX_URI_BYTES {
+            return Err(ProtocolError::InvalidFrame(format!(
+                "hyperlink uri exceeds {} bytes",
+                Self::MAX_URI_BYTES
+            )));
+        }
+        let ok = self.uri.starts_with("http://") || self.uri.starts_with("https://");
+        if !ok {
+            return Err(ProtocolError::InvalidFrame(
+                "hyperlink uri must use http or https".to_owned(),
+            ));
+        }
+        Ok(())
+    }
+}
+impl UiSlot {
+    /// Validate every hyperlink carried by every styled run.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`ProtocolError::InvalidFrame`] for a forbidden scheme or an
+    /// oversized hyperlink id/URI.
+    pub fn validate(&self) -> Result<()> {
+        for line in &self.runs {
+            for run in line {
+                if let Some(link) = &run.style.link {
+                    link.validate()?;
+                }
+            }
+        }
+        Ok(())
+    }
+}
+
+/// One contiguous styled text run inside a UI slot line.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct StyledRun {
+    /// Printable text (no embedded newlines; tabs expanded by the host).
+    pub text: String,
+    /// Optional style; omitted/default means unstyled.
+    #[serde(default, skip_serializing_if = "is_default_style")]
+    pub style: Style,
+}
+
+fn is_default_style(style: &Style) -> bool {
+    style == &Style::default()
+}
+
+/// Where a host UI slot is placed in the native composition tree.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub enum SlotPlacement {
+    /// Startup / chat header region.
+    #[default]
+    Header,
+    /// Footer region.
+    Footer,
+    /// Widget row above the editor.
+    AboveEditor,
+    /// Widget row below the editor.
+    BelowEditor,
+    /// Full editor replacement.
+    Editor,
+    /// Custom message / entry renderer.
+    MessageRenderer,
+    /// Modal overlay.
+    Overlay,
+}
+
+/// Cursor cell within a focusable slot (column/row in the slot's content).
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct SlotCursor {
+    /// Zero-based column.
+    pub col: u16,
+    /// Zero-based row.
+    pub row: u16,
+}
+
+/// Host → Rust `uiSlot` event payload (structured runs only).
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct UiSlot {
+    /// Stable slot key.
+    pub key: String,
+    /// Monotonic generation; stale generations are discarded.
+    pub generation: u64,
+    /// Composition placement.
+    pub placement: SlotPlacement,
+    /// Measured height in rows.
+    pub height: u16,
+    /// Lines of styled runs (`lines[row][run]`).
+    pub runs: Vec<Vec<StyledRun>>,
+    /// Whether the slot can receive focus / input.
+    #[serde(default)]
+    pub focusable: bool,
+    /// Optional hardware-cursor hint inside the slot.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub cursor: Option<SlotCursor>,
+    /// Overlay layout options when [`SlotPlacement::Overlay`].
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub overlay_options: Option<OverlaySpec>,
+}
+
+/// Dispose a keyed slot (and any focused state).
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct DisposeSlot {
+    /// Slot key to dispose.
+    pub key: String,
+    /// Optional generation that triggered dispose.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub generation: Option<u64>,
+}
+
+/// Non-retryable extension failure event payload.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ExtensionErrorEvent {
+    /// Stable error code.
+    pub code: String,
+    /// Human-readable message.
+    pub message: String,
+    /// Always false for extension side effects.
+    #[serde(default)]
+    pub retryable: bool,
+    /// Optional extension path / detail.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub data: Option<Value>,
+}
+
+/// Partial tool update from the host.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ToolUpdate {
+    /// Tool call id.
+    pub tool_call_id: String,
+    /// Tool name.
+    pub tool_name: String,
+    /// Partial result payload (open JSON).
+    pub partial_result: Value,
+}
+
+/// Custom provider stream event from the host.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ProviderEvent {
+    /// Provider registration id.
+    pub provider_id: String,
+    /// Stream / call correlation id.
+    pub call_id: String,
+    /// Event name within the provider stream.
+    pub event: String,
+    /// Event payload (open JSON).
+    #[serde(default)]
+    pub data: Value,
+}
+
+/// Key modifiers on the wire (shift|alt|ctrl|super).
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase", default)]
+pub struct KeyModifiersWire {
+    /// Shift.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub shift: Option<bool>,
+    /// Alt / option.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub alt: Option<bool>,
+    /// Control.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub ctrl: Option<bool>,
+    /// Super / meta / command.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub super_key: Option<bool>,
+}
+
+/// Key event kind on the wire.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub enum KeyEventKindWire {
+    /// Key press (default).
+    #[default]
+    Press,
+    /// Key release (Kitty).
+    Release,
+    /// Key repeat.
+    Repeat,
+}
+
+/// Structured UI event delivered over the protocol (never Ratatui/crossterm types).
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(tag = "type", rename_all = "camelCase")]
+pub enum UiEventWire {
+    /// Keyboard event.
+    Key {
+        /// Key id grammar base (`enter`, `a`, `f1`, …).
+        code: String,
+        /// Modifier set.
+        #[serde(default)]
+        modifiers: KeyModifiersWire,
+        /// Press / release / repeat.
+        #[serde(default)]
+        kind: KeyEventKindWire,
+    },
+    /// Bracketed paste text (newlines normalized to `\n`).
+    Paste {
+        /// Pasted text.
+        text: String,
+    },
+    /// Terminal focus gained.
+    FocusGained,
+    /// Terminal focus lost.
+    FocusLost,
+    /// Terminal resize.
+    Resize {
+        /// Columns.
+        width: u16,
+        /// Rows.
+        height: u16,
+    },
+}
+
+/// Validated extension flag value sent to the TypeScript runtime.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(untagged)]
+pub enum FlagValueWire {
+    /// Boolean CLI flag.
+    Boolean(bool),
+    /// String CLI flag.
+    String(String),
+}
+
+/// Payload for [`FLAGS_SET_METHOD`].
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct FlagsSetRequest {
+    /// Complete validated flag-value overlay.
+    pub values: BTreeMap<String, FlagValueWire>,
+}
+
+/// Acknowledgement for [`FLAGS_SET_METHOD`].
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct FlagsSetResponse {
+    /// True when the host applied every supplied value.
+    pub ok: bool,
+}
+
+/// Payload for [`SHORTCUT_EXECUTE_METHOD`].
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ShortcutExecuteRequest {
+    /// Canonical lower-case key identifier.
+    pub key: String,
+}
+
+/// Immediate dispatch acknowledgement for [`SHORTCUT_EXECUTE_METHOD`].
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ShortcutExecuteResponse {
+    /// Whether a live extension shortcut owned this key.
+    pub handled: bool,
+}
+
+/// Keyed UI event request for [`Method::UiEvent`].
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct UiEventRequest {
+    /// UI slot key.
+    pub key: String,
+    /// Slot generation observed by the native product.
+    pub generation: u64,
+    /// Structured event for cross-language inspection.
+    pub event: UiEventWire,
+    /// Raw terminal input bytes for component `handleInput`, when applicable.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub data: Option<String>,
+}
+
+/// Host delivery result for [`Method::UiEvent`].
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct UiEventResponse {
+    /// True only when the key and generation matched a live component.
+    pub delivered: bool,
+}
+
+/// Terminal-input rewrite / consume result for `terminalInput`.
+#[derive(Debug, Clone, PartialEq, Eq, Default, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase", default)]
+pub struct TerminalInputResult {
+    /// When true, native handling is skipped.
+    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
+    pub consume: bool,
+    /// Optional rewritten input data.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub data: Option<String>,
+}
+
+/// Dialog timeout option shared by select/confirm/input.
+#[derive(Debug, Clone, PartialEq, Eq, Default, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase", default)]
+pub struct DialogOptions {
+    /// Auto-dismiss timeout in milliseconds.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub timeout_ms: Option<u64>,
+}
+
+/// `select` request payload.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct SelectRequest {
+    /// Dialog title.
+    pub title: String,
+    /// Options presented to the user.
+    pub options: Vec<String>,
+    /// Optional timeout.
+    #[serde(default, flatten)]
+    pub options_meta: DialogOptions,
+}
+
+/// `select` response payload.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct SelectResponse {
+    /// Chosen option, or `null`/missing when dismissed.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub value: Option<String>,
+}
+
+/// `confirm` request payload.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ConfirmRequest {
+    /// Dialog title.
+    pub title: String,
+    /// Dialog message body.
+    pub message: String,
+    /// Optional timeout.
+    #[serde(default, flatten)]
+    pub options_meta: DialogOptions,
+}
+
+/// `confirm` response payload.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ConfirmResponse {
+    /// Whether the user confirmed.
+    pub confirmed: bool,
+}
+
+/// `input` request payload.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct InputRequest {
+    /// Dialog title.
+    pub title: String,
+    /// Placeholder text.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub placeholder: Option<String>,
+    /// Optional timeout.
+    #[serde(default, flatten)]
+    pub options_meta: DialogOptions,
+}
+
+/// `input` response payload.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct InputResponse {
+    /// Entered value, or dismissed.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub value: Option<String>,
+}
+
+/// `editor` request payload.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct EditorRequest {
+    /// Dialog title.
+    pub title: String,
+    /// Prefill text.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub prefill: Option<String>,
+}
+
+/// `editor` response payload.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct EditorResponse {
+    /// Edited value, or dismissed.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub value: Option<String>,
+}
+
+/// Notification level for `notify`.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub enum NotifyLevel {
+    /// Informational.
+    #[default]
+    Info,
+    /// Warning.
+    Warning,
+    /// Error.
+    Error,
+}
+
+/// `notify` request/event payload.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct NotifyRequest {
+    /// Notification text.
+    pub message: String,
+    /// Severity.
+    #[serde(default, rename = "type")]
+    pub level: NotifyLevel,
+}
+
+/// Measure/render request shared fields.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct SlotRenderRequest {
+    /// Slot key.
+    pub key: String,
+    /// Available width in columns.
+    pub width: u16,
+    /// Theme generation counter.
+    pub theme_generation: u64,
+}
+
+/// Measure response height.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct MeasureResponse {
+    /// Measured height in rows.
+    pub height: u16,
+}
+
+/// Encode a frame to a single UTF-8 JSON line including the trailing `\n`.
+///
+/// # Errors
+///
+/// Returns [`ProtocolError::InvalidFrame`] when validation fails, or
+/// [`ProtocolError::InvalidJson`] / [`ProtocolError::FrameTooLarge`] when the
+/// encoded line is invalid or too large.
+pub fn encode_frame(frame: &Frame) -> Result<Vec<u8>> {
+    frame.validate(false)?;
+    let mut bytes = serde_json::to_vec(frame)
+        .map_err(|e| ProtocolError::InvalidJson(format!("encode frame: {e}")))?;
+    if bytes.len() > MAX_FRAME_BYTES {
+        return Err(ProtocolError::FrameTooLarge);
+    }
+    bytes.push(b'\n');
+    Ok(bytes)
+}
+
+/// Encode a frame as a UTF-8 string including the trailing newline.
+///
+/// # Errors
+///
+/// Same as [`encode_frame`].
+pub fn encode_frame_string(frame: &Frame) -> Result<String> {
+    let bytes = encode_frame(frame)?;
+    String::from_utf8(bytes).map_err(|e| ProtocolError::InvalidUtf8(e.to_string()))
+}
+
+/// Decode one complete JSON line (no trailing newline required) into a frame.
+///
+/// # Errors
+///
+/// Returns UTF-8, JSON, malformation, size, or validation errors.
+pub fn decode_frame_line(line: &[u8]) -> Result<Frame> {
+    if line.len() > MAX_FRAME_BYTES {
+        return Err(ProtocolError::FrameTooLarge);
+    }
+    let text = str::from_utf8(line).map_err(|e| ProtocolError::InvalidUtf8(e.to_string()))?;
+    decode_frame_str(text)
+}
+
+/// Decode one complete JSON line string into a frame.
+///
+/// # Errors
+///
+/// Returns JSON, malformation, size, or validation errors.
+pub fn decode_frame_str(line: &str) -> Result<Frame> {
+    let trimmed = line.trim_end_matches('\r');
+    if trimmed.is_empty() {
+        return Err(ProtocolError::MalformedFrame("empty line".to_owned()));
+    }
+    if trimmed.len() > MAX_FRAME_BYTES {
+        return Err(ProtocolError::FrameTooLarge);
+    }
+    let frame: Frame =
+        serde_json::from_str(trimmed).map_err(|e| ProtocolError::InvalidJson(e.to_string()))?;
+    frame.validate(false)?;
+    Ok(frame)
+}
+
+/// Decode and require an allowlisted method.
+///
+/// # Errors
+///
+/// Propagates [`decode_frame_str`] errors and [`ProtocolError::UnknownMethod`].
+pub fn decode_frame_str_strict(line: &str) -> Result<Frame> {
+    let frame = decode_frame_str(line)?;
+    frame.validate(true)?;
+    Ok(frame)
+}
+
+/// Incremental JSONL frame decoder with a hard size bound.
+///
+/// Accepts partial chunks, multiple frames per push, LF or CRLF separators,
+/// and rejects oversize lines **before** the internal buffer can grow past
+/// [`MAX_FRAME_BYTES`] + 1 pending newline scan window.
+#[derive(Debug, Default)]
+pub struct FrameDecoder {
+    buf: Vec<u8>,
+    max_frame_bytes: usize,
+}
+
+impl FrameDecoder {
+    /// Create a decoder with the protocol default size limit.
+    #[must_use]
+    pub fn new() -> Self {
+        Self {
+            buf: Vec::new(),
+            max_frame_bytes: MAX_FRAME_BYTES,
+        }
+    }
+
+    /// Create a decoder with a custom max frame size (tests).
+    #[must_use]
+    pub fn with_max_frame_bytes(max_frame_bytes: usize) -> Self {
+        Self {
+            buf: Vec::new(),
+            max_frame_bytes,
+        }
+    }
+
+    /// Bytes currently buffered (incomplete line).
+    #[must_use]
+    pub fn buffered_len(&self) -> usize {
+        self.buf.len()
+    }
+
+    /// Push bytes and return every complete frame decoded from this chunk.
+    ///
+    /// # Errors
+    ///
+    /// Returns the first size / UTF-8 / JSON / validation error encountered.
+    /// On error, the decoder may drop the offending line and keep subsequent
+    /// buffered data only when the error was per-line; oversize clears the
+    /// current line buffer.
+    pub fn push(&mut self, chunk: &[u8]) -> Result<Vec<Frame>> {
+        let mut out = Vec::new();
+        let mut offset = 0usize;
+        while offset < chunk.len() {
+            // Find next newline in chunk without copying the whole remainder.
+            if let Some(rel) = chunk[offset..].iter().position(|&b| b == b'\n') {
+                let line_end_in_chunk = offset + rel;
+                let pending = self.buf.len() + (line_end_in_chunk - offset);
+                if pending > self.max_frame_bytes {
+                    self.buf.clear();
+                    return Err(ProtocolError::FrameTooLarge);
+                }
+                self.buf
+                    .extend_from_slice(&chunk[offset..line_end_in_chunk]);
+                // Strip one trailing CR for CRLF.
+                if self.buf.last() == Some(&b'\r') {
+                    self.buf.pop();
+                }
+                let line = std::mem::take(&mut self.buf);
+                out.push(decode_frame_line(&line)?);
+                offset = line_end_in_chunk + 1;
+            } else {
+                let pending = self.buf.len() + (chunk.len() - offset);
+                if pending > self.max_frame_bytes {
+                    self.buf.clear();
+                    return Err(ProtocolError::FrameTooLarge);
+                }
+                // Grow only up to the remaining allowed bytes.
+                self.buf.extend_from_slice(&chunk[offset..]);
+                break;
+            }
+        }
+        Ok(out)
+    }
+
+    /// Finish the stream: error if a partial line remains; `Ok(None)` if empty.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`ProtocolError::Truncated`] when buffered bytes remain, or
+    /// decode errors if a final line without newline should be accepted — this
+    /// API requires newline-terminated frames, so remainder is truncated.
+    pub fn finish(&mut self) -> Result<Option<Frame>> {
+        if self.buf.is_empty() {
+            return Ok(None);
+        }
+        // Final non-empty buffer without newline is a truncated frame.
+        let leftover = std::mem::take(&mut self.buf);
+        if leftover.iter().all(u8::is_ascii_whitespace) {
+            return Ok(None);
+        }
+        Err(ProtocolError::Truncated)
+    }
+
+    /// Finish accepting a final line without a trailing newline (EOF flush).
+    ///
+    /// # Errors
+    ///
+    /// Returns decode errors for the final line, or [`ProtocolError::FrameTooLarge`].
+    pub fn finish_with_final_line(&mut self) -> Result<Option<Frame>> {
+        if self.buf.is_empty() {
+            return Ok(None);
+        }
+        if self.buf.len() > self.max_frame_bytes {
+            self.buf.clear();
+            return Err(ProtocolError::FrameTooLarge);
+        }
+        if self.buf.last() == Some(&b'\r') {
+            self.buf.pop();
+        }
+        let line = std::mem::take(&mut self.buf);
+        if line.is_empty() {
+            return Ok(None);
+        }
+        Ok(Some(decode_frame_line(&line)?))
+    }
+
+    /// Reset buffered state.
+    pub fn reset(&mut self) {
+        self.buf.clear();
+    }
+}
+
+/// Serialize a typed payload into a JSON object value.
+///
+/// # Errors
+///
+/// Returns [`ProtocolError::InvalidJson`] on serialization failure.
+pub fn to_payload<T: Serialize>(value: &T) -> Result<Value> {
+    serde_json::to_value(value).map_err(|e| ProtocolError::InvalidJson(e.to_string()))
+}
+
+/// Deserialize a typed payload from a frame payload value.
+///
+/// # Errors
+///
+/// Returns [`ProtocolError::InvalidJson`] on deserialization failure.
+pub fn from_payload<T: for<'de> Deserialize<'de>>(payload: &Value) -> Result<T> {
+    serde_json::from_value(payload.clone()).map_err(|e| ProtocolError::InvalidJson(e.to_string()))
+}
+
+/// Empty object payload helper.
+#[must_use]
+pub fn empty_object() -> Value {
+    Value::Object(Map::new())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    const FIXTURES: &str = include_str!("../tests/fixtures/protocol/frames.jsonl");
+
+    type TestResult = std::result::Result<(), Box<dyn std::error::Error>>;
+
+    fn sample_hello_req() -> Result<Frame> {
+        Ok(Frame::request(
+            1,
+            Method::Hello,
+            to_payload(&Hello::local())?,
+        ))
+    }
+
+    #[test]
+    fn versions_are_stable() {
+        assert_eq!(PROTOCOL_VERSION, 1);
+        assert_eq!(COMPATIBILITY_VERSION, "0.80.10");
+        assert_eq!(MAX_FRAME_BYTES, 8 * 1024 * 1024);
+    }
+
+    #[test]
+    fn method_allowlist_roundtrip() {
+        for method in Method::ALL {
+            assert_eq!(Method::parse(method.as_str()), Some(*method));
+        }
+        assert_eq!(FLAGS_SET_METHOD, Method::FlagsSet.as_str());
+        assert_eq!(SHORTCUT_EXECUTE_METHOD, Method::ShortcutExecute.as_str());
+        assert!(Method::parse("notAMethod").is_none());
+    }
+
+    #[test]
+    fn frame_id_rules() -> TestResult {
+        let mut frame = sample_hello_req()?;
+        frame.id = 0;
+        assert!(matches!(
+            frame.validate(false),
+            Err(ProtocolError::InvalidFrame(_))
+        ));
+        Frame::event(0, Method::Notify, empty_object()).validate(false)?;
+        Ok(())
+    }
+
+    #[test]
+    fn hello_version_gate() -> TestResult {
+        Hello::local().validate_remote()?;
+        let bad = Hello {
+            protocol_version: 99,
+            compatibility_version: COMPATIBILITY_VERSION.to_owned(),
+        };
+        assert!(matches!(
+            bad.validate_remote(),
+            Err(ProtocolError::VersionMismatch {
+                remote: 99,
+                local: 1
+            })
+        ));
+        let bad_compat = Hello {
+            protocol_version: 1,
+            compatibility_version: "0.0.0".to_owned(),
+        };
+        assert!(matches!(
+            bad_compat.validate_remote(),
+            Err(ProtocolError::CompatibilityMismatch { .. })
+        ));
+        Ok(())
+    }
+
+    #[test]
+    fn encode_decode_roundtrip_typed() -> TestResult {
+        let hello = sample_hello_req()?;
+        let line = encode_frame_string(&hello)?;
+        assert!(line.ends_with('\n'));
+        let decoded = decode_frame_str(line.trim_end())?;
+        assert_eq!(decoded, hello);
+        assert_eq!(from_payload::<Hello>(&decoded.payload)?, Hello::local());
+
+        let ack = Frame::response(1, Method::Hello, to_payload(&HelloAck::local())?);
+        let ack_line = encode_frame_string(&ack)?;
+        let decoded_ack = decode_frame_str(ack_line.trim_end())?;
+        assert_eq!(
+            from_payload::<HelloAck>(&decoded_ack.payload)?,
+            HelloAck::local()
+        );
+        Ok(())
+    }
+
+    fn sample_slot() -> UiSlot {
+        UiSlot {
+            key: "widget.demo".to_owned(),
+            generation: 3,
+            placement: SlotPlacement::AboveEditor,
+            height: 2,
+            runs: vec![
+                vec![StyledRun {
+                    text: "hi".to_owned(),
+                    style: Style {
+                        bold: Some(true),
+                        fg: Some(WireColor::Named {
+                            name: NamedColor::Green,
+                        }),
+                        ..Style::default()
+                    },
+                }],
+                vec![StyledRun {
+                    text: "link".to_owned(),
+                    style: Style {
+                        underline: Some(true),
+                        link: Some(Hyperlink {
+                            id: Some("a".to_owned()),
+                            uri: "https://example.com".to_owned(),
+                        }),
+                        fg: Some(WireColor::Rgb { r: 1, g: 2, b: 3 }),
+                        ..Style::default()
+                    },
+                }],
+            ],
+            focusable: true,
+            cursor: Some(SlotCursor { col: 1, row: 0 }),
+            overlay_options: Some(OverlaySpec {
+                width: Some(SizeValue::Percent(50)),
+                anchor: Some(OverlayAnchor::TopCenter),
+                margin: Some(OverlayMarginWire::Uniform(2)),
+                non_capturing: true,
+                ..OverlaySpec::default()
+            }),
+        }
+    }
+
+    #[test]
+    fn ui_slot_and_style_roundtrip() -> TestResult {
+        let slot = sample_slot();
+        let frame = Frame::event(0, Method::UiSlot, to_payload(&slot)?);
+        let line = encode_frame_string(&frame)?;
+        let decoded = decode_frame_str(line.trim_end())?;
+        let back: UiSlot = from_payload(&decoded.payload)?;
+        assert_eq!(back, slot);
+        back.validate()?;
+        Ok(())
+    }
+
+    #[test]
+    fn overlay_margin_accepts_uniform_and_sides() -> TestResult {
+        let uniform: OverlaySpec = serde_json::from_value(serde_json::json!({"margin": 3}))?;
+        assert_eq!(uniform.margin, Some(OverlayMarginWire::Uniform(3)));
+
+        let sides: OverlaySpec = serde_json::from_value(serde_json::json!({
+            "margin": {"top": 1, "right": 2, "bottom": 3, "left": 4}
+        }))?;
+        assert_eq!(
+            sides.margin,
+            Some(OverlayMarginWire::Sides(OverlayMargin {
+                top: 1,
+                right: 2,
+                bottom: 3,
+                left: 4,
+            }))
+        );
+        Ok(())
+    }
+
+    #[test]
+    fn ui_slot_rejects_forbidden_and_oversized_links() {
+        for link in [
+            serde_json::json!({"uri": "javascript:alert(1)"}),
+            serde_json::json!({"uri": "file:///tmp/x"}),
+            serde_json::json!({"uri": format!("https://example.com/{}", "x".repeat(2048))}),
+            serde_json::json!({"id": "x".repeat(129), "uri": "https://example.com"}),
+        ] {
+            let frame = Frame::event(
+                0,
+                Method::UiSlot,
+                serde_json::json!({
+                    "key": "bad",
+                    "generation": 1,
+                    "placement": "aboveEditor",
+                    "height": 1,
+                    "runs": [[{"text": "bad", "style": {"link": link}}]]
+                }),
+            );
+            assert!(matches!(
+                frame.validate(false),
+                Err(ProtocolError::InvalidFrame(_))
+            ));
+        }
+    }
+
+    #[test]
+    fn dialog_payloads_roundtrip() -> TestResult {
+        let select = SelectRequest {
+            title: "Pick".to_owned(),
+            options: vec!["a".to_owned(), "b".to_owned()],
+            options_meta: DialogOptions {
+                timeout_ms: Some(1000),
+            },
+        };
+        let frame = Frame::request(7, Method::Select, to_payload(&select)?);
+        let line = encode_frame_string(&frame)?;
+        let decoded = decode_frame_str(line.trim_end())?;
+        assert_eq!(from_payload::<SelectRequest>(&decoded.payload)?, select);
+
+        let confirm = ConfirmResponse { confirmed: true };
+        let frame = Frame::response(7, Method::Confirm, to_payload(&confirm)?);
+        let line = encode_frame_string(&frame)?;
+        let decoded = decode_frame_str(line.trim_end())?;
+        assert!(from_payload::<ConfirmResponse>(&decoded.payload)?.confirmed);
+        Ok(())
+    }
+
+    #[test]
+    fn ui_event_wire_variants() -> TestResult {
+        let events = [
+            UiEventWire::Key {
+                code: "enter".to_owned(),
+                modifiers: KeyModifiersWire {
+                    ctrl: Some(true),
+                    ..KeyModifiersWire::default()
+                },
+                kind: KeyEventKindWire::Press,
+            },
+            UiEventWire::Paste {
+                text: "a\nb".to_owned(),
+            },
+            UiEventWire::FocusGained,
+            UiEventWire::FocusLost,
+            UiEventWire::Resize {
+                width: 80,
+                height: 24,
+            },
+        ];
+        for event in events {
+            let frame = Frame::request(2, Method::UiEvent, to_payload(&event)?);
+            let line = encode_frame_string(&frame)?;
+            let decoded = decode_frame_str(line.trim_end())?;
+            assert_eq!(from_payload::<UiEventWire>(&decoded.payload)?, event);
+        }
+        Ok(())
+    }
+
+    #[test]
+    fn decoder_fragmentation_and_multiple() -> TestResult {
+        let first = sample_hello_req()?;
+        let second = Frame::response(1, Method::Hello, to_payload(&HelloAck::local())?);
+        let mut bytes = encode_frame(&first)?;
+        bytes.extend(encode_frame(&second)?);
+        let mut decoder = FrameDecoder::new();
+        let mut got = Vec::new();
+        for byte in bytes {
+            got.extend(decoder.push(&[byte])?);
+        }
+        assert!(decoder.finish()?.is_none());
+        assert_eq!(got, vec![first, second]);
+        Ok(())
+    }
+
+    #[test]
+    fn decoder_crlf() -> TestResult {
+        let frame = sample_hello_req()?;
+        let mut line = serde_json::to_vec(&frame)?;
+        line.extend_from_slice(b"\r\n");
+        let mut decoder = FrameDecoder::new();
+        let got = decoder.push(&line)?;
+        assert_eq!(got.first(), Some(&frame));
+        assert_eq!(got.len(), 1);
+        Ok(())
+    }
+
+    #[test]
+    fn decoder_final_line_without_newline() -> TestResult {
+        let frame = sample_hello_req()?;
+        let line = serde_json::to_vec(&frame)?;
+        let mut decoder = FrameDecoder::new();
+        assert!(decoder.push(&line)?.is_empty());
+        assert_eq!(decoder.finish_with_final_line()?, Some(frame));
+
+        let mut strict = FrameDecoder::new();
+        assert!(strict.push(&line)?.is_empty());
+        assert!(matches!(strict.finish(), Err(ProtocolError::Truncated)));
+        Ok(())
+    }
+
+    #[test]
+    fn decoder_invalid_utf8_and_json() {
+        let mut decoder = FrameDecoder::new();
+        assert!(matches!(
+            decoder.push(b"\xff\n"),
+            Err(ProtocolError::InvalidUtf8(_))
+        ));
+        let mut decoder = FrameDecoder::new();
+        assert!(matches!(
+            decoder.push(b"{not-json}\n"),
+            Err(ProtocolError::InvalidJson(_))
+        ));
+    }
+
+    #[test]
+    fn decoder_oversized_before_growth() -> TestResult {
+        let limit = 64;
+        let mut decoder = FrameDecoder::with_max_frame_bytes(limit);
+        assert_eq!(
+            decoder.push(&vec![b'a'; limit + 1]),
+            Err(ProtocolError::FrameTooLarge)
+        );
+        assert_eq!(decoder.buffered_len(), 0);
+
+        let mut decoder = FrameDecoder::with_max_frame_bytes(limit);
+        assert!(decoder.push(&vec![b'b'; limit / 2])?.is_empty());
+        assert_eq!(
+            decoder.push(&vec![b'c'; limit]),
+            Err(ProtocolError::FrameTooLarge)
+        );
+        Ok(())
+    }
+
+    #[test]
+    fn strict_unknown_method() -> TestResult {
+        let frame = Frame {
+            id: 1,
+            kind: FrameKind::Req,
+            method: "notAllowlisted".to_owned(),
+            payload: empty_object(),
+        };
+        let line = encode_frame_string(&frame)?;
+        assert!(decode_frame_str(line.trim_end()).is_ok());
+        assert!(matches!(
+            decode_frame_str_strict(line.trim_end()),
+            Err(ProtocolError::UnknownMethod(_))
+        ));
+        Ok(())
+    }
+
+    #[test]
+    fn error_payload_shape() -> TestResult {
+        let error = ErrorPayload {
+            code: "extension_error".to_owned(),
+            message: "boom".to_owned(),
+            retryable: false,
+            data: Some(serde_json::json!({"path": "x.ts"})),
+        };
+        let frame = Frame::error_frame(9, Method::ExtensionError, &error)?;
+        let line = encode_frame_string(&frame)?;
+        let decoded = decode_frame_str(line.trim_end())?;
+        assert_eq!(from_payload::<ErrorPayload>(&decoded.payload)?, error);
+        Ok(())
+    }
+
+    #[test]
+    fn shared_fixtures_field_and_discriminant_parity() -> TestResult {
+        let mut count = 0usize;
+        for line in FIXTURES.lines() {
+            if line.trim().is_empty() || line.trim_start().starts_with('#') {
+                continue;
+            }
+            let frame = decode_frame_str_strict(line)?;
+            let encoded = encode_frame_string(&frame)?;
+            let again = decode_frame_str_strict(encoded.trim_end())?;
+            assert_eq!(again, frame);
+            let method = frame.method_enum();
+            assert!(method.is_some(), "strict decode accepted unknown method");
+            assert!(method.is_some_and(|method| Method::ALL.contains(&method)));
+            count += 1;
+        }
+        assert!(count >= 8);
+        Ok(())
+    }
+
+    #[test]
+    fn eight_mib_limit_constant_and_encode_guard() {
+        let frame = Frame {
+            id: 1,
+            kind: FrameKind::Req,
+            method: Method::Notify.as_str().to_owned(),
+            payload: serde_json::json!({"blob": "x".repeat(MAX_FRAME_BYTES)}),
+        };
+        assert_eq!(encode_frame(&frame), Err(ProtocolError::FrameTooLarge));
+    }
+
+    #[test]
+    fn hyperlink_validation() -> TestResult {
+        Hyperlink {
+            id: None,
+            uri: "https://ok".to_owned(),
+        }
+        .validate()?;
+        assert!(
+            Hyperlink {
+                id: None,
+                uri: "javascript:alert(1)".to_owned(),
+            }
+            .validate()
+            .is_err()
+        );
+        assert!(
+            Hyperlink {
+                id: Some("a".repeat(Hyperlink::MAX_ID_BYTES + 1)),
+                uri: "https://ok".to_owned(),
+            }
+            .validate()
+            .is_err()
+        );
+        Ok(())
+    }
+
+    #[test]
+    fn extension_control_payloads_roundtrip() -> TestResult {
+        let flags = FlagsSetRequest {
+            values: BTreeMap::from([
+                ("plan".to_owned(), FlagValueWire::Boolean(true)),
+                (
+                    "profile".to_owned(),
+                    FlagValueWire::String("fast".to_owned()),
+                ),
+            ]),
+        };
+        let payload = to_payload(&flags)?;
+        assert_eq!(from_payload::<FlagsSetRequest>(&payload)?, flags);
+
+        let shortcut = ShortcutExecuteRequest {
+            key: "ctrl+alt+p".to_owned(),
+        };
+        let payload = to_payload(&shortcut)?;
+        assert_eq!(from_payload::<ShortcutExecuteRequest>(&payload)?, shortcut);
+
+        let ui = UiEventRequest {
+            key: "overlay.1".to_owned(),
+            generation: 2,
+            event: UiEventWire::Paste {
+                text: "hello".to_owned(),
+            },
+            data: Some("hello".to_owned()),
+        };
+        let frame = Frame::request(9, Method::UiEvent, to_payload(&ui)?);
+        let decoded = decode_frame_str(encode_frame_string(&frame)?.trim_end())?;
+        assert_eq!(from_payload::<UiEventRequest>(&decoded.payload)?, ui);
+        Ok(())
+    }
+}