Let the console edit a line, and let a file be a keyboard

BACKSPACE REACHED THE SHELL. A terminal in line mode does not hand a program every
keystroke: it collects a line, rubs out a backspace, and delivers the finished thing at
Return. CosmOS has always relied on that, and behind a window there is no terminal to do it,
so the raw 0x08 went into the command buffer. Correcting a typo produced a line that looked
perfectly right on the screen and matched no command at all - "I do not know: help".

So the console does it, because behind a window the console IS the terminal. In key mode it
does not, and must not: a program in key mode asked for every keystroke as it happens.

CosmOS now asks for eighty columns at boot. Its own help text is seventy-four characters
wide, and dir, the monitor and the assembler's messages all assume room. The machine still
wakes up in the smaller mode, which is right for a machine - it is the system that knows
what shape of screen its own output needs, and a game that wants forty columns says so.

AND A FILE CAN BE A KEYBOARD, which is the part that matters beyond today. The console
behind a window is not the console behind a terminal, and until now the difference was
unreachable: it broke twice in two days and a person typing found it both times. --keyboard
installs the same hook a window does, so the same path runs, and the manifest has a column
for it. cosmosTyped types "halp", backs over it, arrives at "help", and requires the help to
come out. Verified by removing the rub-out, which loses the whole help text.

It does not test the window. Voyager's key queue and everything about presenting frames are
still out of reach. It tests the console, which is where the logic is.

Along the way: VOY_OBJS was missing from the dependency include, so voyager.o never rebuilt
when a header changed. EmulatorOptions grew a field, Voyager kept an object that disagreed
about the size of the struct, and smashed its stack on every run. A clean build hides it and
'make sanitize' cleans first, so that would never have found it either. Tests/voyager.sh did,
by failing all 115 tests that start the machine - which is the differential test earning its
keep on a bug that has nothing to do with what it was built to check.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E2JrLzFvuFX9fgi1LDRjrW

Source/Emulator/io.c

@@ -320,6 +320,61 @@ static void consoleDraw(uint8_t byte) {
 // when one is typed, or -1 to say the window has gone.
 static int (*inputHook)(int mayWait) = NULL;
 
+// ---- Line editing, which the terminal used to do ----
+//
+// A TERMINAL IN LINE MODE DOES NOT HAND A PROGRAM EVERY KEYSTROKE. It collects a line,
+// rubs out a backspace, and delivers the finished thing when Return is pressed. CosmOS has
+// always relied on that, and behind a window there is no terminal to do it - so the raw
+// backspace reached the shell, which put 0x08 in its command buffer and then could not find
+// a command by that name. Correcting a typo made the line unrecognisable while looking
+// perfectly right on screen.
+//
+// So the console does it, because behind a window the console IS the terminal. In key mode
+// it does not: a program in key mode asked for every keystroke as it happens, which is the
+// whole point of key mode.
+#define CONSOLE_LINE_BYTES 256
+static unsigned char consoleLine[CONSOLE_LINE_BYTES];
+static int consoleLineLength = 0;
+static int consoleLineAt = 0;
+
+// Collects until Return, echoing as it goes, and leaves the line to be handed out a byte at
+// a time. Returns 0 if the window closed while it was waiting.
+static int consoleGatherLine(void) {
+    consoleLineAt = 0;
+    consoleLineLength = 0;
+    for (;;) {
+        const int got = inputHook(1);
+        if (got == CONSOLE_GONE) {
+            return 0;
+        }
+        if (got < 0) {
+            continue;
+        }
+        if (got == 0x08) {
+            // Nothing to rub out at the start of a line, and rubbing out past it would eat
+            // the prompt, which belongs to whoever printed it.
+            if (consoleLineLength > 0) {
+                consoleLineLength--;
+                consoleDraw(0x08);
+            }
+            continue;
+        }
+        if (got == '\n' || got == '\r') {
+            consoleLine[consoleLineLength++] = '\n';
+            consoleDraw('\n');
+            return 1;
+        }
+        // No room, or nothing a line is made of. A control byte that means something to a
+        // terminal means nothing here yet, and putting it in the line would only hand a
+        // program something it cannot use.
+        if (got < 0x20 || consoleLineLength >= CONSOLE_LINE_BYTES - 1) {
+            continue;
+        }
+        consoleLine[consoleLineLength++] = (unsigned char)got;
+        consoleDraw((uint8_t)got);
+    }
+}
+
 void consoleSetInputHook(int (*hook)(int mayWait)) {
     inputHook = hook;
 }
@@ -337,19 +392,21 @@ uint8_t consoleReadByte(void) {
     }
     consoleShowWhatIsWritten();
     if (inputHook != NULL) {
+        if (!consoleKeyMode) {
+            // A line already gathered is handed out a byte at a time, which is what the
+            // program is asking for. Only when it runs out is another one collected.
+            if (consoleLineAt >= consoleLineLength && !consoleGatherLine()) {
+                consoleEnded = 1;
+                return 0xFF;
+            }
+            return consoleLine[consoleLineAt++];
+        }
         for (;;) {
-            int got = inputHook(1);
+            const int got = inputHook(1);
             if (got >= 0) {
-                // ---- The screen is the terminal now ----
-                //
-                // In line mode a terminal echoes what is typed and rubs out a backspace,
-                // and CosmOS has always relied on that. There is no terminal behind a
-                // window, so the display controller does it - which is exactly the job a
-                // video terminal's character generator had. In key mode nothing echoes,
-                // because a program in key mode is drawing its own screen.
-                if (!consoleKeyMode) {
-                    consoleDraw((uint8_t)got);
-                }
+                // Nothing echoes in key mode: a program that asked for every keystroke as it
+                // happens is drawing its own screen, and marks it did not make would be in
+                // the way.
                 return (uint8_t)got;
             }
             if (got == CONSOLE_GONE) {
@@ -408,7 +465,17 @@ static void consoleFetch(void) {
     // the window happened to be focused. Asked without waiting, because a poll is a poll -
     // the front end presents a frame when the console genuinely blocks, not when it looks.
     if (inputHook != NULL) {
-        int got = inputHook(0);
+        if (!consoleKeyMode) {
+            // READY means there is a byte to be had, and in line mode there is one only
+            // while a gathered line is still being handed out. A poll must not take a key
+            // from under the gatherer, and half a line is not a line.
+            if (consoleLineAt < consoleLineLength) {
+                consolePushback = consoleLine[consoleLineAt++];
+                consoleAnnounce();
+            }
+            return;
+        }
+        const int got = inputHook(0);
         if (got >= 0) {
             consolePushback = got;
             consoleAnnounce();

Source/Emulator/machine.c

@@ -72,6 +72,32 @@ static void reportCycles(const CPURegisters *cpu, unsigned long cycleCount) {
 }
 
 
+// ---- A keyboard made of a file ----
+//
+// THE CONSOLE BEHIND A WINDOW IS NOT THE CONSOLE BEHIND A TERMINAL, and until this existed
+// the difference was untestable. A terminal does the line editing; a window has none, so the
+// console does it itself - gathering a line, rubbing out a backspace, handing it over only
+// when Return arrives. That is real logic, it broke twice in two days, and both times it was
+// found by a person typing rather than by anything here.
+//
+// So a file can be a keyboard. It installs the same hook a window does, which means the same
+// path runs, and the suite can check what happens when a backspace arrives with nobody to
+// interpret it. It does not test the window - Voyager's own key queue is still beyond reach
+// - but it tests the console, which is where the logic is.
+static FILE *keyboardFile = NULL;
+
+static int keyboardHook(int mayWait) {
+    (void)mayWait;      // There is no window to keep alive, so both questions are the same.
+    if (keyboardFile == NULL) {
+        return CONSOLE_GONE;
+    }
+    const int byte = fgetc(keyboardFile);
+    if (byte == EOF) {
+        return CONSOLE_GONE;
+    }
+    return byte & 0xFF;
+}
+
 uint8_t machineStart(Machine *m, const EmulatorOptions *options, const char *programFile) {
     m->options = *options;
     m->programFile = programFile;
@@ -115,6 +141,14 @@ uint8_t machineStart(Machine *m, const EmulatorOptions *options, const char *pro
     if (m->options.debug) {
         printRegisters(&m->cpu, Program, Data);
     }
+    if (options->keyboard != NULL) {
+        keyboardFile = fopen(options->keyboard, "rb");
+        if (keyboardFile == NULL) {
+            fprintf(stderr, "Error: Couldn't read the keyboard file: %s\n", options->keyboard);
+            return MACHINE_ERROR;
+        }
+        consoleSetInputHook(keyboardHook);
+    }
     setDiskLatency(m->options.diskCycles);
     cycle_timer_init(&m->timer, CYCLE_RATE);
     return MACHINE_OK;
@@ -220,6 +254,11 @@ void machineStop(Machine *m) {
     if (m->options.screen != NULL) {
         videoWriteImage(m->options.screen);
     }
+    if (keyboardFile != NULL) {
+        consoleSetInputHook(NULL);
+        fclose(keyboardFile);
+        keyboardFile = NULL;
+    }
     detachDisk();
 }
 

Source/Emulator/utility.c

@@ -30,6 +30,10 @@ void printHelp(const char *programName) {
     printf("  -S, --screen FILE Save a picture of the screen, as a PPM, when the machine\n");
     printf("                    stops. Works with or without a window, which is how the\n");
     printf("                    tests look at a screen on a host that has no display.\n");
+    printf("  -K, --keyboard FILE  Feed the console from this file as though it were a\n");
+    printf("                    keyboard rather than a terminal. Which means the console does\n");
+    printf("                    its own line editing, the way it must when a window is open\n");
+    printf("                    and there is no terminal behind it to do it.\n");
     printf("  -h, --help        Display this help message.\n");
 }
 
@@ -42,6 +46,7 @@ uint8_t parseOptions(int argc, char *argv[], EmulatorOptions *options) {
         {"write-protect", no_argument, 0, 'W'},
         {"disk-cycles", required_argument, 0, 'L'},
         {"screen", required_argument, 0, 'S'},
+        {"keyboard", required_argument, 0, 'K'},
         {"help",   no_argument,       0, 'h'},
         {0,        0,                 0,  0 }
         };
@@ -55,9 +60,10 @@ uint8_t parseOptions(int argc, char *argv[], EmulatorOptions *options) {
     options->writeProtect = 0;
     options->diskCycles = 0;
     options->screen = NULL;
+    options->keyboard = NULL;
 
     // Parse options
-    while ((opt = getopt_long(argc, argv, "dc:fhD:WL:S:", long_options, &option_index)) != -1) {
+    while ((opt = getopt_long(argc, argv, "dc:fhD:WL:S:K:", long_options, &option_index)) != -1) {
         switch (opt) {
             case 'd':
                 options->debug = 1;
@@ -90,6 +96,9 @@ uint8_t parseOptions(int argc, char *argv[], EmulatorOptions *options) {
             case 'S':
                 options->screen = optarg;
             break;
+            case 'K':
+                options->keyboard = optarg;
+            break;
             case 'h':
                 printHelp(argv[0]);
                 return OPTIONS_HELP;

Source/Emulator/utility.h

@@ -23,6 +23,7 @@ typedef struct {
     const char *disk;      // Disk image to attach, or NULL for a machine with no disk.
     uint8_t writeProtect;  // Attach the disk read only, the way a tab on a floppy would.
     const char *screen;    // Where to save a picture of the screen when the machine stops.
+    const char *keyboard;  // Feed the console from this file as a keyboard, not a terminal.
 } EmulatorOptions;
 
 uint8_t parseOptions(int argc, char *argv[], EmulatorOptions *options);