@cplieger/web-terminal-engine 6.4.0-dev.6 → 6.4.0-dev.9

package/jsr.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/web-terminal-engine",
-  "version": "6.4.0-dev.6",
+  "version": "6.4.0-dev.9",
   "license": "MPL-2.0",
   "exports": {
     ".": "./src/index.ts"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/web-terminal-engine",
-  "version": "6.4.0-dev.6",
+  "version": "6.4.0-dev.9",
   "type": "module",
   "scripts": {
     "typecheck": "tsc -p tsconfig.json",
@@ -22,8 +22,8 @@
     "@stryker-mutator/vitest-runner": "10.0.0",
     "@types/pngjs": "6.0.5",
     "@typescript/native": "npm:typescript@7.0.2",
-    "@vitest/browser-playwright": "5.0.4",
-    "@vitest/coverage-v8": "5.0.4",
+    "@vitest/browser-playwright": "5.0.5",
+    "@vitest/coverage-v8": "5.0.5",
     "esbuild": "0.28.2",
     "eslint": "10.12.0",
     "fast-check": "4.10.2",
@@ -33,7 +33,7 @@
     "prettier": "3.9.10",
     "typescript": "npm:@typescript/typescript6@6.0.2",
     "typescript-eslint": "8.71.2",
-    "vitest": "5.0.4"
+    "vitest": "5.0.5"
   },
   "overrides": {
     "qs": "^6.15.2"

package/src/index.ts

@@ -40,6 +40,7 @@ export { wsURL } from "./wsurl.js";
 export { WS_PATH, SESSIONS_PATH, SESSION_EVENTS_PATH } from "./routes.js";
 export { connectStatusStream } from "./status-stream.js";
 export type {
+  KnownStatus,
   SessionInfo,
   SessionStatus,
   StatusStream,

package/src/keyboard.ts

@@ -339,10 +339,10 @@ function anyModifier(ev: KeyboardEvent): boolean {
 }
 
 /**
- * The kitty "unicode-key-code": the UNSHIFTED (lower-case / base-layout)
- * codepoint of the key. Letters and digits are read from ev.code (the physical
- * key), so a composed Alt/Option character on macOS still maps to its base key;
- * other single-character keys fall back to the case-folded ev.key.
+ * The kitty "unicode-key-code", read as the UNSHIFTED US-layout codepoint of
+ * the physical key: letters, digits and KITTY_CODE_BASE's punctuation come from
+ * ev.code, so a composed Option character or a shifted symbol maps to its base
+ * key; any other single-character key falls back to the case-folded ev.key.
  */
 function kittyKeyCodepoint(ev: KeyboardEvent): number {
   const code = ev.code;
@@ -431,6 +431,12 @@ function encodeKittyDisambiguate(ev: KeyboardEvent): KeyboardResult {
     if (ev.metaKey && !ev.ctrlKey && !ev.altKey) {
       return { kind: "ignore" };
     }
+    // A desktop AltGr character arrives with ctrlKey and altKey clear, so it stays
+    // text: on Windows, Chromium and Firefox swap Ctrl+Alt for AltGraph whenever
+    // the chord types a character (https://chromestatus.com/feature/5059438092222464,
+    // https://searchfox.org/mozilla-central/source/widget/windows/KeyboardLayout.cpp).
+    // AltGraph must not exempt a key here: Firefox sets it on every macOS Option
+    // chord (widget/cocoa/nsCocoaUtils.mm), and Ctrl+Option+a is 97;7u.
     if (ev.ctrlKey || ev.altKey || ev.metaKey) {
       const cp = kittyKeyCodepoint(ev);
       if (cp > 0) {
@@ -480,15 +486,6 @@ export function mapKeyboardEvent(ev: KeyboardEvent, modes: KeyboardModes): Keybo
     }
   }
 
-  // Browser-reserved meta combos (Cmd+R, Cmd+T, Cmd+Q, Cmd+W on Mac;
-  // Ctrl+R, Ctrl+T, Ctrl+W with no Shift on others). Let the browser
-  // handle them. Heuristic: only take Ctrl+letter when Shift is NOT
-  // held AND the letter is one of the ones xterm consumes (a-z),
-  // skipping the few that browsers commonly reserve.
-  // (Ctrl+R, Ctrl+T and Ctrl+W still go to the PTY: readline binds them to
-  // reverse search, transpose and word rubout, and full-screen programs bind
-  // them too. On macOS, Cmd reaches the browser's own combos.)
-
   // Shift+PageUp / Shift+PageDown — local scrollback navigation
   // (matches xterm.js KeyboardResultType.PAGE_UP/PAGE_DOWN).
   if (ev.key === "PageUp" && ev.shiftKey && !ev.ctrlKey && !ev.altKey && !ev.metaKey) {
@@ -590,7 +587,9 @@ export function mapKeyboardEvent(ev: KeyboardEvent, modes: KeyboardModes): Keybo
     return { kind: "ignore" }; // let `input` event handle plain space
   }
 
-  // Single printable character with modifiers.
+  // Single printable character with modifiers. Neither branch takes Meta, so
+  // the browser keeps Cmd+R/T/W/C/V; Ctrl+R/T/W go to the PTY, where readline
+  // binds them.
   if (ev.key.length === 1) {
     const ch = ev.key;
 

package/src/status-stream.ts

@@ -7,6 +7,11 @@
 
 import { nextBackoffDelay } from "./reconnect.js";
 
+/** KnownStatus is a status the server derives itself, one per Go terminal.Status*
+ *  constant. */
+export type KnownStatus =
+  "working" | "idle" | "input" | "done" | "exited" | "crashed" | "failed" | "warning";
+
 /** SessionInfo is one session's wire shape: the JSON object the session REST
  *  API (GET/POST /api/sessions) returns per session, kept in lockstep with the Go
  *  terminal.SessionInfo by hand.
@@ -16,21 +21,14 @@ import { nextBackoffDelay } from "./reconnect.js";
  *  a CLIENT-DERIVED automatic title a client asked the server to remember. */
 export interface SessionInfo {
   readonly id: string;
-  /** the session's current status. "working"/"idle"/"exited"/"crashed" are
-   *  derived by the server; "input"/"done" are latched from a classified OSC 9
-   *  notification; "failed" is OSC 9;4 progress state 2 and "warning" is state 4
-   *  (iTerm2 semantics), both of which PERSIST until the program changes the
-   *  progress state. "exited" and "crashed" split the session's end: "exited" is
-   *  an ordinary one (status 0, or any exit the server itself caused — a closed
-   *  session, the idle reaper, a server shutdown), "crashed" is a non-zero exit
-   *  status or a terminating signal the program was not asked for, so a routine
-   *  restart never renders as a failure. Neither is a progress state: they
-   *  outrank everything, and nothing clears them. A consumer must tolerate an
-   *  UNKNOWN status string from a newer server: the stream is parsed, not
-   *  validated, and an unrecognised value is forwarded rather than dropped
-   *  (forward compatibility across the wire floor). */
-  readonly status:
-    "working" | "idle" | "input" | "done" | "exited" | "crashed" | "failed" | "warning";
+  /** the session's current status. The server derives a KnownStatus from the
+   *  program's OSC 7501 report, or from OSC 9;4 progress while it has sent none
+   *  since a hard reset (RIS); "exited" and "crashed" mark the process's end
+   *  and nothing clears them. A classified OSC 9 notification latches whatever
+   *  string the server's classifier returns, and a newer server may add values,
+   *  so a consumer must handle any other string: the stream forwards it
+   *  unchanged. The engine's docs/sessions.md gives every mapping. */
+  readonly status: KnownStatus | (string & {});
   readonly title: string;
   /** the session's short public name, safe to put in a URL: 1 to 64 characters
    *  of `[A-Za-z0-9_-]`, unique among live sessions, and NOT a capability
@@ -72,11 +70,11 @@ export interface SessionInfo {
    *  view: a list built from that hybrid still names the live set exactly, so the
    *  server accepts it and it becomes the arrangement every device sees. */
   readonly order?: number;
-  /** true once the session has emitted a genuine activity signal — OSC 9;4
-   *  progress or a classified OSC 9 notification.
-   *  Sticky for the session's life. Consumers reveal the per-tab activity dot
-   *  only when this is set; a program that emits no OSC 9 signal (a plain shell)
-   *  keeps its tab dot hidden. */
+  /** true once the session has emitted a genuine activity signal — an OSC 7501
+   *  report, OSC 9;4 progress or a classified OSC 9 notification.
+   *  Sticky for the session's life, a hard reset (RIS) included. Consumers
+   *  reveal the per-tab activity dot only when this is set; a program that
+   *  emits none of the three (a plain shell) keeps its tab dot hidden. */
   readonly reportsActivity?: boolean;
   /** the session's SECONDARY activity: a host-reported background activity that
    *  OUTLIVES the turn, carried beside `status` and never merged into it. The
@@ -84,18 +82,19 @@ export interface SessionInfo {
    *  (stopped and resumable, nobody is being asked) and `"input"` (a background
    *  task is blocked on the user); absent or an empty string means no secondary
    *  activity, and a consumer must tolerate an UNKNOWN value from a newer server
-   *  by rendering nothing for it.
-   *
-   *  Typed `string`, deliberately NOT a union like `status`: that union's own doc
-   *  already admits it must tolerate values outside itself, which forces a cast at
-   *  every forward-compatible site. Absent from a server that reports none. */
+   *  by rendering nothing for it. Absent from a server that reports none. */
   readonly activity?: string;
   /** how many sources produced `activity`: >= 1 whenever `activity` is non-empty,
    *  0 when it is empty or the host does not count them. */
   readonly activityCount?: number;
-  /** numbers the occurrence of `status`: it rises by one each time the status
-   *  changes or a fresh notification re-latches it, and never falls for one id.
-   *  Absent (or 0) means nothing numbered yet, including from an older server. */
+  /** numbers the occurrence of the session's status. A sweep raises it by one
+   *  when it emits a changed status, a status a classified notification latched
+   *  since the last sweep, or an input, done or failed status after an OSC 7501
+   *  report since then created a record, changed one's state or kind, or
+   *  cleared one, and so changed which record the status came from, or its
+   *  state or kind, at that report. A report keeping a record's state and kind
+   *  raises it only by changing the status. It never falls for one id; 0,
+   *  absent on the wire, means nothing numbered yet. */
   readonly statusSeq?: number;
   /** the highest `statusSeq` any reader acknowledged through
    *  `PUT /api/sessions/{id}/seen`. Never falls for one id and never exceeds
@@ -110,9 +109,10 @@ export interface SessionInfo {
 export interface SessionStatus extends SessionInfo {
   /** true when the session is gone (closed or reaped); the consumer drops it. */
   readonly removed?: boolean;
-  /** the OSC 9;4 percentage: -1 when absent or unknown (no sequence seen, or a
-   *  state that carries none — clear/indeterminate), else 0-100. Paired with
-   *  `status` to render a determinate bar. */
+  /** the session's percentage: the OSC 7501 report's `progress` when it
+   *  carries one, else the OSC 9;4 percentage. -1 when absent or unknown (no
+   *  sequence seen, or a state that carries none — clear/indeterminate), else
+   *  0-100. Paired with `status` to render a determinate bar. */
   readonly progressValue?: number;
   /** the OSC 9 notification message, delivered to EVERY subscriber whether or
    *  not the server has a status classifier installed. A notification is an