Content Representation¶
Field |
Value |
|---|---|
Status |
Draft |
Related RFC |
|
Related drafts |
Operations, Capabilities, Terminal-native behavior, Wire requirements, JSON serialization, Error codes |
This document defines the observable requirements for representing a Block’s content. Content snapshots use the shared JSON serialization, but this document does not yet define a catalog of optional content types.
1. Self-Contained and Declarative¶
A content snapshot describes what a Block contains, not a sequence of drawing instructions. Its meaning does not depend on the global cursor position, screen contents, or terminal state outside that Block.
A content representation cannot move the global cursor, clear the screen, or
modify another Block. Payload data is interpreted only according to its
declared content type; for example, escape sequences in text/plain are not
executed as terminal controls.
2. Single Negotiated Representation¶
Each Block snapshot carries exactly one content representation. Every terminal
that confirms support for the initial protocol version supports text/plain
as the baseline representation. Optional representations are advertised
through capability negotiation, and the TUI selects one that the terminal has
confirmed.
A snapshot does not carry a bundle of alternative representations. The terminal therefore does not choose among alternatives or reconcile multiple versions of the same logical content.
3. Explicit Content Type¶
Each snapshot explicitly declares its content type. The terminal interprets the accompanying data according to that type and does not infer the type by inspecting the payload.
A malformed type field or ContentData value that violates the selected
Message schema reports invalid_message when correlation is reliable. A well-
formed but unknown or unnegotiated type reports unsupported_content_type.
Structurally valid data for a supported type that violates that type’s
additional content-validity rules reports invalid_content. Each failure
leaves the Block’s content and lifecycle unchanged; correlation and ID non-reuse
follow the logical wire model.
The initial JSON mapping represents the type as a non-empty string and defines
text/plain as the baseline identifier. Naming, registration, and schemas for
optional types remain open design questions.
4. Complete Replacement Across Types¶
The content value consists of its type and data. An Update replaces that complete value atomically and may retain the current type or change to another type confirmed during capability negotiation.
The terminal does not convert between content types. A replacement whose new type is unsupported or whose data is invalid fails as a whole, leaving the Block’s previous content unchanged.
5. Incremental Text Operations¶
The initial Extend and ReplaceSuffix Operations apply only to text/plain.
Optional content representations continue to use complete snapshots unless
their own future definitions explicitly add incremental editing semantics.
A ReplaceSuffix position counts Unicode scalar values from the beginning of the current logical text. It is not a UTF-8 byte offset, UTF-16 code-unit offset, terminal cell, rendered column, or grapheme-cluster count. A visual character such as an emoji may therefore contain more than one counted scalar value. The text remains a sequence of valid Unicode scalar values before and after the Operation.
This position is interpreted only against the exact content state declared by the incremental Operation. Resize and reflow do not change it.
6. Terminal-Native Projection¶
Each content type defines the logical semantics that terminal-native capabilities operate on, including layout and reflow, selection and copying, and a searchable text projection. Plain Text Content defines the baseline’s newline, Tab, and visible-control handling without changing its logical content. Richer types may preserve structured rendering while defining their corresponding logical text.
The content type specifies these observable semantics. The terminal retains ownership of how native capabilities are implemented, presented, and executed. Their shared interaction with Block Operations is defined by Terminal-Native Behavior.
Open Design Choices¶
Remaining text-layout boundaries listed in Plain Text Content.
The initial set of optional content types and their schemas.
Content-type naming, registration, and versioning.
Detailed native projections for each optional content type.