@cplieger/web-terminal-ui 1.0.0

package/README.md

@@ -0,0 +1,76 @@
+# @cplieger/web-terminal-ui
+
+The reference touch-first browser UI for
+[`@cplieger/web-terminal-engine`](https://github.com/cplieger/web-terminal-engine) — the part
+that turns the engine's render/scroll/connection/keyboard modules into a
+usable terminal on a phone as well as a desktop.
+
+One `mount()` call wires the engine to a small HTML scaffold and owns
+everything above the raw terminal:
+
+- a **display-only** `#term-output` (native text selection survives redraws)
+- a hidden `<textarea>` that owns the keyboard, the local typing buffer, and IME
+- a **mobile key toolbar** (Tab / Esc / arrows / Enter / sticky-Ctrl) and a
+  scroll-to-bottom control
+- a **viewport-clamped context menu** (Copy / Select All / Paste)
+- **predictive local echo** so the cursor moves on keypress even on a slow link
+- **IME / composition** handling (CJK, dictation, autocorrect)
+- **viewport + keyboard-inset** handling for the iOS soft keyboard, rotation,
+  and font-load reflows
+- a connection-status banner and a copy toast
+
+It is published as TypeScript source (no build step) to npm and JSR, alongside
+the CSS bundle and an HTML scaffold. Consumers who want a different UI should
+depend on the engine directly and skip this package.
+
+## Install
+
+```sh
+npm install @cplieger/web-terminal-ui @cplieger/web-terminal-engine
+```
+
+`@cplieger/web-terminal-engine` is a peer dependency — the UI is built on the engine,
+and both halves of the wire protocol must stay in lockstep, so the consumer
+pins the engine version explicitly.
+
+## Usage
+
+Serve the scaffold (`scaffold/index.html` — copy and adapt it) and the bundled
+CSS (`css/` concatenated per `css/MANIFEST` into the `style.css` the scaffold
+links), then call `mount()` from your entry module:
+
+```ts
+import { mount } from "@cplieger/web-terminal-ui";
+
+mount();
+// or, for a server that exposes the WebSocket elsewhere / a custom font:
+mount({ wsPath: "/api/shell/ws", fontReady: '14px "MyMono"' });
+```
+
+`mount()` expects the scaffold's element ids to exist in the DOM (`term`,
+`term-output`, `term-input`, `composition-view`, `pred-cursor`, `loading`,
+`conn-banner`, `key-toolbar`, the `kb-*` buttons, `scroll-bottom`, `ctx-menu`)
+and throws a clear error if a required one is missing. Call it exactly once —
+the UI is single-instance per page.
+
+### Options
+
+| Option      | Default                    | Purpose                                                                                                                                     |
+| ----------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `wsPath`    | `"/ws"`                    | WebSocket endpoint path the engine connects to.                                                                                             |
+| `fontReady` | `'14px "MonaspiceNe NFM"'` | CSS font shorthand awaited before the first resize, so the server is sized against the real web font's cell metrics rather than a fallback. |
+
+`mount()` returns a small handle: `{ focus() }` re-focuses the terminal input
+(and opens the soft keyboard on touch).
+
+## What ships
+
+| Path                     | Purpose                                                           |
+| ------------------------ | ----------------------------------------------------------------- |
+| `src/*.ts`               | The UI modules (`mount`, IME, predictive echo, viewport, status). |
+| `css/*.css` + `MANIFEST` | The default theme + layout; concatenate in MANIFEST order.        |
+| `scaffold/index.html`    | A reference HTML scaffold with the required element ids.          |
+
+## License
+
+GPL-3.0-or-later. See `LICENSE`.

package/css/00-tokens.css

@@ -0,0 +1,33 @@
+/* ===== Tokens ===== */
+:root {
+  interpolate-size: allow-keywords;
+
+  --bg: oklch(0% 0 0deg);
+  --surface: oklch(16% 0.005 280deg / 70%);
+  --border: oklch(100% 0 0deg / 15%);
+  --text: oklch(90% 0.005 280deg);
+  --text-active: color-mix(in oklch, var(--text) 15%, transparent);
+  --radius: 0.75rem;
+  --radius-inner: 0.5rem;
+  --touch-target: 2.75rem; /* 44px — Apple HIG minimum */
+  --pill-outer: calc(
+    var(--touch-target) + 2 * var(--sp-1) + 2px
+  ); /* touch-target + 2×padding + 2×border */
+
+  --icon: 1.125rem; /* 18px */
+  --icon-desktop: 1rem; /* 16px */
+  --sp-1: 0.25rem;
+  --sp-2: 0.5rem;
+  --sp-3: 0.75rem;
+  --font-ui: -apple-system, blinkmacsystemfont, "SF Pro Text", system-ui, sans-serif;
+  --font-mono: "MonaspiceNe NFM", monospace;
+  --dur-micro: 0.1s;
+  --dur-standard: 0.2s;
+  --dur-enter: 0.25s;
+  --dur-exit: 0.15s;
+  --ease-standard: cubic-bezier(0.2, 0, 0, 1);
+  --ease-enter: cubic-bezier(0, 0, 0, 1);
+  --ease-exit: cubic-bezier(0.4, 0, 1, 1);
+  --blur: blur(8px);
+  --safe-top: env(safe-area-inset-top, 0px);
+}

package/css/01-reset.css

@@ -0,0 +1,73 @@
+/* ===== Reset ===== */
+*,
+*::before,
+*::after {
+  box-sizing: border-box;
+}
+
+html,
+body {
+  margin: 0;
+  padding: 0;
+  height: 100%;
+  overflow: hidden;
+  background: var(--bg);
+  color-scheme: dark;
+  -webkit-font-smoothing: antialiased;
+  text-size-adjust: 100%;
+  overscroll-behavior: none;
+  /* Disable pinch-to-zoom and double-tap-to-zoom. The viewport meta tag
+     blocks browser zoom; touch-action: pan-x pan-y additionally lets only
+     scroll/pan gestures through, blocking the pinch-zoom and double-tap-zoom
+     gestures iOS Safari otherwise still honors. */
+  touch-action: pan-x pan-y;
+}
+
+/* stylelint-disable declaration-no-important, time-min-milliseconds --
+   Canonical prefers-reduced-motion override. !important and near-zero
+   durations are required to forcibly defeat any animation/transition rule
+   regardless of specificity, which is the whole point of this a11y reset. */
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+}
+/* stylelint-enable declaration-no-important, time-min-milliseconds */
+
+/* ===== Fonts ===== */
+@font-face {
+  font-family: "MonaspiceNe NFM";
+  src: url("/vendor/fonts/MonaspiceNeNerdFontMono-Regular.otf") format("opentype");
+  font-weight: 400;
+  font-style: normal;
+  font-display: block;
+}
+
+@font-face {
+  font-family: "MonaspiceNe NFM";
+  src: url("/vendor/fonts/MonaspiceNeNerdFontMono-Bold.otf") format("opentype");
+  font-weight: 700;
+  font-style: normal;
+  font-display: block;
+}
+
+@font-face {
+  font-family: "MonaspiceNe NFM";
+  src: url("/vendor/fonts/MonaspiceNeNerdFontMono-Italic.otf") format("opentype");
+  font-weight: 400;
+  font-style: italic;
+  font-display: block;
+}
+
+@font-face {
+  font-family: "MonaspiceNe NFM";
+  src: url("/vendor/fonts/MonaspiceNeNerdFontMono-BoldItalic.otf") format("opentype");
+  font-weight: 700;
+  font-style: italic;
+  font-display: block;
+}