Constrained Cell API

The kn86-nosh-tb runtime exposes a deliberately small KEC Lisp surface for terminal-native cartridges. It is not a raw termbox2 binding. The C runtime owns termbox initialization, shutdown, input modes, cursor state, runtime chrome, and event polling.

engineer maintaining kn86-nosh-tb.

Related:

../../../adr/ADR-0027-termbox2-display-layer.md — decision record and ratification gates.
primitives-by-category.md — full kn86emu NoshAPI surface.
../../runtime/input-dispatch.md — runtime-owned input classification.

Host Contract

kn86-nosh-tb runs on a 128×75 terminal cell grid:

Region	Rows	Owner
Status chrome	`0`	nOSh runtime
Cart/surface region	`1..73`	active cart or runtime surface
Action chrome	`74`	nOSh runtime

Cartridge writes to chrome rows are dropped and counted by the runtime. Out-of-range columns are clipped. The sanctioned palette is amber on black; Lisp code uses color tokens, not termbox attributes.

Draw Primitives

Lisp name	Signature	Returns	Semantics
`cell-set`	`(col row ch fg bg)`	`Unit`	Write one cell. Rows `0` and `74` are rejected as chrome writes.
`cell-print`	`(col row fg bg string)`	`Unit`	Print a string, clipped at the right edge with no wrap.
`cell-clear-cart-region`	`()`	`Unit`	Clear rows `1..73`; chrome rows are untouched.
`cell-cols`	`()`	`Number`	Return `128`.
`cell-rows-usable`	`()`	`Number`	Return `73`.
`half-block-set`	`(x y on)`	`Unit`	Set/clear a sub-cell pixel inside the 128×146 cart canvas.
`half-block-rect`	`(x y w h on)`	`Unit`	Draw a filled rectangle in half-block coordinates, clipped to bounds.
`half-block-clear`	`()`	`Unit`	Clear the cart half-block canvas.
`present`	`()`	`Unit`	Advisory frame-ready marker; the runtime may also present at frame boundaries.
`yield`	`()`	`Unit`	Advisory yield point; the runtime owns actual event polling.

Not exposed to Fe: tb_init, tb_shutdown, tb_clear, tb_set_input_mode, tb_set_output_mode, tb_set_cursor, tb_hide_cursor, tb_poll_event, tb_peek_event, cell inspection helpers, and unchecked chrome writes.

Semantic Callbacks

Cartridges define callbacks as ordinary Fe bindings. The runtime pre-binds each name to nil, so an omitted callback is a silent drop.

Callback	Payload	Semantics
`on-key`	`(key event-type timestamp-ms)`	Classified 31-key event. `key` and `event-type` are numeric enum values from the runtime.
`on-multi-tap`	`(result committed-char timestamp-ms)`	Nokia multi-tap result and current/committed character.
`on-hold`	`(key timestamp-ms)`	Key held past the runtime hold threshold.
`on-resize`	`(width height)`	Terminal resize notification. Mostly desktop/debug; device geometry is fixed.
`on-tick`	`(timestamp-ms)`	Periodic runtime tick. Carts should gate expensive redraws themselves.

Input policy remains runtime-owned. TERM context dispatch, hold timing, double-tap windows, Nokia multi-tap, global chords, and hidden recovery gestures are handled in C before cart callbacks run.

Authoring Notes

The termbox path is useful for new device-first carts because it matches the final hardware shape more closely than the SDL pixel framebuffer. The full kn86emu NoshAPI remains the compatibility surface for launch carts during the ADR-0027 spike, but new terminal-native experiments should start from this constrained API.