@cplieger/web-terminal-ui 1.0.1 → 2.1.0

package/README.md

@@ -1,14 +1,20 @@
 # @cplieger/web-terminal-ui
 
+[![npm](https://img.shields.io/npm/v/@cplieger/web-terminal-ui)](https://www.npmjs.com/package/@cplieger/web-terminal-ui)
+[![JSR](https://jsr.io/badges/@cplieger/web-terminal-ui)](https://jsr.io/@cplieger/web-terminal-ui)
+[![Test coverage](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/cplieger/web-terminal-ui/badges/coverage.json)](https://github.com/cplieger/web-terminal-ui/actions/workflows/coverage.yml)
+[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/13431/badge)](https://www.bestpractices.dev/projects/13431)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/cplieger/web-terminal-ui/badge)](https://scorecard.dev/viewer/?uri=github.com/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:
+One `mount(root)` call builds the entire terminal UI inside a single container
+element you provide and owns everything above the raw terminal:
 
-- a **display-only** `#term-output` (native text selection survives redraws)
+- a **display-only** terminal 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
@@ -20,7 +26,7 @@ everything above the raw terminal:
 - 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
+the CSS bundle and a reference HTML page. Consumers who want a different UI should
 depend on the engine directly and skip this package.
 
 ## Install
@@ -35,41 +41,73 @@ 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"' });
+Serve the bundled CSS (`css/` concatenated per `css/MANIFEST` into the
+`style.css` your page links) plus a minimal HTML page that has one empty
+container element for the terminal, then call `mount(root)` from your entry
+module:
+
+```html
+<div id="terminal"></div>
+<div id="loading">Loading…</div>
+<script type="importmap">
+  {
+    "imports": {
+      "@cplieger/web-terminal-engine": "/vendor/cplieger-web-terminal-engine/index.js",
+      "@cplieger/web-terminal-ui": "/vendor/cplieger-web-terminal-ui/index.js"
+    }
+  }
+</script>
+<script type="module">
+  import { mount } from "@cplieger/web-terminal-ui";
+  mount(document.getElementById("terminal"), {
+    loading: document.getElementById("loading"),
+  });
+  // or, for a server that exposes the WebSocket elsewhere / a custom font:
+  // mount(root, { wsPath: "/api/shell/ws", fontReady: '14px "MyMono"' });
+</script>
 ```
 
-`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.
+`mount(root, opts?)` builds the entire terminal subtree (the display output,
+the hidden keyboard textarea, the mobile key toolbar, the status banner, and
+the context menu) inside `root` itself — there is no element-id contract for
+the host page to reproduce. Call it exactly once; the module state is
+single-instance per page. `scaffold/index.html` is a complete reference page to
+copy and adapt.
 
 ### 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. |
+| 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.                        |
+| `loading`   | _(none)_                   | A pre-JS loading overlay element (kept in your served HTML so it paints before this module loads); mount fades it out and removes it once the first frame renders. |
 
 `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.          |
+| 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 page: `<head>` + one empty root element + importmap. |
+
+## Related projects
+
+The web-terminal family:
+
+- [`web-terminal-engine`](https://github.com/cplieger/web-terminal-engine) — the
+  Go session engine + TypeScript browser renderer this UI is built on (peer
+  dependency).
+- [`web-terminal-server`](https://github.com/cplieger/web-terminal-server) — a
+  ready-to-run container that serves this UI over HTTP + WebSocket for any
+  command.
+
+Consumers that ship this UI:
+
+- [`vibekit`](https://github.com/cplieger/vibekit)
+- [`vibecli`](https://github.com/cplieger/vibecli)
 
 ## License
 

package/css/00-tokens.css

@@ -30,4 +30,5 @@
   --ease-exit: cubic-bezier(0.4, 0, 1, 1);
   --blur: blur(8px);
   --safe-top: env(safe-area-inset-top, 0px);
+  --safe-bottom: env(safe-area-inset-bottom, 0px);
 }

package/css/02-app.css

@@ -48,11 +48,10 @@
    client-side cap or a server-reported resume gap). A quiet, centered,
    non-selectable divider so the user knows scrollback doesn't go further up. */
 .term-trim-marker {
-  color: color-mix(in oklch, var(--text) 45%, transparent);
+  color: color-mix(in oklch, var(--text) 60%, transparent);
   font-size: 0.6875rem;
   text-align: center;
   padding: 2px 0;
-  opacity: 0.7;
   user-select: none;
   font-family: var(--font-ui);
 }
@@ -141,10 +140,11 @@
   display: block;
 }
 
-/* Connection-state banner: floats top-center with a subtle backdrop
-   blur. Hidden until status.ts sets `.visible`. Distinct from the
-   `.pill` family because it wants to span across the full top center
-   visually rather than dock to a corner. */
+/* Connection-state banner: bottom-center on touch (lifted above the
+   virtual keyboard via --kb-inset), top-center on desktop. Subtle
+   backdrop blur. Hidden until status.ts sets `.visible`. Distinct from
+   the `.pill` family because it wants to span the full width centrally
+   rather than dock to a corner. */
 .conn-banner {
   position: fixed;
   bottom: var(--sp-3);
@@ -208,6 +208,18 @@
   }
 }
 
+/* Desktop (pointer: fine): move the banner to top-center so it no longer
+   shares the bottom-center anchor with the scroll-to-bottom FAB
+   (.kb-scroll-bottom). Sharing it let the banner (pointer-events:auto,
+   z-index:20) render over the FAB and intercept its click. Touch keeps
+   the bottom placement and the --kb-inset keyboard lift above. */
+@media (pointer: fine) {
+  .conn-banner {
+    top: var(--sp-3);
+    bottom: auto;
+  }
+}
+
 /* Clickable URLs */
 .term-link {
   color: inherit;
@@ -430,7 +442,7 @@
   z-index: 10;
   transition:
     opacity var(--dur-standard) var(--ease-standard),
-    background-color 150ms var(--ease-standard),
+    background-color var(--dur-micro) var(--ease-standard),
     display var(--dur-standard) allow-discrete;
 }
 
@@ -696,9 +708,9 @@
   opacity: 0;
   scale: 0.95;
   transition:
-    opacity 0.15s ease,
-    scale 0.15s ease,
-    display 0.15s allow-discrete;
+    opacity var(--dur-exit) var(--ease-standard),
+    scale var(--dur-exit) var(--ease-standard),
+    display var(--dur-exit) allow-discrete;
 }
 
 .ctx-menu.visible {
@@ -728,3 +740,15 @@
 .ctx-menu button:active {
   background: var(--text-active);
 }
+
+/* Touch (long-press) menu: bump the rows to the 44px --touch-target
+   standard the rest of the touch UI uses (the key-toolbar grid is
+   repeat(4, var(--touch-target))). Desktop right-click keeps the
+   compact 24px menu. padding-block re-centres the label in the taller box. */
+@media (pointer: coarse) {
+  .ctx-menu button {
+    min-height: var(--touch-target);
+    padding-block: var(--sp-2);
+    touch-action: manipulation;
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/web-terminal-ui",
-  "version": "1.0.1",
+  "version": "2.1.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",
@@ -27,13 +27,13 @@
     "@eslint/js": "10.0.1",
     "@types/node": "25.9.4",
     "@vitest/coverage-v8": "4.1.9",
-    "eslint": "10.5.0",
+    "eslint": "10.6.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",
+    "knip": "6.22.0",
+    "prettier": "3.9.0",
+    "stylelint": "17.14.0",
     "stylelint-config-standard": "40.0.0",
     "typescript": "6.0.3",
     "typescript-eslint": "8.62.0",

package/scaffold/index.html

@@ -16,37 +16,24 @@
 </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>
+<!-- mount() builds the entire terminal UI inside this single root element.
+     The loading overlay is a sibling (not a child of the root) so mount never
+     clears it; mount fades it out once the first frame renders. -->
+<div id="terminal"></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. -->
+<!-- Deployment-specific: the importmap resolves the bare package specifiers to
+     the compiled JS your build emits. Adjust the paths to your build layout. -->
 <script type="importmap">
 {
   "imports": {
-    "@cplieger/web-terminal-engine": "/vendor/cplieger-web-terminal-engine/index.js"
+    "@cplieger/web-terminal-engine": "/vendor/cplieger-web-terminal-engine/index.js",
+    "@cplieger/web-terminal-ui": "/vendor/cplieger-web-terminal-ui/index.js"
   }
 }
 </script>
-<script type="module" src="/app.js"></script>
+<script type="module">
+  import { mount } from "@cplieger/web-terminal-ui";
+  mount(document.getElementById("terminal"), { loading: document.getElementById("loading") });
+</script>
 </body>
 </html>

package/src/composition.ts

@@ -27,14 +27,9 @@
 // for the same reason.
 
 import { keyboard } from "@cplieger/web-terminal-engine";
+import { resetToPlaceholder } from "./input-placeholder.js";
 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 };
@@ -43,7 +38,6 @@ let send: (bytes: string) => void;
 let composing = false;
 let sendingComposition = false;
 let compositionStart = 0;
-let compositionEnd = 0;
 let compositionSuffix = "";
 
 export function init(opts: {
@@ -75,7 +69,7 @@ function onStart(): void {
   const start = textarea.selectionStart;
   const end = textarea.selectionEnd;
   compositionStart = Math.min(start, end);
-  compositionEnd = Math.max(start, end);
+  const compositionEnd = Math.max(start, end);
   compositionSuffix = textarea.value.substring(compositionEnd);
   compositionView.textContent = "";
   compositionView.classList.add("active");
@@ -88,12 +82,6 @@ function onUpdate(ev: CompositionEvent): void {
   // 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 {
@@ -119,7 +107,7 @@ function onEnd(): void {
     if (composed.length > 0) {
       send(composed);
     }
-    resetTextareaToPlaceholder();
+    resetToPlaceholder(textarea);
   }, 0);
 }
 
@@ -140,17 +128,7 @@ function onPaste(ev: ClipboardEvent): void {
   // 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.
-  }
+  resetToPlaceholder(textarea);
 }
 
 /** Position the composition view (and the helper textarea, which

package/src/index.ts

@@ -1,6 +1,7 @@
 // @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/).
+// the @cplieger/web-terminal-engine engine. The public surface is a single
+// mount(root) call that builds the whole terminal subtree inside a
+// host-provided element; scaffold/index.html + css/ are a reference page to copy.
 //
 // Consumers who want a different UI should depend on @cplieger/web-terminal-engine
 // directly and wire the engine's render/scroll/connection/keyboard modules

package/src/input-placeholder.ts

@@ -0,0 +1,29 @@
+// Single source of truth for the hidden-textarea placeholder shared by
+// mount.ts and composition.ts.
+//
+// A single-character placeholder is kept in the hidden textarea so iOS soft
+// keyboards have something to "delete" when the user holds Backspace. iOS only
+// fires repeating `input` events with inputType="deleteContentBackward" when
+// the textarea has content to delete; with a perpetually empty textarea,
+// holding Backspace deletes one char and stops because iOS sees nothing more to
+// remove. The placeholder itself is invisible (textarea has opacity:0) and is
+// stripped out of every send. NBSP is chosen specifically so screen-reader
+// announcement of the input state stays empty-ish rather than "space".
+//
+// The constant AND the reset routine must stay in lockstep across the two
+// modules (mount.ts seeds + re-pads it; composition.ts restores it on
+// compositionend / paste) or the iOS held-Backspace key-repeat silently breaks
+// with no compile error — which is why they live here in one place.
+export const INPUT_PLACEHOLDER = "\u00A0";
+
+// Restore the placeholder and put the cursor at the end, so the next typed
+// character appends after it rather than before.
+export function resetToPlaceholder(textarea: HTMLTextAreaElement): 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.
+  }
+}