@tui-sandbox/library 10.5.1 → 10.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tui-sandbox/library",
-  "version": "10.5.1",
+  "version": "10.6.1",
   "repository": {
     "type": "git",
     "url": "https://github.com/mikavilpas/tui-sandbox"
@@ -12,8 +12,8 @@
   },
   "dependencies": {
     "@catppuccin/palette": "1.7.1",
-    "@trpc/client": "11.4.1",
-    "@trpc/server": "11.4.1",
+    "@trpc/client": "11.4.2",
+    "@trpc/server": "11.4.2",
     "@xterm/addon-attach": "0.11.0",
     "@xterm/addon-fit": "0.10.0",
     "@xterm/xterm": "5.5.0",
@@ -24,7 +24,7 @@
     "express": "5.1.0",
     "neovim": "5.3.0",
     "node-pty": "1.0.0",
-    "prettier": "3.5.3",
+    "prettier": "3.6.1",
     "tsx": "4.20.3",
     "type-fest": "4.41.0",
     "winston": "3.17.0"
@@ -33,10 +33,10 @@
     "@types/command-exists": "1.2.3",
     "@types/cors": "2.8.19",
     "@types/express": "5.0.3",
-    "@types/node": "24.0.1",
+    "@types/node": "24.0.4",
     "nodemon": "3.1.10",
-    "vite": "6.3.5",
-    "vitest": "3.2.3",
+    "vite": "7.0.0",
+    "vitest": "3.2.4",
     "zod": "4.0.0-beta.20250505T195954"
   },
   "peerDependencies": {

package/src/browser/neovim-client.ts

@@ -1,5 +1,7 @@
+import type { Terminal } from "@xterm/xterm"
 import { TerminalClient as NeovimTerminalClient } from "../client/index.js"
 import { TerminalTerminalClient } from "../client/terminal-terminal-client.js"
+import type { TuiTerminalApi } from "../client/websocket-client.js"
 import type {
   ExCommandClientInput,
   LuaCodeClientInput,
@@ -64,7 +66,7 @@ window.startNeovim = async function (startArgs?: StartNeovimGenericArguments): P
 declare global {
   interface Window {
     startNeovim(startArguments?: StartNeovimGenericArguments): Promise<GenericNeovimBrowserApi>
-    startTerminalApplication(args: StartTerminalGenericArguments): Promise<GenericTerminalBrowserApi>
+    startTerminalApplication(args: StartTerminalBrowserArguments): Promise<GenericTerminalBrowserApi>
   }
 }
 
@@ -73,9 +75,24 @@ export type GenericTerminalBrowserApi = {
   runBlockingShellCommand(input: BlockingCommandClientInput): Promise<BlockingShellCommandOutput>
 }
 
+export type BrowserTerminalSettings = {
+  configureTerminal?: (term: {
+    terminal: Terminal
+    api: TuiTerminalApi
+    recipes: {
+      supportDA1: () => void
+    }
+  }) => void
+}
+
+export type StartTerminalBrowserArguments = {
+  serverSettings: StartTerminalGenericArguments
+  browserSettings: BrowserTerminalSettings
+}
+
 /** Entrypoint for the test runner (cypress) */
 window.startTerminalApplication = async function (
-  args: StartTerminalGenericArguments
+  args: StartTerminalBrowserArguments
 ): Promise<GenericTerminalBrowserApi> {
   const terminal = terminalClient.get()
   const testDirectory = await terminal.startTerminalApplication(args)

package/src/client/terminal-config.ts

@@ -0,0 +1,25 @@
+import type { Terminal } from "@xterm/xterm"
+import type { TuiTerminalApi } from "./websocket-client.js"
+
+/** DA1—Primary Device Attributes
+ * In this DA exchange, the host asks for the terminal's architectural class and basic attributes.
+ * https://vt100.net/docs/vt510-rm/DA1.html
+ *
+ * Terminal Response
+ * The terminal responds by sending its architectural class and basic
+ * attributes to the host. This response depends on the terminal's current
+ * operating VT level.
+ */
+export function supportDA1(terminal: Terminal, api: TuiTerminalApi): void {
+  // Register a CSI handler for the 'c' command (ESC [ c)
+  terminal.parser.registerCsiHandler({ final: "c" }, () => {
+    // Emit a fake DA1 response: ESC [ ? 1 ; 2 c
+    api.onKeyPress({
+      key: "\x1b" + ("[?1;2c" satisfies FakeDA1Response),
+      domEvent: new KeyboardEvent("keydown", { key: "Escape" }),
+    })
+    return true // prevent default handling
+  })
+}
+
+export type FakeDA1Response = "[?1;2c"

package/src/client/terminal-terminal-client.ts

@@ -1,11 +1,13 @@
 import { createTRPCClient, httpBatchLink, httpSubscriptionLink, splitLink } from "@trpc/client"
 import type { Terminal } from "@xterm/xterm"
 import "@xterm/xterm/css/xterm.css"
-import type { StartTerminalGenericArguments } from "../server/applications/terminal/TerminalTestApplication.js"
+import type { StartTerminalBrowserArguments } from "../browser/neovim-client.js"
 import type { BlockingCommandClientInput } from "../server/blockingCommandInputSchema.js"
 import type { AppRouter } from "../server/server.js"
 import type { BlockingShellCommandOutput, TestDirectory } from "../server/types.js"
 import "./style.css"
+import { supportDA1 } from "./terminal-config.js"
+import type { TuiTerminalApi } from "./websocket-client.js"
 import { getTabId, startTerminal } from "./websocket-client.js"
 
 /** Manages the terminal state in the browser as well as the (browser's)
@@ -15,6 +17,7 @@ export class TerminalTerminalClient {
   private readonly tabId: { tabId: string }
   private readonly terminal: Terminal
   private readonly trpc: ReturnType<typeof createTRPCClient<AppRouter>>
+  terminalApi: TuiTerminalApi
 
   constructor(app: HTMLElement) {
     const trpc = createTRPCClient<AppRouter>({
@@ -35,7 +38,7 @@ export class TerminalTerminalClient {
     this.tabId = getTabId()
     const tabId = this.tabId
 
-    const terminal = startTerminal(app, {
+    this.terminalApi = {
       onMouseEvent(data: string) {
         void trpc.terminal.sendStdin.mutate({ tabId, data }).catch((error: unknown) => {
           console.error(`Error sending mouse event`, error)
@@ -44,11 +47,12 @@ export class TerminalTerminalClient {
       onKeyPress(event) {
         void trpc.terminal.sendStdin.mutate({ tabId, data: event.key })
       },
-    })
+    }
+    const terminal = startTerminal(app, this.terminalApi)
     this.terminal = terminal
 
-    // start listening to Neovim stdout - this will take some (short) amount of
-    // time to complete
+    // start listening to stdout - this will take some (short) amount of time
+    // to complete
     this.ready = new Promise<void>(resolve => {
       console.log("Subscribing to stdout")
       trpc.terminal.onStdout.subscribe(
@@ -68,13 +72,24 @@ export class TerminalTerminalClient {
     })
   }
 
-  public async startTerminalApplication(args: StartTerminalGenericArguments): Promise<TestDirectory> {
+  public async startTerminalApplication(args: StartTerminalBrowserArguments): Promise<TestDirectory> {
     await this.ready
+
+    args.browserSettings.configureTerminal?.({
+      terminal: this.terminal,
+      api: this.terminalApi,
+      recipes: {
+        supportDA1: () => {
+          supportDA1(this.terminal, this.terminalApi)
+        },
+      },
+    })
+
     const testDirectory = await this.trpc.terminal.start.mutate({
       tabId: this.tabId,
       startTerminalArguments: {
-        additionalEnvironmentVariables: args.additionalEnvironmentVariables,
-        commandToRun: args.commandToRun,
+        additionalEnvironmentVariables: args.serverSettings.additionalEnvironmentVariables,
+        commandToRun: args.serverSettings.commandToRun,
         terminalDimensions: {
           cols: this.terminal.cols,
           rows: this.terminal.rows,

package/src/client/websocket-client.ts

@@ -7,11 +7,11 @@ import type { TabId } from "../server/utilities/tabId.ts"
 import "./style.css"
 import { validateMouseEvent } from "./validateMouseEvent.js"
 
-export type StartTerminalOptions = {
+export type TuiTerminalApi = {
   onMouseEvent: (data: string) => void
   onKeyPress: (event: { key: string; domEvent: KeyboardEvent }) => void
 }
-export function startTerminal(app: HTMLElement, options: StartTerminalOptions): Terminal {
+export function startTerminal(app: HTMLElement, api: TuiTerminalApi): Terminal {
   const terminal = new Terminal({
     cursorBlink: false,
     convertEol: true,
@@ -62,12 +62,12 @@ export function startTerminal(app: HTMLElement, options: StartTerminalOptions):
 
     const mouseEvent = validateMouseEvent(data)
     if (mouseEvent) {
-      options.onMouseEvent(mouseEvent)
+      api.onMouseEvent(mouseEvent)
     }
   })
 
   terminal.onKey(event => {
-    options.onKeyPress(event)
+    api.onKeyPress(event)
   })
 
   return terminal

package/src/server/applications/neovim/NeovimApplication.ts

@@ -202,11 +202,12 @@ export class NeovimApplication implements AsyncDisposable {
 
     try {
       await access(this.state.socketPath)
-      throw new Error(`Socket file ${this.state.socketPath} should have been removed by neovim when it exited.`)
+      console.warn(`Socket file ${this.state.socketPath} should have been removed by neovim when it exited.`)
+      return
     } catch (e) {
       // all good
+    } finally {
+      this.state = undefined
     }
-
-    this.state = undefined
   }
 }

package/src/server/cypress-support/contents.ts

@@ -11,10 +11,12 @@ export async function createCypressSupportFileContents(): Promise<string> {
 // This file is autogenerated by tui-sandbox. Do not edit it directly.
 //
 import type {
+  BrowserTerminalSettings,
   GenericNeovimBrowserApi,
   GenericTerminalBrowserApi,
 } from "@tui-sandbox/library/dist/src/browser/neovim-client"
 import type {
+  AllKeys,
   BlockingShellCommandOutput,
   RunExCommandOutput,
   RunLuaCodeOutput,
@@ -131,9 +133,17 @@ Cypress.Commands.add("nvim_isRunning", () => {
   })
 })
 
-Cypress.Commands.add("startTerminalApplication", (args: StartTerminalGenericArguments) => {
+Cypress.Commands.add("startTerminalApplication", (args: StartTerminalGenericArguments & BrowserTerminalSettings) => {
   cy.window().then(async win => {
-    const terminal: GenericTerminalBrowserApi = await win.startTerminalApplication(args)
+    const terminal: GenericTerminalBrowserApi = await win.startTerminalApplication({
+      serverSettings: {
+        commandToRun: args.commandToRun,
+        additionalEnvironmentVariables: args.additionalEnvironmentVariables,
+      } satisfies AllKeys<StartTerminalGenericArguments>,
+      browserSettings: {
+        configureTerminal: args.configureTerminal,
+      } satisfies AllKeys<BrowserTerminalSettings>,
+    })
 
     Cypress.Commands.addAll({
       terminal_runBlockingShellCommand: terminal.runBlockingShellCommand,
@@ -177,7 +187,9 @@ declare global {
   namespace Cypress {
     interface Chainable {
       startNeovim(args?: MyStartNeovimServerArguments): Chainable<NeovimContext>
-      startTerminalApplication(args: StartTerminalGenericArguments): Chainable<TerminalTestApplicationContext>
+      startTerminalApplication(
+        args: StartTerminalGenericArguments & BrowserTerminalSettings
+      ): Chainable<TerminalTestApplicationContext>
 
       /** Types text into the terminal, making the terminal application receive
        * the keystrokes as input. Requires neovim to be running. */

package/src/server/types.ts

@@ -64,3 +64,15 @@ export type RunLuaCodeOutput = {
 }
 
 export type RunExCommandOutput = { value?: string }
+
+/**
+ * Require all of an object's keys to be set explicitly. This is useful for
+ * readability: writing all the keys makes their presence explicit. They could
+ * also be added via a spread operator (...obj), but in that case the following
+ * cases are unclear:
+ *
+ * - extra keys might be included because TypeScript does not check for them
+ * - if the target object type has optional keys, they might be missing. In
+ *   this case, they will never get set
+ **/
+export type AllKeys<T extends Record<never, never>> = Record<keyof T, unknown>