@cplieger/web-terminal-ui 7.2.2 → 7.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/README.md +18 -6
  2. package/css/00-tokens.css +21 -1
  3. package/css/02-terminal.css +3 -1
  4. package/css/page.css +59 -1
  5. package/package.json +1 -1
  6. package/src/kernel/kernel.ts +57 -5
package/README.md CHANGED
@@ -63,10 +63,16 @@ page that has one empty container element, then call
63
63
  **Full-page host** (the terminal IS the page, as in `web-terminal-server` and
64
64
  `web-terminal-kiro`): concatenate `css/MANIFEST` into the `style.css` your page
65
65
  links. That reference bundle is `css/page.css` (the page kit: `html/body`
66
- reset + the bundled web font's `@font-face`, expecting the font files at
67
- `/vendor/fonts/`) plus the complete component set. The bundled font backs both
68
- the terminal display and the chrome text, so serving those files is not
69
- optional for a full-page host.
66
+ reset + the `@font-face` rules for two families, expecting the font files at
67
+ `/vendor/fonts/`) plus the complete component set. The set is the four
68
+ `MonaspaceNeonNF-*.woff2` faces, which back both the terminal display and the
69
+ chrome text, plus `WebTerminalGlyphs.woff2` — a tiling overlay that supplies the
70
+ box-drawing, block, braille and powerline cells the terminal draws — served
71
+ alongside that font's `LICENSE` and `NOTICE`. Serving the Monaspace faces is not
72
+ optional for a full-page host. A host that has not yet added the overlay file
73
+ degrades cleanly rather than breaking: the face errors out, and the terminal
74
+ renders exactly as it did before, with the tiling ranges coming from Monaspace
75
+ and the system font.
70
76
 
71
77
  **Embedder** (the terminal lives inside your app's layout, as a panel or pane):
72
78
  concatenate the per-preset manifest matching your composition instead:
@@ -185,7 +191,7 @@ are importable from `…/features/<name>` (`clipboard`, `context-menu`,
185
191
  | `features` | _(none; bare kernel)_ | A FUNCTION returning the feature list. Omitted builds only the terminal (no chrome). Pass a preset by name (`features: presetTabbed`) or a factory of your own; it is called inside the startup-failure boundary, so a preset that throws is handled rather than escaping. |
186
192
  | `layout` | `"viewport"` | How the terminal claims space. `"viewport"`: the root becomes a fixed full-viewport box (the full-page product). `"container"`: the root fills your container element, which becomes the styling and positioning boundary (the embedded case). |
187
193
  | `wsPath` | `"/ws"` | WebSocket endpoint path the engine connects to. |
188
- | `fontReady` | `'14px "Monaspace Neon NF"'` | 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. |
194
+ | `fontReady` | `'14px "Monaspace Neon NF"'` | 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. Only the family that CARRIES those metrics is named: the tiling overlay copies them and holds no letter for the width probe to measure, and naming it as well would open the gate on the overlay alone in WebKit (Safari, every iOS browser), while Monaspace was still loading. The wait is bounded at 3s whatever the fonts do, the `font-display: block` period the bundled faces declare, so a request that stalls leaves the terminal sized on fallback metrics rather than never sized at all, and a font that lands after the bound costs one corrective resize. |
189
195
  | `scrollbackLines` | _(engine default)_ | Retained scrollback lines per terminal, and per tab under the tabs feature (every per-tab cache is built through the same budget). This is the page's dominant memory dial: it bounds the styled-run arrays each session retains AND the DOM rows the renderer keeps (one row element per retained line), so a memory-constrained host (iOS Safari, where the content process is reclaimed under system pressure) passes a smaller budget at the price of a shorter scroll-back. A history budget floored at the live screen: the engine never evicts the current window, so a value at or below the terminal height keeps the full screen with no scrollback, but choose a value comfortably above the largest expected terminal height (a few multiples), since near or below it the batched eviction degrades to per-line churn. Non-integer or non-positive values are ignored. Left unset, the engine decides, and it decides twice: 5000 against a server that cannot serve history back, dropping to a 1500-line resident tail plus an on-demand cache once a server declares demand-paged scrollback. Prefer leaving it unset: the depth then lives on the server and the phone holds a working set. An explicit value opts OUT of that flip: it is an explicit memory decision and holds in both states. |
190
196
  | `persistScrollback` | _(off)_ | Persist each session's scrollback across a page discard, through storage YOU supply. A page that is discarded and reloaded otherwise resumes holding nothing, so it asks the server for everything and refills its whole buffer over the wire (the normal case on iOS, where Safari evicts backgrounded tabs under memory pressure and returning to one re-runs the page). With a snapshot restored, the resume asks only for what was printed while the tab was gone. It helps the FRESH-LOAD case only: a warm reconnect and an in-page tab switch already replay nothing. Off by default because `localStorage` is a shared, origin-wide, quota-limited resource and this library is embedded in applications that keep their own state there: an application decides durability for its own users, a library does not decide it for an embedder. Applies to a single terminal and to every tab alike. See below. |
191
197
  | `loading` | _(none)_ | A pre-JS loading overlay element (kept in your served HTML so it paints before this module loads); it is faded out and removed once the first frame renders. |
@@ -485,7 +491,7 @@ about your server rather than about this terminal.
485
491
  | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
486
492
  | `src/**/*.ts` | The UI modules: the kernel (`kernel/`), opt-in features (`features/`), per-preset entries (`presets/`), IME, predictive echo, viewport. |
487
493
  | `css/*.css` + manifests | Root-scoped component styles. `MANIFEST` = the reference full-page bundle (`page.css` + the tabbed set); `MANIFEST.single/touch/tabbed` = component-only per-preset bundles for embedders. Concatenate in manifest order. |
488
- | `css/page.css` | The page kit (full-page hosts only): `html/body` reset + the terminal web font's `@font-face`. |
494
+ | `css/page.css` | The page kit (full-page hosts only): `html/body` reset + the `@font-face` rules for the terminal's two web fonts, `Monaspace Neon NF` and the `Web Terminal Glyphs` tiling overlay. |
489
495
  | `scaffold/index.html` | A reference full-page HTML host: `<head>` + one empty root element + importmap. |
490
496
 
491
497
  ## Related projects
@@ -518,3 +524,9 @@ This project was built with AI-assisted tooling using [Claude](https://claude.co
518
524
  ## License
519
525
 
520
526
  MPL-2.0. See [LICENSE](LICENSE).
527
+
528
+ The `Web Terminal Glyphs` tiling overlay named in `css/page.css` is a separate
529
+ Apache-2.0 work, and its licence travels with the FONT FILE — which this package
530
+ does not ship, it only names the URL. So no new obligation lands on an npm or JSR
531
+ consumer; the obligation is the serving host's, which is why the full-page host
532
+ notes above ask for the font's `LICENSE` and `NOTICE` beside the `.woff2`.
package/css/00-tokens.css CHANGED
@@ -141,7 +141,27 @@
141
141
  strip (MANIFEST.touch excludes 30-tabs.css), so nothing metric-dependent
142
142
  rides on that fallback. */
143
143
  --font-ui: "Monaspace Neon NF", ui-monospace, monospace;
144
- --font-mono: "Monaspace Neon NF", monospace;
144
+ /* The terminal display is an OVERLAY over a companion: "Web Terminal Glyphs"
145
+ is a tiling-only face (box drawing, blocks, braille, powerline — 1,098
146
+ codepoints, no letters, no digits, not even a space), so the browser takes
147
+ those cells from it and everything else from Monaspace by ordinary family
148
+ fallback. It leads deliberately, so its cell-exact glyphs win where the
149
+ companion also has a codepoint; carrying no text glyphs, it cannot move the
150
+ companion's metrics or its look. page.css declares the four faces and owns
151
+ the rest of the reasoning.
152
+
153
+ --font-ui above does NOT get the overlay, and that is a scope choice rather
154
+ than an omission: the chrome renders labels and never a tiling codepoint, so
155
+ the overlay would be a family the browser consults on every glyph and never
156
+ draws from. It would not cost a label geometry to add it — the overlay's
157
+ vertical metrics are copied from the companion (the upstream font's
158
+ dist/cell.json, 1890/-400/200 with USE_TYPO_METRICS set on both), so the
159
+ line box is the same either way. The reason to keep the chrome's stack at one
160
+ family is least mechanism, and --label-ink-shift below is why that matters:
161
+ it is written from the line box the engine actually built
162
+ (src/features/tabs/ink-centre.ts), so anything that DOES move the chrome's
163
+ metrics lands straight in the chip labels. */
164
+ --font-mono: "Web Terminal Glyphs", "Monaspace Neon NF", monospace;
145
165
  /* Pre-measurement default for the chip labels' ink centring; the tabs feature
146
166
  writes a measured px value per site (src/features/tabs/ink-centre.ts owns
147
167
  why). Zero: flex centring already lands within 0.4px of the cap band, and is
package/css/02-terminal.css CHANGED
@@ -45,7 +45,9 @@
45
45
  touch-action: pan-x pan-y;
46
46
  font-family: var(--font-mono);
47
47
  /* Bold and italic are real faces (page.css); a synthesized stand-in must
48
- never be drawn in their place. */
48
+ never be drawn in their place. Not redundant with those declarations: Blink
49
+ obliques an italic run over the tiling overlay despite its exact italic face,
50
+ so this line is the only thing keeping box drawing upright there. */
49
51
  font-synthesis: none;
50
52
  font-size: 14px;
51
53
  /* The cell height. The engine reads it (render.ts updateFontMetrics) and sizes
package/css/page.css CHANGED
@@ -236,7 +236,33 @@ body {
236
236
  monospace stack.
237
237
 
238
238
  No face carries ascent-override or descent-override: the terminal's cell
239
- background is the run padding in 02-terminal.css, never these metrics. */
239
+ background is the run padding in 02-terminal.css, never these metrics.
240
+
241
+ The tiling overlay, "Web Terminal Glyphs", is the second family below, and it
242
+ is ONE file declared under FOUR descriptor sets. The released face is a single
243
+ upright 400 weight, so a lone rule would leave the engine free to synthesise a
244
+ stand-in for a bold or italic run. What the four sets (400/700 x normal/italic)
245
+ against the same URL foreclose is the EMBOLDENED stand-in, in Blink and in
246
+ Gecko both: a bold run resolves a real face where the same asset under one rule
247
+ is thickened. They do NOT foreclose the OBLIQUE one in Blink, which honours the
248
+ italic descriptor for face SELECTION and slants the run anyway; the only thing
249
+ keeping an italic box-drawing corner upright there is font-synthesis: none on
250
+ .term (02-terminal.css). Both mechanisms are load-bearing and neither is the
251
+ whole guarantee. All four rules point at one file, so the bytes download once.
252
+
253
+ No overlay face declares unicode-range, and that absence is deliberate: the
254
+ font's own cmap IS its range (1,098 tiling codepoints, no letters, no digits,
255
+ no space), so a letter falls through to Monaspace by ordinary family fallback,
256
+ and a range here would only narrow that fallback to a list somebody has to
257
+ maintain against the next release of the font.
258
+
259
+ The overlay is listed FIRST in --font-mono and never in --font-ui
260
+ (00-tokens.css owns why). A full-page host must serve
261
+ WebTerminalGlyphs.woff2 beside the Monaspace faces, along with that font's
262
+ LICENSE and NOTICE: it is a separate Apache-2.0 work, and §4 binds whoever
263
+ ships the bytes. This package ships none, it only names the URL — so a host
264
+ that has not caught up errors the face out and renders exactly as it did
265
+ before, with the tiling ranges coming from Monaspace and the system font. */
240
266
  @font-face {
241
267
  font-family: "Monaspace Neon NF";
242
268
  src: url("/vendor/fonts/MonaspaceNeonNF-Regular.woff2") format("woff2");
@@ -268,3 +294,35 @@ body {
268
294
  font-style: italic;
269
295
  font-display: block;
270
296
  }
297
+
298
+ @font-face {
299
+ font-family: "Web Terminal Glyphs";
300
+ src: url("/vendor/fonts/WebTerminalGlyphs.woff2") format("woff2");
301
+ font-weight: 400;
302
+ font-style: normal;
303
+ font-display: block;
304
+ }
305
+
306
+ @font-face {
307
+ font-family: "Web Terminal Glyphs";
308
+ src: url("/vendor/fonts/WebTerminalGlyphs.woff2") format("woff2");
309
+ font-weight: 700;
310
+ font-style: normal;
311
+ font-display: block;
312
+ }
313
+
314
+ @font-face {
315
+ font-family: "Web Terminal Glyphs";
316
+ src: url("/vendor/fonts/WebTerminalGlyphs.woff2") format("woff2");
317
+ font-weight: 400;
318
+ font-style: italic;
319
+ font-display: block;
320
+ }
321
+
322
+ @font-face {
323
+ font-family: "Web Terminal Glyphs";
324
+ src: url("/vendor/fonts/WebTerminalGlyphs.woff2") format("woff2");
325
+ font-weight: 700;
326
+ font-style: italic;
327
+ font-display: block;
328
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cplieger/web-terminal-ui",
3
- "version": "7.2.2",
3
+ "version": "7.3.0",
4
4
  "type": "module",
5
5
  "description": "Reference touch-first browser UI for @cplieger/web-terminal-engine: a composable kernel + feature modules (tabs, activity monitor, mobile toolbar, context menu, IME, predictive echo, viewport handling) and CSS. One createTerminal() call.",
6
6
  "license": "MPL-2.0",
package/src/kernel/kernel.ts CHANGED
@@ -54,7 +54,23 @@ import type {
54
54
  const { mapKeyboardEvent, bracketTextForPaste, prepareTextForTerminal } = keyboard;
55
55
 
56
56
  const DEFAULT_WS_PATH = "/ws";
57
+ // The family that carries the CELL METRICS, alone: deliberately not --font-mono's
58
+ // list, which leads with the tiling overlay. WebKit resolves load() over a list as
59
+ // soon as the FIRST family whose descriptor covers the sample has loaded
60
+ // (CSSFontFaceSet::matchingFacesExcludingPreinstalledFonts, `if (found) break;`),
61
+ // so naming the overlay would settle the gate on its 11 KB while the companion is
62
+ // still loading — and the overlay copies the companion's metrics and carries no
63
+ // "M", the glyph render.ts measures, so waiting on it defends no number anyway.
57
64
  const DEFAULT_FONT_READY = '14px "Monaspace Neon NF"';
65
+ // The deadline on the WHOLE gate below, because neither document.fonts.load nor
66
+ // document.fonts.ready carries one: a response held open leaves both pending for
67
+ // as long as that request lives, and a gate that never settles reports no size at
68
+ // all. The budget is the block period the faces themselves buy with font-display:
69
+ // block (css/page.css declares it on every one; 3s is what CSS Fonts 4 recommends
70
+ // for `block`) — how long an engine withholds glyphs before it paints the
71
+ // fallback. Once it has, the cell on screen IS the fallback cell, so a longer wait
72
+ // defends metrics nobody is looking at.
73
+ const FONT_READY_TIMEOUT_MS = 3000;
58
74
 
59
75
  const TOAST_MS = 3000;
60
76
  // A touch that focuses the input (opens the soft keyboard) must be a genuine
@@ -1383,13 +1399,49 @@ function buildTerminal(
1383
1399
  });
1384
1400
  };
1385
1401
  try {
1386
- void document.fonts
1387
- .load(fontReady)
1388
- .then(onFontSettled)
1389
- .catch((err: unknown) => {
1402
+ // false once the fonts have landed, true when the deadline opened the gate
1403
+ // without them. The race covers the whole wait, not just the rejection arm: a
1404
+ // request that stalls with nothing rejecting leaves load() ITSELF pending, so a
1405
+ // deadline armed on the rejection would bound one of the ways a font can hang.
1406
+ const landed: Promise<boolean> = document.fonts.load(fontReady).then(
1407
+ () => false,
1408
+ (err: unknown) => {
1390
1409
  console.warn(`web-terminal-ui: web font ${fontReady} failed to load`, err);
1391
- onFontSettled();
1410
+ // One load() over a comma-separated stack rejects as a UNIT, so settling
1411
+ // here would let an unavailable OPTIONAL family abandon the gate for the
1412
+ // REQUIRED one and announce a size measured on fallback metrics. `ready`
1413
+ // settles the initial load INCLUDING a failed one (the same property
1414
+ // features/tabs/ink-centre.ts relies on), so the families that ARE served
1415
+ // still land their bytes before the first resize is measured.
1416
+ return document.fonts.ready.then(() => false);
1417
+ },
1418
+ );
1419
+ const deadline = new Promise<boolean>((resolve) => {
1420
+ window.setTimeout(() => {
1421
+ resolve(true);
1422
+ }, FONT_READY_TIMEOUT_MS);
1423
+ });
1424
+ // Whichever settles first opens the gate exactly once; the loser is ignored.
1425
+ void Promise.race([landed, deadline]).then((timedOut) => {
1426
+ onFontSettled();
1427
+ if (!timedOut) {
1428
+ return;
1429
+ }
1430
+ // The gate opened on fallback metrics, and the swap period is infinite: bytes
1431
+ // that land after this change the cell width with fontsLoaded already true,
1432
+ // and nothing re-measures until the next viewport transition. So one
1433
+ // corrective announce, through the path the viewport settle uses.
1434
+ // sendResize deduplicates, so a font that never lands costs nothing.
1435
+ void document.fonts.ready.then(() => {
1436
+ // The bytes can arrive arbitrarily late, so this is the one arm of the gate
1437
+ // that outlives its terminal; destroy() wins, as it does for a feature's
1438
+ // un-cancelled async.
1439
+ if (isDestroyed() || measurableSize() === null) {
1440
+ return;
1441
+ }
1442
+ connection.sendResize();
1392
1443
  });
1444
+ }, onFontSettled);
1393
1445
  } catch (err) {
1394
1446
  console.warn(`web-terminal-ui: invalid fontReady ${fontReady}`, err);
1395
1447
  onFontSettled();