@cplieger/web-terminal-engine 1.2.0 → 1.3.0

package/jsr.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/web-terminal-engine",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "exports": {
     ".": "./src/index.ts"
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/web-terminal-engine",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "type": "module",
   "scripts": {
     "typecheck": "tsgo -p tsconfig.json",
@@ -10,10 +10,10 @@
   "devDependencies": {
     "@eslint/js": "10.0.1",
     "@vitest/coverage-v8": "4.1.9",
-    "eslint": "10.5.0",
+    "eslint": "10.6.0",
     "fast-check": "4.8.0",
     "happy-dom": "20.10.6",
-    "prettier": "3.8.4",
+    "prettier": "3.8.5",
     "typescript": "6.0.3",
     "typescript-eslint": "8.62.0",
     "vitest": "4.1.9"

package/src/keyboard.ts

@@ -470,7 +470,7 @@ export interface MobileToolbarController {
    *     would garble it.
    */
   applyStickyCtrl(text: string): string;
-  /** Programmatically arm/disarm Ctrl. Updates the toolbar button visuals + fires `onCtrlChange`. */
+  /** Programmatically arm/disarm Ctrl. Updates the toolbar button visuals (`.armed` class + `aria-pressed`) + fires `onCtrlChange`. */
   setCtrlArmed(on: boolean): void;
   /** Whether sticky-Ctrl is currently armed. */
   isCtrlArmed(): boolean;
@@ -513,20 +513,28 @@ export function bindMobileToolbar(opts: BindMobileToolbarOptions): MobileToolbar
   const enterBtn = findBtn(ids.enter);
   const escBtn = findBtn(ids.esc);
 
+  function paintCtrlBtn(on: boolean): void {
+    if (!ctrlBtn) {
+      return;
+    }
+    ctrlBtn.classList.toggle("armed", on);
+    // Keep the ARIA toggle state in sync with the visual `.armed` class so
+    // assistive tech announces the sticky-Ctrl button as pressed/unpressed.
+    // The scaffold ships kb-ctrl as `aria-pressed="false"`; consumers used to
+    // own this in their own setCtrlArmed before delegating the toolbar here.
+    ctrlBtn.setAttribute("aria-pressed", on ? "true" : "false");
+  }
+
   function setCtrlArmed(on: boolean): void {
     if (armed === on) {
       // Still update visuals defensively (e.g. after dispose was called
       // and someone re-armed via setCtrlArmed) — but skip the change
       // notification to keep onCtrlChange edge-triggered.
-      if (ctrlBtn) {
-        ctrlBtn.classList.toggle("armed", on);
-      }
+      paintCtrlBtn(on);
       return;
     }
     armed = on;
-    if (ctrlBtn) {
-      ctrlBtn.classList.toggle("armed", on);
-    }
+    paintCtrlBtn(on);
     opts.onCtrlChange?.(on);
   }
 

package/src/render.ts

@@ -178,6 +178,12 @@ export function init(opts: {
   rowEls.clear();
   renderQueue.clear();
   trimMarkerEl = null;
+  // Drop the predicted-cursor overlay (re-created lazily against the new
+  // termWrap on the next setPredictedCursor call) so re-init starts clean.
+  if (predCursorEl) {
+    predCursorEl.remove();
+    predCursorEl = null;
+  }
   output.replaceChildren();
   cursorAbs = -1;
   if (pendingFrame !== undefined) {
@@ -785,16 +791,28 @@ export function getCursorPx(): { left: number; top: number; cellH: number } {
 
 let predCursorEl: HTMLElement | null = null;
 
+// Create the predicted-cursor overlay the renderer owns. Appended to termWrap
+// (the positioned scroll container) so its absolute left/top math matches the
+// row offsets. Styled by the `.pred-cursor` class from the UI CSS bundle. The
+// renderer owning this means the engine never depends on a host-provided
+// `#pred-cursor` scaffold element.
+function createPredCursorEl(): HTMLElement {
+  const el = document.createElement("div");
+  el.className = "pred-cursor";
+  el.setAttribute("aria-hidden", "true");
+  termWrap.appendChild(el);
+  return el;
+}
+
 /**
  * Show or hide a "predicted" cursor overlay at window-relative (row, col).
  * Useful for client-side echo of typed characters before the server
- * acknowledges them, over high-latency connections.
+ * acknowledges them, over high-latency connections. The overlay element is
+ * created lazily on first use (a consumer that never predicts never creates
+ * it).
  */
 export function setPredictedCursor(row: number, col: number, active: boolean): void {
-  const el = predCursorEl ?? (predCursorEl = document.getElementById("pred-cursor"));
-  if (!el) {
-    return;
-  }
+  const el = predCursorEl ?? (predCursorEl = createPredCursorEl());
   const win = store.getWindow();
   const predAbs = win.base + row;
   if (!active || (predAbs === cursorAbs && col === cursorCol)) {