@cplieger/web-terminal-ui 5.3.0 → 5.3.1

package/css/00-tokens.css

@@ -144,27 +144,33 @@
   --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).
+     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).
 
      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. Against the bundled font in
-     WebKit it is 0.1190em at 13px and 0.0915em at 14px, since 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). Engines then disagree with each other (Firefox makes that 14px box
-     17px) and platforms disagree within one engine (iOS reads metrics through
-     CoreText, Linux WebKit through FreeType). Four fixes were hardcoded
-     constants and each was correct only where it was tuned.
+     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.
 
-     0.1147em is kept as the default because it is the midpoint of that
-     sawtooth: worst case 0.34px before the measurement lands, versus 1.5px for
-     no correction at all. 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. */
-  --label-ink-shift: 0.1147em;
+     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. */
+  --label-ink-shift: 0em;
   --dur-micro: 0.1s;
   --dur-standard: 0.2s;
   --dur-enter: 0.25s;

package/css/02-terminal.css

@@ -45,6 +45,12 @@
   touch-action: pan-x pan-y;
   font-family: var(--font-mono);
   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. */
   line-height: 17px;
   padding: 4px;
   background: var(--bg);

package/css/30-tabs.css

@@ -215,9 +215,16 @@
    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 — about 1.5px at this size — 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:
+   --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
@@ -227,6 +234,9 @@
    - 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
@@ -240,16 +250,19 @@
    --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. 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: in WebKit 0.1190em at 13px against 0.0915em at 14px,
-   because 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). 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), Firefox makes that 14px box 17px rather than 18px, 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
+   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.
 

package/css/31-switcher.css

@@ -196,11 +196,12 @@
 
 /* Ink-centring geometry, identical to .wt-tab-label: a symmetric ink allowance
    the ellipsis clipping needs, plus a bottom margin of twice --label-ink-shift
-   that lifts the ink to the row centre. These labels are 14px against the strip's
+   that lifts the CAP band (cap top to baseline, never cap-to-descender) to the row
+   centre. These labels are 14px against the strip's
    13px, which is exactly why --label-ink-shift is MEASURED per site at runtime
    (src/features/tabs/ink-centre.ts) rather than declared once: the shift an engine
-   needs is a sawtooth in font size, not a ratio, so the single em constant that
-   served both sizes was correct at 13px and 0.33px high here. See 30-tabs.css for
+   needs is a sawtooth in font size, not a ratio — it does not even keep one sign
+   across the two sizes. See 30-tabs.css for
    the full derivation, for why line-height must stay `normal`, and for why a
    measured shift beats a text-box trim behind an @supports gate. */
 :where(.wt-root) .wt-switcher-label {
@@ -471,11 +472,12 @@
 
 /* Ink-centring geometry, identical to .wt-tab-label: a symmetric ink allowance
    the ellipsis clipping needs, plus a bottom margin of twice --label-ink-shift
-   that lifts the ink to the row centre. These labels are 14px against the strip's
+   that lifts the CAP band (cap top to baseline, never cap-to-descender) to the row
+   centre. These labels are 14px against the strip's
    13px, which is exactly why --label-ink-shift is MEASURED per site at runtime
    (src/features/tabs/ink-centre.ts) rather than declared once: the shift an engine
-   needs is a sawtooth in font size, not a ratio, so the single em constant that
-   served both sizes was correct at 13px and 0.33px high here. See 30-tabs.css for
+   needs is a sawtooth in font size, not a ratio — it does not even keep one sign
+   across the two sizes. See 30-tabs.css for
    the full derivation, for why line-height must stay `normal`, and for why a
    measured shift beats a text-box trim behind an @supports gate. */
 :where(.wt-root) .wt-switcher-row-label {

package/css/page.css

@@ -215,13 +215,44 @@ body {
    different typeface per engine (see --label-ink-shift in 00-tokens.css). An
    embedder does not serve these files and never inherits these URLs, so it
    either ships its own @font-face or lets both tokens fall back to the platform
-   monospace stack. */
+   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.
+
+   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.
+
+   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.
+
+   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. */
 @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 {
@@ -230,6 +261,8 @@ body {
   font-weight: 700;
   font-style: normal;
   font-display: block;
+  ascent-override: 99.5%;
+  descent-override: 25%;
 }
 
 @font-face {
@@ -238,6 +271,8 @@ body {
   font-weight: 400;
   font-style: italic;
   font-display: block;
+  ascent-override: 99.5%;
+  descent-override: 25%;
 }
 
 @font-face {
@@ -246,4 +281,6 @@ body {
   font-weight: 700;
   font-style: italic;
   font-display: block;
+  ascent-override: 99.5%;
+  descent-override: 25%;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/web-terminal-ui",
-  "version": "5.3.0",
+  "version": "5.3.1",
   "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": "GPL-3.0-or-later",

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

@@ -4,27 +4,36 @@
 //
 // 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) while a mixed-case title's ink runs cap height to
-// descender (0.734em over, 0.203em under), so the visible text sits low inside
-// the box it is centred by. The correction is the gap between those two centres.
+// 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.
 //
-// That gap is NOT a font-relative constant, which is what four previous 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: measured in WebKit against this font it is
-// 0.1190em at 13px but 0.0915em at 14px, because 0.25em x 13 = 3.25 rounds to 3
-// (16px box) while 0.25em x 14 = 3.5 rounds to 4 (18px box). Sweeping 11-20px
-// gives a sawtooth between 0.092em and 0.119em, so one em value is right only at
-// the sizes whose rounding it was tuned against — the shipped 0.1147em was
-// correct on the 13px desktop strip and 0.33px high on the 14px mobile chip.
-// Engines disagree with each other too (Firefox makes that same 14px box 17px,
-// not 18px), and so do platforms within one engine: iOS resolves metrics through
+// 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.
+// 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 ink extents,
-// and writes the difference to --label-ink-shift as pixels. The CSS keeps an em
+// 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.
 import { fromHTML } from "../dom.js";
@@ -42,7 +51,6 @@ const PROBE_CLASS = "wt-ink-probe";
 /** Cap ink, x-height ink and descender ink in one string, so the DOM probe's
  *  line box is the one a real mixed-case title produces. */
 const PROBE_TEXT = "Hxp";
-
 /** Class chains that resolve each site's label font. Deliberately the shortest
  *  chain that carries the font-size (`.wt-tab` and `.wt-switcher-current`) and
  *  not the real ancestry: `.wt-switcher` is `display: none` off a coarse pointer
@@ -59,16 +67,17 @@ export interface InkMetrics {
   readonly baselinePx: number;
   /** Cap ink above the baseline, em. */
   readonly capInkEm: number;
-  /** Descender ink below the baseline, em. */
-  readonly descInkEm: number;
   readonly fontSizePx: number;
 }
 
-/** How far a label's visible ink sits BELOW its line box's centre. Positive is
- *  the normal case (ink low), and the CSS lifts the box by exactly this much. */
+/** How far a label's visible ink sits BELOW its line box's centre, where
+ *  "visible ink" is the cap band (cap top to baseline). Positive is the normal
+ *  case (ink low), and the CSS lifts the box by exactly this much.
+ *
+ *  Descender ink is deliberately NOT part of the band; see the header. */
 export function inkShiftPx(m: InkMetrics): number {
-  const inkCentre = m.baselinePx + ((m.descInkEm - m.capInkEm) * m.fontSizePx) / 2;
-  return inkCentre - m.fontBoxPx / 2;
+  const capCentre = m.baselinePx - (m.capInkEm * m.fontSizePx) / 2;
+  return capCentre - m.fontBoxPx / 2;
 }
 
 let ctx2d: CanvasRenderingContext2D | null | undefined;
@@ -78,21 +87,20 @@ function canvas2d(): CanvasRenderingContext2D | null {
   return ctx2d;
 }
 
-/** The font's own ink extents, in em. Canvas rather than the DOM because only
+/** The font's own cap ink, in em. Canvas rather than the DOM because only
  *  TextMetrics reports where the glyphs' ink actually starts and stops; a DOM
  *  rect only ever reports the box around it. */
-function inkExtents(font: string): Pick<InkMetrics, "capInkEm" | "descInkEm"> | null {
+function inkExtents(font: string): Pick<InkMetrics, "capInkEm"> | null {
   const ctx = canvas2d();
   if (!ctx) {
     return null;
   }
   ctx.font = font;
   const capInk = ctx.measureText("H").actualBoundingBoxAscent;
-  const descInk = ctx.measureText("p").actualBoundingBoxDescent;
-  if (!(capInk > 0) || !(descInk > 0)) {
+  if (!(capInk > 0)) {
     return null;
   }
-  return { capInkEm: capInk / REF_PX, descInkEm: descInk / REF_PX };
+  return { capInkEm: capInk / REF_PX };
 }
 
 /** The engine's line box and baseline for a laid-out element's own font. The