hotty conformance vectors

vectors.json is what a host and an SDK must do, as data.

The host sections (vectors, wire) are run by two hosts that share no code:

• hotty-blitz: crates/hotty-blitz/tests/conformance.rs, which runs the keys, keymap and edit sections too, the edits on a real surface;
• xterm-addon-hotty: tests/e2e/conformance.spec.ts and tests/unit/conformance.test.ts (with keys, keymap and edit).

hotty-go's test host runs vectors too (hottytest/conformance_test.go).

The SDK sections (wire, build, encode, decode, scan, detect, keys, keymap, edit; SDK.md §5) are run by:

• the Python client: clients/python/test_vectors.py, every section;
• hotty-go: hotty_test.go (wire), vectors_test.go (build, encode, decode, scan, detect, keys, keymap) and hottyedit/field_test.go (edit);
• hotty-lua: tests/vectors.lua, every section, under each of its runtimes.

The Python client and hotty-lua count code points, not grapheme clusters (SDK.md §4.6), and skip the vectors that require graphemes.

A disagreement is either a bug or a line of SPEC.md or SDK.md that says too little.

Format

{ "version": "0.4",
  "vectors": [ { "name": …, "steps": [ step, … ] } ],
  "wire":    [ { "name": …, "stream": …, "commands": [ … ], "invalid": n } ],
  "build":   [ … ], "encode": [ … ], "decode": [ … ], "scan": [ … ],
  "detect":  [ … ] }

Numbers. A number in a body has a type (SPEC §3.3). In this file, a number written with a fraction or an exponent (720.0) is a float, and any other an int, so {"w": 720.0} is not matched by an int 720. A host's runner reads the file keeping the two apart: Python's json does, Go's with UseNumber, Rust's serde_json (is_f64), and JavaScript's JSON.parse with a reviver that reads the source text.

Each vector starts on a fresh host, with mod ctrl and the default edit shortcuts (SPEC §10.2, §10.4), whatever its platform. A vector with "requires" applies only to a host that has what it names, and others skip it. A list names several, all required:

• a feature (SPEC §4): "passthrough" (§9.3), "hover" (§9.4), "count" (§9), "menu" (§10.7);
• "touch", a host that takes touch (SPEC §9.1, §16);
• "commands", a host with a terminal that takes edit commands (§10.6);
• "mouse", a host with a terminal that reports the mouse (§9.6), whose runner tells what it reported (Touch, below);
• "undo", a host whose text fields keep a history and cut (§10.2);
• "pressed", a host that sees the key the user pressed (§10.4): its runner offers a key step's key as pressed, by both its names, and then as the bytes a terminal sends for it, as the host would;
• "scroll" (§5.3), "steps", "drop" (§9.1) and "view" (§9.5): what every host of this version does, named so that a host that lays nothing out, an SDK's test host (SDK.md §4.4), skips it. Nor do test hosts keep a history, so they skip "undo".

Its steps come in seven kinds.

Send { "send": {control}, "payload": text?, "body": value?, "reply": …, "events": … }: the command goes to the host as the program would send it. It is base64-encoded and chunked as needed. payload is UTF-8 text; body is a msgpack body (a delta's ops, a menu), as JSON: the runner writes it as msgpack, its numbers as Numbers (above) say, and sends that.

• "reply" absent: replies are not checked.
• "reply": null: the command must produce no reply.
• "reply": {…}: the first reply (a=ok or a=err) must match. Every key but code, detail, body and types is compared with the reply's control, and one whose value is null must be absent from it; code and detail with the body of an a=err. body gives fields the body of an a=ok must have, equal as values (Numbers, above); fields it does not name are not checked. types gives the type of each field of the body (SPEC §3.3): "int", "float", "str", "bool", [T] an array of T, {"name": T, …} a map with those fields, and {"*": T} a map of any names to T. The body must decode (SDK.md §3.9) and each field it has be of its type; a field it lacks, or one types does not name, is not checked.
• "events": the events the command makes the host send, as for a pointer step (below). Some follow the command by a frame or a load (fit, SPEC §5.2), so a runner waits for them, and then a frame or two more to see one too many.

Inspect { "inspect": [surface, id], "expect": … }: the host reports the element as the program wrote it:

• tag;
• attrs: the attributes, with the program's values (a cid: URL stays cid: whatever the host loads);
• text: the text content;
• children: the child elements as [tag, id or null, text].

"expect": null means there is no such element. Otherwise every key of expect must equal the reported value exactly (keys it leaves out are not checked).

Pointer { "pointer": "move" | "down" | "up" | "leave", "s": surface, "at": …, "keys": [ … ], "events": [ … ] }: a mouse, as the user would move it (SPEC §9.1, §16).

• "move" puts the pointer on surface s at at: an element's id, for the centre of its box, or [c, r], for the centre of that cell of the surface, counted from its top left cell (§9.1). A cell can lie outside the window, outside the surface, and over another surface. Moving onto another surface s, with no button down, takes the pointer off the one it was on, as a terminal does: that one is left first (SPEC §9.4).
• "down" and "up" press and release the primary button where the pointer is.
• "wheel" turns the wheel where the pointer is, by "by": [c, r], columns and rows of the surface (positive: right and down), a cell's pixels each. It is one gesture: a runner may send it as several wheel events (a browser scrolls no more than a page for one), lets what it scrolls come to rest before the step's events are read, and lets the gesture end before the next step, so each wheel step is a gesture of its own.
• "leave" takes the pointer out of the terminal's window.
• "keys": the modifier keys held during the step (shift, ctrl, alt, super); none when absent.
• "count", for "down" and "up": the platform's count of this press and its release in a run of clicks, as an OS hands it over with them (macOS's clickCount, GTK's n_press, the DOM's detail); 1 when absent. A runner gives it to the host as the host's platform would.
• "through": true if the step passes through the surface (SPEC §9.3), false if the surface gets it. Absent: not checked.
• "terminal", for a wheel: true if the gesture went on to the terminal, as over the cells beneath (SPEC §9), false if it did not (the document scrolled, or overscroll-behavior stopped it, §5.3). Absent: not checked.
• "events": every event (a=ev) the step makes the host send, in order, and nothing more. Each is compared as a reply is: every key but detail with the event's control, null for a key it must not have ("t": null: the event names no element, SPEC §9), and detail, when present, with its body, decoded: equal as values, each of its type (Numbers, above), and null when the event has none. Absent: events are not checked.

Touch { "touch": "down" | "move" | "up", "s": surface, "at": …, "keys": [ … ], "terminal": …, "mouse": …, "events": [ … ] }: one finger, as the user would touch the terminal (SPEC §9.1, §9.6, §16). "down" touches surface s at at, a cell [c, r] as for a pointer step, or, without s, the cells: the screen's cell [c, r], counted from 0 at its top left. "move" moves the finger to at, in moves of a runner's choosing, along the straight line from where it was, so it passes the host's tap slop in that line's direction (the vectors move along a row or a column, so where the finger enters an element does not depend on those moves); "up" lifts it. "keys" are the modifier keys held, as for a pointer step. "terminal", for a move: true if the touch went on to the terminal as a scroll (SPEC §9), false if the surface or the program's mouse took it (§9.6); absent, not checked. "mouse": what the terminal reported of the mouse's primary button for the step (§9.6), each [kind, c, r], kind "down", "move" or "up" on the screen's cell [c, r], counted from 0; [] for nothing, and absent, not checked. How many moves it reports depends on the runner's moves, so a runner compares the two lists keeping only the last move of each run of moves in each. "events" as for a pointer step: what the step makes the host send.

Key { "key": name, "keys": [ … ], "terminal": …, "events": [ … ] }: a key pressed and released where the keyboard is (SPEC §10): on the surface that has it, or else on the terminal. name is the key as the DOM's KeyboardEvent.key has it ("Enter", "Tab", "End", "ArrowDown", "B"), on a US layout, where its physical key is the one a US keyboard has it on. "keys" are the modifier keys held, as for a pointer step. The host names the key as SPEC §10.4 does. A runner that gives the host keys by name names them so; one that presses keys on a terminal gets them from the terminal's encoding, which, for the keys the vectors press, names the same key, but the physical name of a character's key (ctrl+key_w, beside ctrl+w). "terminal": true if the key reached the program as terminal input (§10.2), false if the surface used it; absent, not checked. "events" as for a pointer step.

Write { "write": text }: the program writes text to the terminal, bytes that are not hotty's. The vectors write CSI ? 1002 h and CSI ? 1006 h together, so that the terminal reports the mouse's buttons and drags in the SGR encoding, CSI ? 1002 l, so that it reports them no longer, and CSI ? 1049 h and CSI ? 1049 l, the alternate screen and back. A runner whose host has no terminal of its own does to the host what a terminal does on these.

Menu { "menu": "shown" | "pick", "expect": …, "name": str, "events": [ … ] }: the program's menu, in a host that has menu (SPEC §10.7, §16).

• "shown": the level the host shows, once any wait it makes before showing one has passed. "expect" is its items in order, each {"key", "label", "group", "enabled"}: the item's key and label as the program sent them, whether it is a group, and whether it is enabled; null when none shows.
• "pick": the item named "name" is picked, as from a multiplexer's palette or a command palette the host already has. A host that offers no picks skips the vector. "events" as for a pointer step: what the pick makes the host send, [] for nothing.

The documents of pointer steps size their elements in cells (--hotty-cell-w, --hotty-cell-h, SPEC §8), and point at centres that lie well inside a cell, so the cell reported is the same on every host. Wheels and keys scroll a document to an end, or bring an element into view where any alignment ends at the same offset, never by a distance: how far a wheel's notch or an arrow key moves differs between hosts.

A host never compresses what it sends (SPEC §3.3): a runner checks that no reply or event it reads carries o.

Wire vectors check the envelope alone. The stream (JSON-escaped bytes) must decode into commands: listed control keys equal, m and o never present, and the payload is UTF-8 text. It must also report invalid malformed or interrupted commands.

The vectors check the document, the events and the wire, not pixels (§5.3: pixels may differ between hosts).

The SDK sections

They check an SDK's wire layer (SDK.md §3). Names in them are canonical, in snake case (SDK.md Appendix A): a runner maps set_text, keep_cursor and fit_rows to its own. Strings are the UTF-8 of the JSON string. null means absent: Go's zero value, Python's None. A vector with "requires" applies to an SDK that implements what it names; a runner declares what it implements, and skips the rest:

Build { "build": builder, "args": {…}, "options": {…}?, "out": [ … ] }: the runner calls the builder with args, and with the reply options n and q, detached, scroll and late from options, which have no order. sync takes args.commands, each a { "build", "args", "options" } of its own. The output, split into raw bytes and hotty sequences, must be out:

• { "raw": text }: bytes that are not hotty's, such as PlaceAt's cursor moves, Query's DA1 and Sync's brackets;
• { "cmd": { "control": {…}, "payload": text? } }: one command, decoded. Its control has exactly these keys (m and o never), and its payload is this text, empty when absent, or the bytes of "payload_b64": a delta's or a menu's msgpack, which "body" shows as JSON, as a Decode vector's bodies do (below), and runners ignore.

Encode { "control": [[key, value], …], "payload": text | "payload_b64": …, "bytes"?: text, "chunks"?: [ { "control": text, "len": n } ] }: the runner calls Encode with the control in that order. With bytes, the output must be exactly that: these are payloads that cannot be compressed, under 256 bytes or random. With chunks, it is split into sequences, and each one's control (between ESC ] 7279 ; and ;) and base64 length must match. Every case must also decode back to the payload, with the control's keys in order, but m and o, which are Encode's (SDK.md §3.3).

Decode { "seqs": [ text, … ], "bodies"?: [ … ], "max"?: n, "results": [ … ], "invalid": n, "messages": [ … ] }: each sequence goes to one Decoder's Feed, in order. max, when present, is the Decoder's Max (SDK.md §3.6). results are its results (not_hotty, partial, complete, invalid), and invalid its count after the last. messages are the complete ones, in order:

• control: exactly these keys and values;
• reply: Reply's fields (ok, re, n, surface, cols, rows, code, detail, op);
• event: Event's fields and accessors (surface, kind, target, value, checked, fields as a list of [name, value], mods, link with href and url, fit_rows, drag with c, r, x, y, tx and ty, hover with c, r and out, area, count, view with areas and at_end, command with name, key, text and has_text);
• changed: a caps event's Changed, with fields the names of exactly the fields it has, as the body names them (cellcss), and those fields as caps checks them;
• caps: Caps's fields (cell_css with w and h, features), and its answers: has maps a feature to the answer, and light. null: the reply carries none, as when its body does not decode.

Only the keys listed are checked, but view's areas, which is compared whole: the same ids, each with the same area. Numbers compare as numbers.

A host's body in the sequences is msgpack in base64, which no one reads, so bodies shows them as JSON (Numbers, above), one for each sequence:

• the body of the message the sequence starts, its maps in their order;
• null where the sequence starts no message, or one with no body;
• {"hex": …} for bytes the script below does not write: a body that is not one msgpack value, one in another of its types' forms than the smallest (an int wider than it needs, a float of 32 bits), or one holding what no host sends (a nil, a key that is not a string, an extension).

Runners ignore it. scripts/bodies.py writes the base64 in seqs from it, splitting a chunked body where its chunks split it before, and a Build vector's payload_b64 from its body, and with --check fails when they differ. The vector about base64 itself writes its sequences by hand, and has no bodies.

Scan { "stream": text, "segments": [ … ], "held"?: text, "flush"?: [ … ], "invalid"?: n }: the stream goes to a Scanner, which looks for DA1 answers only when the vector requires scanner.da1. The runner feeds it whole, cut in two at every offset (or, in a long stream, at every offset near its ends and at a stride between), and a byte at a time; each time, the segments must be segments (adjacent pass segments merged), what it holds after the stream held (none when absent), what Flush returns flush (none when absent), and its count of dropped sequences invalid (0 when absent). A segment is { "pass": text }, { "osc": text } or { "da1": text }.

Keys checks key names (SPEC §10.4, SDK.md §3.10), in four forms:

• { "input": text, "keys": [ … ] }: DecodeKeys(input) must return keys, one entry for each key, null for input that is no key;
• { "key": text, "canon": text | null }: ParseKey(key) must return canon, null when the name does not parse. These are myelin key names 0.1's read vectors (its conformance/keys.json), as they are;
• { "key": text, "mod": "ctrl" | "super", "canon": text | null }: ReadKey on a Platform whose mod is mod must return canon, null when the name does not parse. These are myelin key names 0.1's mod vectors that set no other option (strict reading or shifted capitals, which §10.4 does not use), as they are;
• { "key": text, "text": text | null }: KeyText(key) must return text, null for none.

Keymap checks keymaps (SPEC §10.2, SDK.md §3.10), each on the Platform in "platform": { "mod"?, "edit"? }, the zero Platform (ctrl, the default edit shortcuts) where absent, in three forms:

• { "parse": text, "format": text }: ParseKeymap(platform, parse).Format() must be format; with "terminal_keys": true and no parse, TerminalKeys formatted must be format;
• { "multiline": bool, "terminal_keys"?: true, "keys": [ … ], "lookup": { key: action | null } }: Resolve(platform, multiline, …) with TerminalKeys first when terminal_keys is true, then each of keys. Lookup of each key of lookup must return its value: an action, "insert", or null when the key is not the field's. Selects of each key of selects, and Binds of each key of binds, if there is one, must return its value;
• { "keys": [ … ], "program"?: { key: bool }, "prefix"?: { key: bool }, "scroll"?: { key: action | null } }: an element's keymap outside a text field, with no default keymap: ParseKeymap of keys joined with a space, the root's first. Program of each key of program, Prefix of each key of prefix, and Scroll of each key of scroll, must return its value, null for none.

Edit { "field": { "value", "caret", "anchor"?, "multiline"?, "password"?, "rows"? }, "steps": [ … ] }: a Field (SDK.md §4.6) made from field, absent keys false, 1 for rows, and nothing selected when there is no anchor. Each step is { "do": action }, { "extend": action }, { "type": text } or { "select": [anchor, caret] }, and after it every key the step lists must equal the Field's: value, caret and anchor (in characters; with nothing selected, the anchor is the caret), and changed, what Do, Extend or Type returned (false for select). "requires": ["graphemes"] marks the vectors whose text has a character of more than one code point, other than CR LF.

Detect { "n"?: n, "late"?: true, "steps": [ … ], "caps"?: {…} }: one Detector, with the query's number n (1 when absent), asking for a late answer when late is true. Each step happens at time at, in milliseconds, and is one of start, da1, osc (a sequence, decoded, and given to Reply; its body shows the body, as a Decode vector's bodies do, and runners ignore it), tick and end. After each, every key the step lists must equal the Detector's: took (what DA1 or Reply returned), state (detecting, native, text), decided, done, and deadline (null when there is none). caps is checked against the capabilities at the end; null: there are none, as when the terminal is no host the program can use.