Text-entry surface survey (2026-07-29)

Phase 1 of the hardware text-entry interaction design. This document enumerates every KN-86 surface that accepts operator-authored characters, records what alphabet each one needs, and states the constraints a single interaction model has to satisfy. It selects nothing. Candidate interaction models are judged in the kn86-textentry workbench (Phase 2); the selected model and its seam land as an ADR (Phase 3).

Governing documents: ADR-0016 §6 to §9 (the multi-tap model, the prompt-text FFI, the tap / double-tap / long-press event model), ADR-0044 (the current three-layer keyboard authority), ADR-0046 (programs as major modes), ADR-0042 (the program roster), and the Canonical Hardware Specification (key count and layer model).

1. The character path as built

Two paths reach a composer today, and they share nothing.

Path A, the emulator character path. A screen registers a one-argument handler in a registry separate from the render / on-key registry:

SDL_EVENT_TEXT_INPUT                        hosts/emulator/src/main.c:613
  -> nosh_host_handle_char(ch)              runtime/src/nosh_host.c:1032
  -> screen_router_handle_key(rt, KN86_KEY_NONE, ch)
  -> (deck/dispatch-char name ch)           runtime/src/sys_screen.c:139
  -> the screen's registered handler        runtime/system-image/lib/deck.lsp:131

Three screens register a handler: the REPL (repl/input-putc, runtime/system-image/lib/repl/repl.lsp:406), AmberCalc (runtime/programs/ambercalc/ambercalc.lsp:1283), and CALC (runtime/programs/calc/calc.lsp:502). The registry is gated on screen_router_is_active, so the path exists for system screens and programs and never for carts.

Path B, the multi-tap machine. runtime/src/nokia.c is the ADR-0016 §6 state machine: digits 2 to 9 cycle letters, 0 commits a space, 1 cycles . , ' " : ; !, / shifts case, * deletes, ENT commits, and a 600 ms dwell (NOKIA_COMMIT_TIMEOUT_MS) auto-commits the pending letter. The module is pure: the caller owns a NokiaState and supplies every timestamp.

Two callers own an instance:

Owner	Instance	Reached from Lisp as
runtime/src/nemacs.c:125	g_nemacs.nokia	nothing program-agnostic; drives :nemacs-literal scope and the prompt-text modal
runtime/src/deck_aux.c:67	g_aux.nokia	deck/oobe-press!, deck/oobe-tick!, deck/oobe-handle, deck/oobe-handle-len, deck/oobe-pending

Two further files touch the machine without owning one: runtime/src/dev_overlay.c:313 reads nemacs’s instance through nemacs_nokia_state_const() for a debug readout, and runtime/src/input.c:297 gates double-tap synthesis on numpad keys while multi-tap scope is active (input_set_suppress_double_tap).

The cart-facing seam that already exists. (prompt-text "label" max-len) is bound in the cart FFI bridge (runtime/src/nosh_lisp_bridge.c:3920) and runs a blocking modal: the host pumps its own event loop, feeds keys through nemacs_literal_keypress, echoes on CIPHER-LINE Row 4, and returns the string or nil on cancel (hosts/emulator/src/main.c:523). No cart calls it. Grepping carts/ for prompt-text returns nothing.

2. The gap

Path A carries letters and is fed only by SDL_EVENT_TEXT_INPUT. Path B carries letters from the physical keyboard and is reachable from Lisp only under deck/oobe-* names. The two never meet, so no program can accept letters on the deck.

The keyboard makes the gap concrete. Under ADR-0044 the printed L0 and L1 layers carry digits, the five punctuation primaries, the function block, and the KEC punctuation set. Neither printed layer carries a letter. The unprinted L2 (§4) carries the rare ASCII tail and no letters either. Letters exist on the deck in exactly one place: the ADR-0016 §6 digit-to-letter binding that nokia.c implements.

A second defect follows from the same split. The QMK keymap emits real letter scancodes for the function block (KC_Q for QUOTE, KC_W for CONS, and so on; hosts/device/firmware/keyboard/keymap.c:161), and runtime/src/input.c remaps those scancodes to KN86_KEY_QUOTE / KN86_KEY_CONS. Text input is started whenever a composer screen is active (runtime/src/nosh_host.c:598). On the device, one press of QUOTE therefore delivers both a KN86_KEY_QUOTE dispatch and a TEXT_INPUT character q into the composer. On hardware Path A carries the wrong letters. Any selected model has to state which path owns characters on the device, and close the other.

That keymap is also pre-ADR-0031: it encodes the retired 31-key matrix with a single _BASE layer, no SHIFT layer, and no L2. The Sweep retarget is a separate open piece of work and is a dependency of any candidate that puts letters in firmware.

3. Per-surface survey

Columns: alphabet is the smallest character set the surface has to accept; length is the typical committed field; carried by records whether ranked completion, history, or a fixed grammar can do most of the work instead of per-character entry; typing is whether entry is the primary interaction of the surface or an occasional one.

3.1 First-party programs (runtime/programs/, ADR-0042 roster)

Program	What gets typed	Alphabet	Length	Carried by	Typing
ambercalc	cell literals, @row$col refs, formulas (ADR-0049)	digits, @ $ . + - * / ( ), uppercase letters for function names	3 to 24	grammar: refs and operators are structural, function names are a closed set	primary
calc	RPN number entry	digits, ., sign	1 to 12	nothing; numeric only	primary
conduit	endpoints, credentials, then arbitrary remote shell commands	full ASCII	4 to 60	history repeats the session; the dialer is a closed endpoint set; credentials come from Keyring	primary, and the hardest program case
bzbx	a filter grammar over hosts and captures, hostnames	lowercase letters, digits, . : / >	4 to 24	completion over the scanned host list; the filter keys are a closed set	occasional
kommander	path fragments for find and filter	lowercase letters, digits, . / _ -	3 to 32	completion over the mount index (kommander/find-index) does nearly all of it	occasional
ripsaw	entity-name queries	uppercase letters, digits, space	3 to 24	completion over ripsaw/entity-names; ido-style narrowing	occasional
kn9	search over from and subject	letters, digits, @ . -	3 to 24	completion over kn9/search-index	occasional
keyring	key labels, method and lock selection	uppercase letters, digits, -	4 to 16	selection is completing-read; only a new label is free text	occasional
dossier	nothing today; browse only	none	0	index navigation	none
trace	nothing; pursuit grid	none	0	key verbs	none
echo	operator utterances addressed to CIPHER	full ASCII, sentence-shaped	10 to 80	nothing; free prose is the point	primary, and the longest fields on the deck
knamp	nothing today; station browse and tune	none	0	list selection	none

Six of the twelve need no character entry at all or need it only through completion. The four narrowing programs (bzbx, kommander, ripsaw, kn9) all reach text through completing-read over an index the program already holds, which is the same shape in every one of them. CONDUIT and ECHO are the two surfaces where free characters are the interaction rather than a way to filter a list.

3.2 System-image libraries (runtime/system-image/lib/)

Surface	What gets typed	Alphabet	Length	Carried by	Typing
REPL	arbitrary KEC Lisp forms	full ASCII including every KEC punctuation character	5 to 70	history ring, token prediction (ADR-0009), the TERM command palette	primary; the hardest case on the deck
nEmacs	symbols and literals inside a structure editor	full ASCII, Lisp-symbol shaped	3 to 40	structural editing supplies the parens; prediction supplies the symbol	primary
deck (OOBE)	the operator handle	uppercase letters, digits	1 to 12 (DECK_AUX_HANDLE_MAX)	nothing; a name is a name	once per device
mission board	nothing; offers are selected	none	0	list selection	none

The REPL sets the ceiling. Anything that can type an idiomatic KEC form can type everything else on the deck, which is why the REPL is the acceptance surface for the selected model rather than a special case bolted on afterward.

3.3 Cartridges (carts/carts/)

None of the five shipped carts (snake, icebreaker, neongrid, depthcharge, blackledger) accepts characters. Three constraints make a cart’s entry surface narrower than a program’s:

• The cart context binds one library. cartridge.c embeds ui/ui/draw.lsp only (runtime/src/cartridge.c:37). A cart cannot compose ui/field, ui/palette, or any other System-tier component, because render/* is unbound in a cart context by design. A cart-tier field has to be drawn through the cell-* tier or drawn for the cart by the runtime.
• A cart has no clock. Nothing in the cart tier reads monotonic time, so a cart cannot drive a dwell timeout itself. nokia_tick needs a timestamp from a caller that has one.
• Row 0 and Row 74 are runtime-owned. A cart draws Rows 1 to 73, so an entry field that wants chrome rows has to be composed by the runtime on the cart’s behalf.

The consequence: the cart tier wants a runtime-owned modal rather than a component a cart draws itself. prompt-text is already that shape. Whatever model is selected, the cart seam should stay one call that returns a string or nil, with the runtime owning the field, the timing, and the echo.

4. What the survey constrains

1. Three alphabet classes. Numeric-only (calc, ambercalc literals), a closed identifier set reached by narrowing (bzbx, kommander, ripsaw, kn9, keyring), and free ASCII (REPL, nEmacs, CONDUIT, ECHO, the OOBE handle). A model that serves only the third makes the first two slower than they are today; a model that serves only the first two leaves the REPL unusable on hardware.
2. Completion carries the majority of surfaces. Four of the five programs that accept text already narrow a list the program holds. For those, the cost that matters is the cost of the first two or three characters; the twentieth character is never reached.
3. The REPL is the ceiling and the acceptance test. Full ASCII, every KEC punctuation character, and lines up to about 70 characters.
4. The dwell timeout is the weakest part of the shipped machine. The on-glass clock is coarse, and a 600 ms dwell prices every letter that follows a letter on the same key. A model that commits on an explicit key instead of a dwell removes the timing dependency from the interaction and from the tests.
5. Two tiers, one machine. The program tier wants a registered handler and a composed field (Path A’s shape, with a real character source behind it). The cart tier wants a blocking modal (prompt-text’s shape). Both should sit on one instance of the machine behind program-agnostic names, with deck/oobe-* preserved so first boot does not regress.
6. The split across runtime and firmware is a real fork in the design. A model that assigns letters through QMK layers or combos lands in hosts/device/firmware/keyboard/, needs the Sweep retarget first, and changes nothing in the runtime except deleting the multi-tap path. A model that keeps letters in the runtime lands in runtime/src/ and leaves the keymap alone. Candidates state which side they fall on.

5. The candidate set under judgement

Fourteen candidates are staged in the kn86-textentry workbench (port 7731) with a keypad simulator over the ADR-0031 §3.1 L0 manifest, so each model can be typed rather than read about. Twelve are simulatable; the two firmware-layer models are shown as layer maps. Costs are counted uniformly: one press is one key actuation, a shift-layer glyph counts as two, and a dwell wait counts as zero presses and is recorded in the clock column instead.

Code	Model	Lands in	Clock	FLINT	(nil? x)	kx-04.hab
MT-DWELL	multi-tap, dwell commit (as shipped)	runtime	yes	13	19	21
MT-COMMIT	multi-tap, commit key, no timeout	runtime	no	13	19	21
MT-STRICT	multi-tap, uniform commit per letter	runtime	no	18	24	27
PICK-GRID	on-screen glyph grid, cursor-navigated	runtime	no	32	41	46
PICK-2KEY	two-key glyph paging, group then member	runtime	no	11	16	19
PREFIX-ESC	one-glyph punctuation escape (a modifier)	runtime	no	13	17	19
TRACK-WHEEL	trackpoint glyph ring (ADR-0035)	runtime	no	11	19	21
T9-WORD	predictive over a deck dictionary	runtime	no	6	11	10
T9-KEC	predictive over the live KEC symbol table	runtime	no	13	13	21
PALETTE-1ST	completion-first; nothing is ever spelled	runtime	no	13	3	3
QMK-ALPHA	a latched L3 alpha layer, one press per letter	firmware	no	7	10	11
QMK-CHORD	letters from two-key combos on the digit block	firmware	yes	6	10	11
HIST-1ST	history and prediction first (a modifier)	runtime	no	13	4	3
HYBRID	per-tier profiles over one machine	composition	no	-	-	3

Three of these are modifiers rather than whole models (PREFIX-ESC, HIST-1ST, and HYBRID as the composition), and the workbench tags them so their value is not double-counted inside another card.

Two findings came out of building the simulator and belong in the record:

• Committed and pending must never render alike. A dwell commit changes no glyph on screen unless the pending letter is visually distinct, so an operator cannot tell whether the dwell has fired. nokia_pending already exposes the pending character separately from nokia_buffer; the field component has to render the two differently, and the ADR-0016 §6 echo format ([<committed><pending>_]) does not by itself.
• Punctuation-carrying symbols need a digit signature that skips the punctuation. A T9 signature for nil? runs to three digits, because ? sits on no multi-tap table. Any predictive model over the KEC symbol table has to strip unmappable characters when it builds the signature and restore them on acceptance.

6. Open items this survey does not settle

• Which interaction model the deck ships. Judged in the workbench (Phase 2).
• Whether the function block’s letter scancodes (KC_Q and the rest) are remapped in firmware to non-letter codes, or whether text input is gated per surface in the runtime. Both close the spurious-character defect in §2; the selected model decides which.
• The Sweep keymap retarget, a dependency of any firmware-side candidate.