@cplieger/web-terminal-ui 1.0.0

package/css/MANIFEST

@@ -0,0 +1,5 @@
+# web-terminal-ui CSS bundle manifest
+# Files concatenated in declared order to produce the served style.css.
+00-tokens.css
+01-reset.css
+02-app.css

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@cplieger/web-terminal-ui",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Reference touch-first browser UI for @cplieger/web-terminal-engine: textarea input model, mobile key toolbar, context menu, IME, predictive echo, viewport/keyboard-inset handling, and CSS. One mount() call.",
+  "license": "GPL-3.0-or-later",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "types": "./src/index.ts",
+  "scripts": {
+    "typecheck": "tsgo -p tsconfig.json",
+    "typecheck:tests": "tsgo -p tsconfig.test.json",
+    "test": "vitest --run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest --run --coverage",
+    "lint:eslint": "eslint .",
+    "lint:prettier": "prettier --check .",
+    "lint:fix": "eslint . --fix && prettier --write .",
+    "lint:knip": "knip",
+    "verify": "bash scripts/verify.sh"
+  },
+  "peerDependencies": {
+    "@cplieger/web-terminal-engine": ">=1.2.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "10.0.1",
+    "@types/node": "25.9.4",
+    "@vitest/coverage-v8": "4.1.9",
+    "eslint": "10.5.0",
+    "fast-check": "4.8.0",
+    "happy-dom": "20.10.6",
+    "html-validate": "11.5.3",
+    "knip": "6.20.0",
+    "prettier": "3.8.4",
+    "stylelint": "17.13.0",
+    "stylelint-config-standard": "40.0.0",
+    "typescript": "6.0.3",
+    "typescript-eslint": "8.62.0",
+    "vitest": "4.1.9"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cplieger/web-terminal-ui.git"
+  },
+  "files": [
+    "src/",
+    "css/",
+    "scaffold/",
+    "LICENSE",
+    "README.md",
+    "!src/**/*.test.ts",
+    "!src/**/fc-strict-setup.ts"
+  ]
+}

package/scaffold/index.html

@@ -0,0 +1,52 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1,maximum-scale=1,user-scalable=no,viewport-fit=cover,interactive-widget=resizes-content">
+<meta name="color-scheme" content="dark">
+<title>Web Terminal</title>
+<!-- App icons and web-app manifest are deployment-specific; add your own. -->
+<link rel="stylesheet" href="/style.css">
+<!-- [html-validate-disable-next no-style-tag -- critical CSS for instant loading indicator] -->
+<style>
+#loading{position:fixed;inset:0;display:flex;align-items:center;justify-content:center;flex-direction:column;gap:12px;z-index:200;background:#000;font-family:system-ui,-apple-system,sans-serif;color:#b48eff;font-size:18px;transition:opacity .3s ease}
+#loading.fade{opacity:0}
+#loading .spin{width:32px;height:32px;border:3px solid #b48eff;border-right-color:transparent;border-radius:50%;animation:sp .6s linear infinite}
+@keyframes sp{to{transform:rotate(360deg)}}
+</style>
+</head>
+<body>
+<div id="term" class="term">
+  <div id="term-output" class="term-output" role="log" aria-live="off" aria-roledescription="Terminal" aria-label="Terminal"></div>
+  <textarea id="term-input" class="term-input" autocapitalize="off" autocomplete="off" autocorrect="off" spellcheck="false" aria-label="Terminal input" tabindex="-1"></textarea>
+  <div id="composition-view" class="composition-view" aria-hidden="true"></div>
+  <div id="pred-cursor" class="pred-cursor" aria-hidden="true"></div>
+</div>
+<div id="loading"><div class="spin"></div>Loading…</div>
+<div id="conn-banner" class="conn-banner" role="status" aria-live="polite"></div>
+<div id="key-toolbar" class="key-toolbar collapsed no-transition" aria-label="Navigation keys" role="toolbar">
+  <button type="button" id="kb-toggle" class="kb-toggle"      aria-label="Toggle key toolbar"><svg class="icon-hamburger" viewBox="0 0 24 24"><line x1="4" y1="6" x2="20" y2="6"/><line x1="4" y1="12" x2="20" y2="12"/><line x1="4" y1="18" x2="20" y2="18"/></svg><svg class="icon-close" viewBox="0 0 24 24"><line x1="6" y1="6" x2="18" y2="18"/><line x1="18" y1="6" x2="6" y2="18"/></svg></button>
+  <button type="button" id="kb-tab"    class="kb-key kb-r1c1" aria-label="Tab">TAB</button>
+  <button type="button" id="kb-esc"    class="kb-key kb-r1c2" aria-label="Escape">ESC</button>
+  <button type="button" id="kb-up"     class="kb-key kb-r1c3" aria-label="Up"><svg viewBox="0 0 24 24"><polyline points="6 15 12 9 18 15"/></svg></button>
+  <button type="button" id="kb-enter"  class="kb-key kb-r1c4" aria-label="Enter"><svg viewBox="0 0 24 24"><polyline points="9 10 4 15 9 20"/><polyline points="20 4 20 15 4 15"/></svg></button>
+  <button type="button" id="scroll-bottom" class="kb-scroll-bottom" aria-label="Scroll to bottom"><svg viewBox="0 0 24 24"><path fill="none" d="M7 13l5 5 5-5M7 6l5 5 5-5"/></svg></button>
+  <button type="button" id="kb-ctrl"   class="kb-key kb-r2c1" aria-label="Sticky Ctrl modifier" aria-pressed="false">CTRL</button>
+  <button type="button" id="kb-left"   class="kb-key kb-r2c2" aria-label="Left"><svg viewBox="0 0 24 24"><polyline points="15 6 9 12 15 18"/></svg></button>
+  <button type="button" id="kb-down"   class="kb-key kb-r2c3" aria-label="Down"><svg viewBox="0 0 24 24"><polyline points="6 9 12 15 18 9"/></svg></button>
+  <button type="button" id="kb-right"  class="kb-key kb-r2c4" aria-label="Right"><svg viewBox="0 0 24 24"><polyline points="9 6 15 12 9 18"/></svg></button>
+</div>
+<div id="ctx-menu" class="ctx-menu"></div>
+<!-- Deployment-specific: the importmap resolves the bare engine specifier to
+     the engine's compiled JS, and /app.js is your bundle that calls
+     `mount()` from @cplieger/web-terminal-ui. Adjust paths to your build. -->
+<script type="importmap">
+{
+  "imports": {
+    "@cplieger/web-terminal-engine": "/vendor/cplieger-web-terminal-engine/index.js"
+  }
+}
+</script>
+<script type="module" src="/app.js"></script>
+</body>
+</html>

package/src/composition.ts

@@ -0,0 +1,171 @@
+// IME / composition support.
+//
+// Mirrors xterm.js's CompositionHelper. The browser fires
+// compositionstart → compositionupdate(s) → compositionend when an IME
+// (Japanese / Korean / Chinese / Vietnamese / dictation / autocorrect
+// suggestion bar) is active. Without a handler, the user sees nothing
+// while typing because keydown/input fire only when the composed
+// phrase is finalised.
+//
+// What this module does:
+//   1. On compositionstart, mark composing=true and capture textarea
+//      selection bounds. Show the floating compositionView at the
+//      cursor with the in-progress text.
+//   2. On compositionupdate, mirror the in-progress text into
+//      compositionView (\u200E LTR markers, RTL CSS direction so long
+//      compositions track their tail).
+//   3. On compositionend, set a setTimeout(0) finaliser. The
+//      compositionend.data property is unreliable on Chromium (Korean
+//      ending consonant moves to next char on vowel input, etc.); the
+//      textarea value at next tick has the truth.
+//   4. While composing, callers' keydown handler must early-return
+//      (handled via isComposing()). xterm.js takes the same approach.
+//
+// Positioning: the compositionView is absolutely positioned inside
+// `termWrap`. The IME UI (browser-rendered popup with candidate words)
+// uses the textarea as its anchor; we move the textarea to the cursor
+// for the same reason.
+
+import { keyboard } from "@cplieger/web-terminal-engine";
+const { bracketTextForPaste, prepareTextForTerminal } = keyboard;
+
+// Single-character invisible placeholder used by app.ts to keep the
+// iOS soft keyboard's held-Backspace auto-repeat firing. Composition
+// finalisation must restore the placeholder (and not empty the
+// textarea) for the same reason.
+const INPUT_PLACEHOLDER = "\u00A0";
+
+let textarea: HTMLTextAreaElement;
+let compositionView: HTMLElement;
+let getCursorPx: () => { left: number; top: number; cellH: number };
+let send: (bytes: string) => void;
+
+let composing = false;
+let sendingComposition = false;
+let compositionStart = 0;
+let compositionEnd = 0;
+let compositionSuffix = "";
+
+export function init(opts: {
+  textarea: HTMLTextAreaElement;
+  compositionView: HTMLElement;
+  getCursorPx: () => { left: number; top: number; cellH: number };
+  send: (bytes: string) => void;
+}): void {
+  textarea = opts.textarea;
+  compositionView = opts.compositionView;
+  getCursorPx = opts.getCursorPx;
+  send = opts.send;
+
+  textarea.addEventListener("compositionstart", onStart);
+  textarea.addEventListener("compositionupdate", onUpdate);
+  textarea.addEventListener("compositionend", onEnd);
+  textarea.addEventListener("paste", onPaste);
+}
+
+/** True while an IME composition is in progress. Caller's keydown
+ *  listener must early-return on true to avoid sending raw key bytes
+ *  during composition. */
+export function isComposing(): boolean {
+  return composing || sendingComposition;
+}
+
+function onStart(): void {
+  composing = true;
+  const start = textarea.selectionStart;
+  const end = textarea.selectionEnd;
+  compositionStart = Math.min(start, end);
+  compositionEnd = Math.max(start, end);
+  compositionSuffix = textarea.value.substring(compositionEnd);
+  compositionView.textContent = "";
+  compositionView.classList.add("active");
+  positionCompositionView();
+}
+
+function onUpdate(ev: CompositionEvent): void {
+  // \u200E (LTR mark) wrappers + CSS direction:rtl on the view make
+  // long compositions show their trailing edge instead of being
+  // clipped at the start. Pattern from xterm.js.
+  compositionView.textContent = `\u200E${ev.data}\u200E`;
+  positionCompositionView();
+  // Schedule a microtask to refresh the end position after the
+  // textarea selection settles.
+  setTimeout(() => {
+    const end = textarea.selectionEnd;
+    compositionEnd = Math.max(compositionStart, end);
+  }, 0);
+}
+
+function onEnd(): void {
+  compositionView.classList.remove("active");
+  composing = false;
+  // The compositionend event fires before the textarea reflects the
+  // final value on most browsers (Chromium especially). Defer one tick
+  // and read the textarea then; xterm.js's pattern.
+  sendingComposition = true;
+  const startSnapshot = compositionStart;
+  const suffixSnapshot = compositionSuffix;
+  setTimeout(() => {
+    if (!sendingComposition) {
+      return;
+    }
+    sendingComposition = false;
+    const value = textarea.value;
+    const valueEnd =
+      suffixSnapshot.length > 0 && value.endsWith(suffixSnapshot)
+        ? value.length - suffixSnapshot.length
+        : value.length;
+    const composed = value.substring(startSnapshot, Math.max(startSnapshot, valueEnd));
+    if (composed.length > 0) {
+      send(composed);
+    }
+    resetTextareaToPlaceholder();
+  }, 0);
+}
+
+function onPaste(ev: ClipboardEvent): void {
+  // Native `paste` event handler. Required for iOS where Ctrl+Shift+V
+  // is unavailable; users invoke paste from the iOS callout menu and
+  // it fires this event on the focused textarea.
+  if (!ev.clipboardData) {
+    return;
+  }
+  const raw = ev.clipboardData.getData("text/plain");
+  if (raw === "") {
+    return;
+  }
+  ev.preventDefault();
+  ev.stopPropagation();
+  send(bracketTextForPaste(prepareTextForTerminal(raw)));
+  // Restore the placeholder so the subsequent `input` event (some
+  // browsers fire it after paste) and held-Backspace auto-repeat keep
+  // working.
+  resetTextareaToPlaceholder();
+}
+
+function resetTextareaToPlaceholder(): void {
+  textarea.value = INPUT_PLACEHOLDER;
+  try {
+    textarea.setSelectionRange(INPUT_PLACEHOLDER.length, INPUT_PLACEHOLDER.length);
+  } catch {
+    // Some older WebKit builds throw on setSelectionRange against a
+    // visually-hidden textarea; ignore.
+  }
+}
+
+/** Position the composition view (and the helper textarea, which
+ *  anchors the IME popup) at the current terminal cursor pixel
+ *  position. iOS keyboards open without scrolling the layout when
+ *  the focused textarea is on screen at a sane location. */
+export function positionCompositionView(): void {
+  const { left, top, cellH } = getCursorPx();
+  compositionView.style.left = `${left}px`;
+  compositionView.style.top = `${top}px`;
+  compositionView.style.height = `${cellH}px`;
+  compositionView.style.lineHeight = `${cellH}px`;
+  // Textarea piggy-backs on the cursor position so iOS scroll-into-
+  // view targets the cursor area instead of jumping to top-left.
+  textarea.style.left = `${left}px`;
+  textarea.style.top = `${top}px`;
+  textarea.style.height = `${cellH}px`;
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+// @cplieger/web-terminal-ui — the reference touch-first browser UI built on
+// the @cplieger/web-terminal-engine engine. The public surface is a single mount()
+// call against the shipped scaffold (scaffold/index.html) + CSS (css/).
+//
+// Consumers who want a different UI should depend on @cplieger/web-terminal-engine
+// directly and wire the engine's render/scroll/connection/keyboard modules
+// to their own DOM.
+
+export { mount } from "./mount.js";
+export type { MountOptions, TerminalUI } from "./mount.js";