Skip to content

protocol-v1.md

Latest commit

 

History

History
49 lines (32 loc) · 1.66 KB

protocol-v1.md

File metadata and controls

49 lines (32 loc) · 1.66 KB
Raw

Protocol v1

Protocol v1 is UTF-8 NDJSON over stdin/stdout. Each line contains exactly one request or response. Standard error is never part of the protocol.

Lifecycle

  1. Client sends hello with protocol_version = 1.
  2. Host responds with its version and capabilities.
  3. Client creates one surface.
  4. Client submits monotonically increasing frame identifiers.
  5. Client sends shutdown and waits for ack.

Only one surface is supported in the first implementation. The identifiers and message shape already allow multiple surfaces in a later host release.

Commands

Frames contain an ordered commands array. Supported v1 operations are:

  • background
  • fill, stroke, no_fill, no_stroke
  • stroke_weight
  • circle, ellipse, rect, line

Coordinates and dimensions are 32-bit floating-point values in renderer pixels. Colors use normalized RGBA channels from 0 through 1. Dimensions cannot be negative and all floating-point values must be finite.

Errors

Errors are ordinary responses:

{"type":"error","code":"invalid_state","message":"frame requires an active surface"}

Expected codes in v1:

  • invalid_json
  • invalid_request
  • invalid_state
  • unsupported_protocol
  • unknown_surface
  • renderer_error
  • message_too_large

An error does not terminate the host unless the client subsequently requests shutdown or the transport closes.

Performance evolution

NDJSON is the control-plane and correctness format. Before large drawings or pixel transfer are supported, the protocol will add negotiated binary frame payloads. A frame remains the unit of batching and acknowledgement so clients never send one IPC message per primitive.