blockether.vis.views

Immutable input-form, live-view and view-event records.

For reading receipts, see the Sessions API guide. For creating interfaces, use the human-input guide or live-view guide.

@dataclass(frozen=True, slots=True)

class InputView(_ViewRecord):

An open input form, including its component tree and engine-owned timeout metadata.

This describes the form, not a person's answers. Public close events do not include submitted values. Those values belong to the waiting extension. origin names the session that asks and, for a child session, its parent session.

InputView( id: str, title: str, nodes: tuple[Mapping[str, typing.Any], ...], submit_label: str, cancel_label: str, is_cancellable: bool, timeout_ms: int, created_at: int, description: str | None = None, source: str | None = None, session_id: str | None = None, origin: Mapping[str, typing.Any] | None = None)

id: str

title: str

nodes: tuple[Mapping[str, typing.Any], ...]

submit_label: str

cancel_label: str

is_cancellable: bool

timeout_ms: int

created_at: int

description: str | None

source: str | None

session_id: str | None

origin: Mapping[str, typing.Any] | None

Inherited methods and attributes

@classmethod

def from_wire(cls, value: Any):

Validate a raw mapping and return an immutable record.

Raises:

ValueError: The mapping does not match this record's View schema.

def to_wire(self) -> dict[str, typing.Any]:

Return a fresh JSON-compatible copy, including nested mappings and lists.

@dataclass(frozen=True, slots=True)

class LiveView(_ViewRecord):

An open live interface at sequence seq, with immutable semantic nodes.

In your consumer, apply later LivePatch operations in sequence order. This snapshot does not change itself when another event arrives.

LiveView( id: str, title: str, nodes: tuple[Mapping[str, typing.Any], ...], timeout_ms: int, channel_ids: tuple[str, ...], seq: int, created_at: int, description: str | None = None, source: str | None = None, session_id: str | None = None, owner: Mapping[str, typing.Any] | None = None, placement: str | None = None, key: str | None = None, extension: str | None = None, is_stale: bool | None = None, submissions: tuple[Mapping[str, typing.Any], ...] | None = None, is_archived: bool | None = None, is_closed: bool | None = None)

id: str

title: str

nodes: tuple[Mapping[str, typing.Any], ...]

timeout_ms: int

channel_ids: tuple[str, ...]

seq: int

created_at: int

description: str | None

source: str | None

session_id: str | None

owner: Mapping[str, typing.Any] | None

placement: str | None

key: str | None

extension: str | None

is_stale: bool | None

submissions: tuple[Mapping[str, typing.Any], ...] | None

is_archived: bool | None

is_closed: bool | None

Inherited methods and attributes

@classmethod

def from_wire(cls, value: Any):

Validate a raw mapping and return an immutable record.

Raises:

ValueError: The mapping does not match this record's View schema.

def to_wire(self) -> dict[str, typing.Any]:

Return a fresh JSON-compatible copy, including nested mappings and lists.

@dataclass(frozen=True, slots=True)

class ViewSnapshot(_ViewRecord):

A view document kept after close, without open-session IDs or timeout metadata.

ViewSnapshot( title: str, nodes: tuple[Mapping[str, typing.Any], ...], description: str | None = None)

title: str

nodes: tuple[Mapping[str, typing.Any], ...]

description: str | None

Inherited methods and attributes

@classmethod

def from_wire(cls, value: Any):

Validate a raw mapping and return an immutable record.

Raises:

ValueError: The mapping does not match this record's View schema.

def to_wire(self) -> dict[str, typing.Any]:

Return a fresh JSON-compatible copy, including nested mappings and lists.

@dataclass(frozen=True, slots=True)

class LivePatch(_ViewRecord):

Ordered semantic updates for view_id, ending at sequence seq.

The containing ViewEvent.first_seq identifies the first sequence covered by a patch event. Operations remain immutable schema-validated mappings.

LivePatch(view_id: str, seq: int, ops: tuple[Mapping[str, typing.Any], ...])

view_id: str

seq: int

ops: tuple[Mapping[str, typing.Any], ...]

Inherited methods and attributes

@classmethod

def from_wire(cls, value: Any):

Validate a raw mapping and return an immutable record.

Raises:

ValueError: The mapping does not match this record's View schema.

def to_wire(self) -> dict[str, typing.Any]:

Return a fresh JSON-compatible copy, including nested mappings and lists.

@dataclass(frozen=True, slots=True)

class InputResult(_ViewRecord):

Public close receipt. Submitted values belong only to the waiting extension.

InputResult(reason: str)

reason: str

Inherited methods and attributes

@classmethod

def from_wire(cls, value: Any):

Validate a raw mapping and return an immutable record.

Raises:

ValueError: The mapping does not match this record's View schema.

def to_wire(self) -> dict[str, typing.Any]:

Return a fresh JSON-compatible copy, including nested mappings and lists.

@dataclass(frozen=True, slots=True)

class LiveResult(_ViewRecord):

A live interface's final outcome and the optional view document kept after close.

Check is_completed and reason. Do not assume that every close succeeds. is_from_human tells a person's close from a programmatic one. view, summary, error and attachment metadata can be absent.

view_id: str

is_completed: bool

reason: str

is_from_human: bool

view: ViewSnapshot | None

note: str | None

elided: tuple[Mapping[str, typing.Any], ...] | None

summary: str | None

artifact_id: str | None

error: str | None

@classmethod

def from_wire(cls, value: Any) -> LiveResult:

Validate a close receipt and decode its optional ViewSnapshot.

Raises:

ValueError: The receipt or its view document does not match the View schema.

Inherited methods and attributes

def to_wire(self) -> dict[str, typing.Any]:

Return a fresh JSON-compatible copy, including nested mappings and lists.

@dataclass(frozen=True, slots=True)

class ViewEvent:

Typed payload of view.open, view.patch or view.close, not its SSE envelope.

kind: str

view_id: str

view: InputView | LiveView | None

patch: LivePatch | None

result: InputResult | LiveResult | None

first_seq: int | None

@classmethod

def from_wire(cls, event_type: str, value: Any) -> ViewEvent:

Decode a View event payload, separate from its stream envelope.

Arguments:

event_type: "view.open", "view.patch" or "view.close".
value: The corresponding JSON payload, including its kind and view ID.

Raises:

KeyError: The event type is unsupported.
ValueError: The payload, view identity or patch sequence is invalid.

def to_wire(self) -> dict[str, typing.Any]:

Return this typed View payload as fresh JSON-compatible data.