@cplieger/web-terminal-ui 7.2.1 → 7.3.0

package/README.md

@@ -63,10 +63,16 @@ page that has one empty container element, then call
 **Full-page host** (the terminal IS the page, as in `web-terminal-server` and
 `web-terminal-kiro`): concatenate `css/MANIFEST` into the `style.css` your page
 links. That reference bundle is `css/page.css` (the page kit: `html/body`
-reset + the bundled web font's `@font-face`, expecting the font files at
-`/vendor/fonts/`) plus the complete component set. The bundled font backs both
-the terminal display and the chrome text, so serving those files is not
-optional for a full-page host.
+reset + the `@font-face` rules for two families, expecting the font files at
+`/vendor/fonts/`) plus the complete component set. The set is the four
+`MonaspaceNeonNF-*.woff2` faces, which back both the terminal display and the
+chrome text, plus `WebTerminalGlyphs.woff2` — a tiling overlay that supplies the
+box-drawing, block, braille and powerline cells the terminal draws — served
+alongside that font's `LICENSE` and `NOTICE`. Serving the Monaspace faces is not
+optional for a full-page host. A host that has not yet added the overlay file
+degrades cleanly rather than breaking: the face errors out, and the terminal
+renders exactly as it did before, with the tiling ranges coming from Monaspace
+and the system font.
 
 **Embedder** (the terminal lives inside your app's layout, as a panel or pane):
 concatenate the per-preset manifest matching your composition instead:
@@ -185,7 +191,7 @@ are importable from `…/features/<name>` (`clipboard`, `context-menu`,
 | `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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | `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).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | `wsPath`            | `"/ws"`                      | WebSocket endpoint path the engine connects to.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| `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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | `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. |
 | `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.                                                                                                                                                                                                                                                                                                                                                                                              |
 | `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.
 | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `src/**/*.ts`           | The UI modules: the kernel (`kernel/`), opt-in features (`features/`), per-preset entries (`presets/`), IME, predictive echo, viewport.                                                                                   |
 | `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. |
-| `css/page.css`          | The page kit (full-page hosts only): `html/body` reset + the terminal web font's `@font-face`.                                                                                                                            |
+| `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.                                       |
 | `scaffold/index.html`   | A reference full-page HTML host: `<head>` + one empty root element + importmap.                                                                                                                                           |
 
 ## Related projects
@@ -518,3 +524,9 @@ This project was built with AI-assisted tooling using [Claude](https://claude.co
 ## License
 
 MPL-2.0. See [LICENSE](LICENSE).
+
+The `Web Terminal Glyphs` tiling overlay named in `css/page.css` is a separate
+Apache-2.0 work, and its licence travels with the FONT FILE — which this package
+does not ship, it only names the URL. So no new obligation lands on an npm or JSR
+consumer; the obligation is the serving host's, which is why the full-page host
+notes above ask for the font's `LICENSE` and `NOTICE` beside the `.woff2`.

package/css/00-tokens.css

@@ -141,35 +141,31 @@
      strip (MANIFEST.touch excludes 30-tabs.css), so nothing metric-dependent
      rides on that fallback. */
   --font-ui: "Monaspace Neon NF", ui-monospace, monospace;
-  --font-mono: "Monaspace Neon NF", monospace;
-  /* How far a chip label's INK sits below its line box's centre, so flex
-     centring can be corrected by exactly that much (see .wt-tab-label in
-     30-tabs.css). The band is the CAP band — cap top to baseline, the visible
-     mass of a label — not cap-to-descender, which reserves empty descender room
-     below the letters and reads high (measured: 1.32px above the chip's centre
-     at 13px, while the dot and close glyph beside it sat at 0.00px).
+  /* The terminal display is an OVERLAY over a companion: "Web Terminal Glyphs"
+     is a tiling-only face (box drawing, blocks, braille, powerline — 1,098
+     codepoints, no letters, no digits, not even a space), so the browser takes
+     those cells from it and everything else from Monaspace by ordinary family
+     fallback. It leads deliberately, so its cell-exact glyphs win where the
+     companion also has a codepoint; carrying no text glyphs, it cannot move the
+     companion's metrics or its look. page.css declares the four faces and owns
+     the rest of the reasoning.
 
-     This value is only the PRE-MEASUREMENT DEFAULT — what the first paint uses
-     before the tabs feature replaces it, per site, with a pixel value measured
-     in the live engine (src/features/tabs/ink-centre.ts). It is not the answer,
-     because no single value can be: engines round the font's ascent and descent
-     to whole CSS pixels before building the line box, so the ideal shift is a
-     sawtooth in font size rather than a ratio, and on the cap band it does not
-     even keep one sign. Measured against the bundled font it runs from about
-     -0.021em (Blink 151 at 13px, a 17px box) to +0.028em (Gecko at 14px, where
-     the box is 17px against Blink's 18px), and platforms disagree inside one
-     engine too (iOS reads metrics through CoreText, Linux WebKit through
-     FreeType) — which is why four hardcoded constants each held only where they
-     were tuned.
-
-     ZERO is the default because the whole range is within ~0.03em of it: flex
-     centring of the font box is already within 0.4px of cap-band centring, so
-     the first paint starts uncorrected and the measurement lands within a frame.
-     That is also the best behaviour if the measurement never runs at all (no
-     canvas, a display:none probe): 0.4px out rather than the 1.3px a
-     descender-inclusive constant was. Do not tune it by eye — a wrong default is
-     invisible the moment the measured value arrives, so eye-tuning it optimises
-     nothing and pins the wrong number in place. */
+     --font-ui above does NOT get the overlay, and that is a scope choice rather
+     than an omission: the chrome renders labels and never a tiling codepoint, so
+     the overlay would be a family the browser consults on every glyph and never
+     draws from. It would not cost a label geometry to add it — the overlay's
+     vertical metrics are copied from the companion (the upstream font's
+     dist/cell.json, 1890/-400/200 with USE_TYPO_METRICS set on both), so the
+     line box is the same either way. The reason to keep the chrome's stack at one
+     family is least mechanism, and --label-ink-shift below is why that matters:
+     it is written from the line box the engine actually built
+     (src/features/tabs/ink-centre.ts), so anything that DOES move the chrome's
+     metrics lands straight in the chip labels. */
+  --font-mono: "Web Terminal Glyphs", "Monaspace Neon NF", monospace;
+  /* Pre-measurement default for the chip labels' ink centring; the tabs feature
+     writes a measured px value per site (src/features/tabs/ink-centre.ts owns
+     why). Zero: flex centring already lands within 0.4px of the cap band, and is
+     the best answer when the measurement cannot run. Do not tune it by eye. */
   --label-ink-shift: 0em;
   --dur-micro: 0.1s;
   --dur-standard: 0.2s;

package/css/02-terminal.css

@@ -44,13 +44,15 @@
      (WebKit bug 240917), which the switcher-bar gesture relies on. */
   touch-action: pan-x pan-y;
   font-family: var(--font-mono);
+  /* Bold and italic are real faces (page.css); a synthesized stand-in must
+     never be drawn in their place. Not redundant with those declarations: Blink
+     obliques an italic run over the tiling overlay despite its exact italic face,
+     so this line is the only thing keeping box drawing upright there. */
+  font-synthesis: none;
   font-size: 14px;
-  /* The cell height. It is PAIRED with the bundled font's overridden vertical
-     metrics (page.css): a cell's background is painted by an inline span, whose
-     box comes from the font's ascent + descent, so those must stay >= this value
-     or every row boundary shows an unpainted stripe. Changing either number
-     alone reopens that gap. The engine reads this as its cell height
-     (render.ts updateFontMetrics) and sizes the PTY from it. */
+  /* The cell height. The engine reads it (render.ts updateFontMetrics) and sizes
+     the PTY from it. The row background owes it nothing: see the run padding
+     below. */
   line-height: 17px;
   padding: 4px;
   background: var(--bg);
@@ -82,6 +84,14 @@
   content: "\00a0";
 }
 
+/* The cell background is THIS padding, not the font: an inline run paints its
+   font's content area (16px of the 17px row), and shipping Safari has no
+   ascent-override to widen it (webkit.org/b/219735, fixed in trunk 2026-08). */
+:where(.wt-root) .term-row span,
+:where(.wt-root) .term-row a {
+  padding-block: 1px;
+}
+
 /* "earlier output trimmed" marker (vterm renderer inserts .term-trim-marker
    as the first row when history older than the buffer holds was evicted —
    client-side cap or a server-reported resume gap). A quiet, centered,
@@ -91,6 +101,7 @@
   font-size: 0.6875rem;
   text-align: center;
   padding: 2px 0;
+  -webkit-user-select: none;
   user-select: none;
   font-family: var(--font-ui);
 }
@@ -141,12 +152,12 @@
      explicitly and must never let an ancestor override them. `user-select`
      is spec'd as non-inherited but WebKit/Chromium treat it as inherited,
      so a stray `user-select: none` on html/body/.term would silently kill
-     selection here; keep it `text` (modern Safari honors the unprefixed
-     form, so no `-webkit-` pair is needed). `-webkit-touch-callout: default`
+     selection here; keep it `text`. `-webkit-touch-callout: default`
      keeps the iOS callout (a page-level `none` suppresses it) and has no
      standard equivalent. No JS may `preventDefault` a touch/pointer/
      contextmenu over this element or the native selection dies (see the
      kernel focus handling + contextMenu feature). */
+  -webkit-user-select: text;
   user-select: text;
   -webkit-touch-callout: default;
 

package/css/30-tabs.css

@@ -152,6 +152,7 @@
   font-size: 0.8125rem;
   cursor: pointer;
   white-space: nowrap;
+  -webkit-user-select: none;
   user-select: none;
   /* Kills the 300ms double-tap-to-zoom delay, which is what makes a double-TAP
      usable as the touch rename entry: on iPadOS a long-press on this chip starts
@@ -224,81 +225,22 @@
   background: color-mix(in oklch, var(--tab-active-bg), var(--tab-active-fg) 22%);
 }
 
-/* The label flexes to fill the fixed-width tab and truncates with an ellipsis
-   (min-width: 0 lets a flex item shrink below its content width), and it owns the
-   ink-centring geometry the two switcher labels in 31-switcher.css share verbatim.
-
-   Centre the INK, not the line box. A font's metrics box reaches far higher above
-   the baseline than below it (the bundled font: 0.995em over, 0.250em under),
-   while the ink of a mixed-case title runs ~0.734em over (cap height) to ~0.203em
-   under (descender). Flex centring centres the BOX, which leaves the visible text
-   --label-ink-shift low — reading as baseline-aligned with the activity dot's
-   bottom edge instead of level with its centre. Two declarations, one job, and a
-   third that must NOT be added:
-
-   The band being centred is cap top to BASELINE. Descender ink is deliberately
-   outside it: including it reserves empty room below the letters, and the label
-   then reads HIGH — measured on this chip at 13px, the title's cap band sat
-   1.32px above the chip's centre while the dot and the close glyph beside it sat
-   at 0.00px. Same edges as `text-box-edge: cap alphabetic`. Descenders overhang
-   the band, which is what the padding below is for.
-
-   - padding-block is the ink allowance, not spacing. `overflow: hidden` (which
-     the ellipsis requires) clips at the padding box, and the line box clears the
-     tallest ink by only 0.6px, so an unpadded label shaves the top off every
-     acute accent and caron. 0.125em per side buys 2.2px of clearance at 13px, and
-     being symmetric it does not move the centred text.
-   - margin-block hangs TWICE the shift below the box. Flex centring centres the
-     MARGIN box, so a bottom-heavy margin lifts the border box by half of it --
-     exactly one shift -- and unlike padding it does not enlarge the clipping box.
-     The shift can be NEGATIVE (a top-heavy margin, pushing the box down) at sizes
-     where the engine's rounding already overshoots; that is a normal outcome of
-     the measurement, not a sign the arithmetic is inverted.
-   - line-height stays at `normal`, deliberately. Setting it looks like the
-     responsible thing to do and it is the trap: `normal` is the ONE value whose
-     half-leading is zero by definition, which is what makes the baseline sit at
-     exactly the engine's ascent below the box top. Any other value leaves
-     (line-height - font box) / 2 to be halved and rounded, and Chromium floors
-     it -- measured with an explicit 1.25 the 14px switcher labels came out a
-     FULL pixel high (line box 17.5 under an 18px font box, so half-leading
-     -0.25 floored to -1) while the 13px strip label was fine, which is exactly
-     the kind of works-where-I-looked bug this rule exists to end.
-
-   --label-ink-shift is MEASURED, not declared. The tabs feature writes a pixel
-   value per site from the line box the running engine produced for this font at
-   this size (src/features/tabs/ink-centre.ts); the em value in 00-tokens.css is
-   only what the first paint uses, and it is 0 because the cap-band correction is
-   within 0.4px of nothing on every engine measured. Four earlier fixes were
-   constants, and the reason none held is that engines round the font's ascent and
-   descent to whole CSS pixels before laying out the line box, so the required
-   shift is a sawtooth in font size, not a ratio: on the cap band it runs from
-   about -0.021em (Blink 151 at 13px, a 17px box) to +0.0279em (Gecko at 14px,
-   where the box is 17px against Blink's 18px), changing sign along the way,
-   because 0.25em x 13 = 3.25 and 0.25em x 14 = 3.5 round to different whole
-   pixels. The three engines
-   also report slightly different ink extents for one font file (cap 0.7344 /
-   0.7350 / 0.7300em in WebKit, Blink and Gecko), and iOS resolves metrics through
-   CoreText where Linux WebKit uses FreeType — which is why the 13px strip
-   measured centred in every local check and still read high on an
-   iPad. Nothing here is tunable by eye; if the centring looks wrong, run
-   scripts/verify-chip-geometry.mjs and fix what it measures.
-
-   What this deliberately does NOT use is `text-box: trim-both`, which three of
-   the four previous attempts were built on. It ships in Blink and WebKit only
-   (Firefox 151 still reports false for it), so it can only be applied behind an
-   @supports gate, and a gate means two engines render two different geometries of
-   which only the one the author is looking at ever gets tuned. Trimming to
-   `cap alphabetic` and giving the descender back as asymmetric padding IS
-   size-independent and holds to 0.05px in both engines that implement it — but
-   ungated it swings to 0.39px in Firefox, and a measured shift needs no gate and
-   no second code path to beat it. */
+/* Centres the label's INK (cap top to baseline), not its line box; the shift is
+   measured per site by features/tabs/ink-centre.ts, which owns why. Not
+   `text-box: trim-both` (Firefox lacks it; a gate is two geometries, one
+   untuned), and `line-height` stays `normal`: Chromium floors any other
+   half-leading (1.25 put 14px labels a pixel high). */
 :where(.wt-root) .wt-tab-label {
   flex: 1 1 auto;
   min-width: 0;
   overflow: hidden;
   white-space: nowrap;
   text-overflow: ellipsis;
+  /* The ink allowance `overflow: hidden` needs (the line box clears an accent by
+     ~0.6px); symmetric, so it moves nothing. */
   padding-block: 0.125em;
+  /* Flex centres the MARGIN box, so twice the shift below lifts the border box
+     by one shift without growing the clip. A negative shift is a normal result. */
   margin-block: 0 calc(2 * var(--label-ink-shift));
 }
 
@@ -553,6 +495,7 @@
      even though the property is non-inherited per spec (the same deviation the
      touch model documents for .term-output). Without this, caret placement and
      text selection break inside the field in Safari — i.e. on the iPad. */
+  -webkit-user-select: text;
   user-select: text;
   /* The chip is cursor: pointer; a text field must not inherit that. */
   cursor: text;

package/css/page.css

@@ -28,7 +28,6 @@ body {
      this, rotating a phone to landscape zooms the text. iOS Safari implements
      ONLY the -webkit- prefixed form (the unprefixed property is ignored there),
      so both are required — unprefixed alone left iPhones inflating on rotate. */
-  /* stylelint-disable-next-line property-no-vendor-prefix -- iOS Safari only implements the prefixed form */
   -webkit-text-size-adjust: 100%;
   text-size-adjust: 100%;
   overscroll-behavior: none;
@@ -236,42 +235,40 @@ body {
    either ships its own @font-face or lets both tokens fall back to the platform
    monospace stack.
 
-   EVERY face overrides the font's vertical metrics to 0.995em over the baseline
-   and 0.250em under, and that is load-bearing for the terminal, not taste.
+   No face carries ascent-override or descent-override: the terminal's cell
+   background is the run padding in 02-terminal.css, never these metrics.
 
-   A cell's background is painted by an inline span, and an inline box paints its
-   FONT's content area, never the line box: at `font-size: 14px` with
-   `line-height: 17px` (02-terminal.css) a font whose ascent + descent is under
-   17px leaves an unpainted stripe between consecutive rows, so an application
-   drawing a solid column of background (kiro-cli's green and purple block
-   gutters) renders as dashes. GitHub's own Monaspace webfont declares
-   ascent 1890/2000 and descent 400/2000 with USE_TYPO_METRICS set, which is
-   0.945em + 0.200em = 16.03px at 14px, and Chromium rounds that to a 16px box
-   inside a 17px row: a 1px gap on every row boundary, measured in the sidecar.
+   The tiling overlay, "Web Terminal Glyphs", is the second family below, and it
+   is ONE file declared under FOUR descriptor sets. The released face is a single
+   upright 400 weight, so a lone rule would leave the engine free to synthesise a
+   stand-in for a bold or italic run. What the four sets (400/700 x normal/italic)
+   against the same URL foreclose is the EMBOLDENED stand-in, in Blink and in
+   Gecko both: a bold run resolves a real face where the same asset under one rule
+   is thickened. They do NOT foreclose the OBLIQUE one in Blink, which honours the
+   italic descriptor for face SELECTION and slants the run anyway; the only thing
+   keeping an italic box-drawing corner upright there is font-synthesis: none on
+   .term (02-terminal.css). Both mechanisms are load-bearing and neither is the
+   whole guarantee. All four rules point at one file, so the bytes download once.
 
-   0.995em + 0.250em is what the nerd-fonts-patched MonaspiceNe NFM OTFs carried
-   until 5.3.0 swapped them for these WOFF2 files (the swap was gated on
-   horizontal advances only, which is how the regression shipped). It rounds to
-   an 18px box, so a row's background overhangs its box by 1px and consecutive
-   rows meet with no seam — and the baseline does not move (13px from the row's
-   top edge, before and after), so no glyph shifts by restoring it. It is also
-   the metric pair the rest of this package is already tuned and documented
-   against: --label-ink-shift's sawtooth and ink-centre.ts both derive from
-   0.995em / 0.250em by name.
+   No overlay face declares unicode-range, and that absence is deliberate: the
+   font's own cmap IS its range (1,098 tiling codepoints, no letters, no digits,
+   no space), so a letter falls through to Monaspace by ordinary family fallback,
+   and a range here would only narrow that fallback to a list somebody has to
+   maintain against the next release of the font.
 
-   Do not "modernise" these away, and do not close the gap by lowering
-   `line-height` instead: that shrinks the cell, so it changes how many rows fit
-   a viewport and what the engine reports to the PTY. If a Monaspace bump ever
-   changes the outlines enough that a 0.995em ascent clips them, re-measure both
-   halves together — the terminal needs ascent + descent >= the cell height. */
+   The overlay is listed FIRST in --font-mono and never in --font-ui
+   (00-tokens.css owns why). A full-page host must serve
+   WebTerminalGlyphs.woff2 beside the Monaspace faces, along with that font's
+   LICENSE and NOTICE: it is a separate Apache-2.0 work, and §4 binds whoever
+   ships the bytes. This package ships none, it only names the URL — so a host
+   that has not caught up errors the face out and renders exactly as it did
+   before, with the tiling ranges coming from Monaspace and the system font. */
 @font-face {
   font-family: "Monaspace Neon NF";
   src: url("/vendor/fonts/MonaspaceNeonNF-Regular.woff2") format("woff2");
   font-weight: 400;
   font-style: normal;
   font-display: block;
-  ascent-override: 99.5%;
-  descent-override: 25%;
 }
 
 @font-face {
@@ -280,8 +277,6 @@ body {
   font-weight: 700;
   font-style: normal;
   font-display: block;
-  ascent-override: 99.5%;
-  descent-override: 25%;
 }
 
 @font-face {
@@ -290,8 +285,6 @@ body {
   font-weight: 400;
   font-style: italic;
   font-display: block;
-  ascent-override: 99.5%;
-  descent-override: 25%;
 }
 
 @font-face {
@@ -300,6 +293,36 @@ body {
   font-weight: 700;
   font-style: italic;
   font-display: block;
-  ascent-override: 99.5%;
-  descent-override: 25%;
+}
+
+@font-face {
+  font-family: "Web Terminal Glyphs";
+  src: url("/vendor/fonts/WebTerminalGlyphs.woff2") format("woff2");
+  font-weight: 400;
+  font-style: normal;
+  font-display: block;
+}
+
+@font-face {
+  font-family: "Web Terminal Glyphs";
+  src: url("/vendor/fonts/WebTerminalGlyphs.woff2") format("woff2");
+  font-weight: 700;
+  font-style: normal;
+  font-display: block;
+}
+
+@font-face {
+  font-family: "Web Terminal Glyphs";
+  src: url("/vendor/fonts/WebTerminalGlyphs.woff2") format("woff2");
+  font-weight: 400;
+  font-style: italic;
+  font-display: block;
+}
+
+@font-face {
+  font-family: "Web Terminal Glyphs";
+  src: url("/vendor/fonts/WebTerminalGlyphs.woff2") format("woff2");
+  font-weight: 700;
+  font-style: italic;
+  font-display: block;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/web-terminal-ui",
-  "version": "7.2.1",
+  "version": "7.3.0",
   "type": "module",
   "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.",
   "license": "MPL-2.0",
@@ -56,7 +56,7 @@
     "@vitest/browser-playwright": "5.0.0",
     "@vitest/coverage-v8": "5.0.0",
     "eslint": "10.10.0",
-    "fast-check": "4.9.0",
+    "fast-check": "4.10.0",
     "html-validate": "11.15.0",
     "knip": "6.35.1",
     "playwright": "1.63.0",

package/src/features/tabs/ink-centre.ts

@@ -1,41 +1,11 @@
-// Optical centring for the three chip labels (desktop strip, mobile switcher
-// chip, overview rows), measured in the engine instead of predicted from the
-// font's tables.
-//
-// Flex centring centres a label's LINE BOX. A font's metrics box reaches much
-// further above the baseline than below (the bundled Monaspace Neon NF: 0.995em
-// over, 0.250em under), so the visible text sits low inside the box it is
-// centred by, and the correction is the gap between the box's centre and the
-// text's own.
-//
-// WHICH BAND is the text's own is the load-bearing decision, and the first
-// version of this got it wrong. It centred cap-top-to-DESCENDER-bottom, which
-// reserves descender room below the letters and reads high: measured on the real
-// chip in Blink, the title's cap band sat 1.320px above the chip's centre while
-// the status dot and the close glyph beside it sat at exactly 0.000px, and a
-// title is judged against those two neighbours. So the band is cap-top to
-// BASELINE — the visible mass of a UI label, and the same pair of edges CSS
-// spells `text-box-edge: cap alphabetic`. Descenders overhang it deliberately;
-// the label's `padding-block` (30-tabs.css) is the allowance that keeps them
-// clear of `overflow: hidden`, so nothing is clipped by the choice.
-//
-// The correction is NOT a font-relative constant, which is what four earlier
-// fixes assumed. Engines round the font's ascent and descent to whole CSS pixels
-// before building the line box, so the ideal shift jumps whenever a size crosses
-// a rounding boundary: 0.25em x 13 = 3.25 rounds to 3 (a 16px box) while
-// 0.25em x 14 = 3.5 rounds to 4 (an 18px box), and the shift moves with it.
-// Engines disagree with each other too (Gecko makes that same 14px box 17px, not
-// 18px), and so do platforms within one engine: iOS resolves metrics through
-// CoreText, Linux WebKit through FreeType, which is why the strip read correct
-// in every local check and high on an iPad. Measured across 11-20px the cap-band
-// shift sawtooths between about -0.010em and +0.028em — small, but still wider
-// than the 0.33px error that was reported as a defect, so it stays measured.
-//
-// So nothing here predicts. Each measurement asks the engine for the line box
-// and baseline it actually produced, asks the font for its actual cap ink, and
-// writes the difference to --label-ink-shift as pixels. The CSS keeps an em
-// default for the pre-measurement paint (see 00-tokens.css); this only ever
-// narrows the error.
+// Optical centring for the three chip labels, measured in the engine rather than
+// predicted from the font's tables. Flex centring centres the LINE BOX, and a
+// font's box reaches further above the baseline than below it, so the text sits
+// low; the correction is the gap from the box's centre to the CAP band's (cap
+// top to baseline, the `text-box-edge: cap alphabetic` edges; a band including
+// descender ink reads high beside the dot and close glyph). Measured, not a
+// constant, because engines round ascent and descent to whole CSS pixels before
+// building the line box, and round differently per engine and platform.
 import { fromHTML } from "../dom.js";
 
 /** Ink extents are measured at this size and scaled back to em: WebKit and Blink

package/src/kernel/kernel.ts

@@ -54,7 +54,23 @@ import type {
 const { mapKeyboardEvent, bracketTextForPaste, prepareTextForTerminal } = keyboard;
 
 const DEFAULT_WS_PATH = "/ws";
+// The family that carries the CELL METRICS, alone: deliberately not --font-mono's
+// list, which leads with the tiling overlay. WebKit resolves load() over a list as
+// soon as the FIRST family whose descriptor covers the sample has loaded
+// (CSSFontFaceSet::matchingFacesExcludingPreinstalledFonts, `if (found) break;`),
+// so naming the overlay would settle the gate on its 11 KB while the companion is
+// still loading — and the overlay copies the companion's metrics and carries no
+// "M", the glyph render.ts measures, so waiting on it defends no number anyway.
 const DEFAULT_FONT_READY = '14px "Monaspace Neon NF"';
+// The deadline on the WHOLE gate below, because neither document.fonts.load nor
+// document.fonts.ready carries one: a response held open leaves both pending for
+// as long as that request lives, and a gate that never settles reports no size at
+// all. The budget is the block period the faces themselves buy with font-display:
+// block (css/page.css declares it on every one; 3s is what CSS Fonts 4 recommends
+// for `block`) — how long an engine withholds glyphs before it paints the
+// fallback. Once it has, the cell on screen IS the fallback cell, so a longer wait
+// defends metrics nobody is looking at.
+const FONT_READY_TIMEOUT_MS = 3000;
 
 const TOAST_MS = 3000;
 // A touch that focuses the input (opens the soft keyboard) must be a genuine
@@ -1383,13 +1399,49 @@ function buildTerminal(
     });
   };
   try {
-    void document.fonts
-      .load(fontReady)
-      .then(onFontSettled)
-      .catch((err: unknown) => {
+    // false once the fonts have landed, true when the deadline opened the gate
+    // without them. The race covers the whole wait, not just the rejection arm: a
+    // request that stalls with nothing rejecting leaves load() ITSELF pending, so a
+    // deadline armed on the rejection would bound one of the ways a font can hang.
+    const landed: Promise<boolean> = document.fonts.load(fontReady).then(
+      () => false,
+      (err: unknown) => {
         console.warn(`web-terminal-ui: web font ${fontReady} failed to load`, err);
-        onFontSettled();
+        // One load() over a comma-separated stack rejects as a UNIT, so settling
+        // here would let an unavailable OPTIONAL family abandon the gate for the
+        // REQUIRED one and announce a size measured on fallback metrics. `ready`
+        // settles the initial load INCLUDING a failed one (the same property
+        // features/tabs/ink-centre.ts relies on), so the families that ARE served
+        // still land their bytes before the first resize is measured.
+        return document.fonts.ready.then(() => false);
+      },
+    );
+    const deadline = new Promise<boolean>((resolve) => {
+      window.setTimeout(() => {
+        resolve(true);
+      }, FONT_READY_TIMEOUT_MS);
+    });
+    // Whichever settles first opens the gate exactly once; the loser is ignored.
+    void Promise.race([landed, deadline]).then((timedOut) => {
+      onFontSettled();
+      if (!timedOut) {
+        return;
+      }
+      // The gate opened on fallback metrics, and the swap period is infinite: bytes
+      // that land after this change the cell width with fontsLoaded already true,
+      // and nothing re-measures until the next viewport transition. So one
+      // corrective announce, through the path the viewport settle uses.
+      // sendResize deduplicates, so a font that never lands costs nothing.
+      void document.fonts.ready.then(() => {
+        // The bytes can arrive arbitrarily late, so this is the one arm of the gate
+        // that outlives its terminal; destroy() wins, as it does for a feature's
+        // un-cancelled async.
+        if (isDestroyed() || measurableSize() === null) {
+          return;
+        }
+        connection.sendResize();
       });
+    }, onFontSettled);
   } catch (err) {
     console.warn(`web-terminal-ui: invalid fontReady ${fontReady}`, err);
     onFontSettled();