@cplieger/web-terminal-ui 5.2.1 → 5.2.2

package/css/00-tokens.css

@@ -144,17 +144,26 @@
   --font-mono: "MonaspiceNe NFM", 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). Derived from MonaspiceNe NFM's own tables and outlines:
+     30-tabs.css).
 
-       (ascent - descent) / 2      = (0.995 - 0.250) / 2   = 0.3725em
-       (cap ink - descender ink)/2 = (0.7344 - 0.2188) / 2 = 0.2578em
-       difference                                          = 0.1147em
+     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.
 
-     A constant is safe here only because the bundled font leaves engines
-     nothing to disagree about: hhea, OS/2 typo and usWin all declare the same
-     0.995 / 0.250 with lineGap 0, and fsSelection sets USE_TYPO_METRICS, so
-     Chromium, Gecko and WebKit all compute the same line box. Re-derive this
-     number if the bundled font ever changes; do not nudge it by eye. */
+     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;
   --dur-micro: 0.1s;
   --dur-standard: 0.2s;

package/css/30-tabs.css

@@ -198,11 +198,11 @@
 
    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.7344em over (cap height) to 0.2188em
+   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 — 0.1147em, 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 — 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:
 
    - 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
@@ -222,21 +222,31 @@
      -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.
 
-   What this deliberately does NOT use is `text-box: trim-both`, which all three
-   previous attempts were built on. It ships in Blink and WebKit only (Firefox has
-   it in Nightly behind layout.css.text-box.enabled), 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.
-   Measured on the gated version: Chromium centred to 0.02px while Firefox sat
-   1.50px low with its baseline half a pixel BELOW the dot. The keyword vocabulary
-   is too coarse for this text besides -- `cap alphabetic` centres the cap band and
-   reads 1.14px low on lowercase, `ex alphabetic` centres the x-band and reads high
-   on capitals, and a mixed-case tab title wants neither edge.
-
-   The residual error is engines rounding ascent and descent to whole pixels, which
-   makes the ideal shift 0.127em at 13px and 0.099em at 14px; the one authored
-   0.1147em is the unrounded truth and lands within 0.22px at both sizes, in every
-   engine, with no fork. */
+   --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
+   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. */
 :where(.wt-root) .wt-tab-label {
   flex: 1 1 auto;
   min-width: 0;
@@ -247,9 +257,23 @@
   margin-block: 0 calc(2 * var(--label-ink-shift));
 }
 
-/* A little breathing room after the activity dot, before the label. */
+/* The dot sits between two gaps that must read as one gap: the chip's own
+   padding on its left, and the run to the label on its right. The chip's flex
+   `gap` is --sp-1 (it also spaces label -> close, which wants the tighter
+   value), so the dot makes up the difference itself and the two flanking gaps
+   both land on --sp-2. Expressed as the arithmetic rather than a literal 4px so
+   the equality survives a change to either token — a literal 2px was 6px against
+   the padding's 8px, which reads as the dot being crowded toward the title.
+
+   This equalises the LAYOUT gaps, deliberately not the ink gaps. A monospace
+   glyph is centred in a fixed advance, so a title's first letter starts about a
+   pixel inside its box, and how far in depends on the letter: compensating would
+   mean a correction that changes per title and per font, and the engines do not
+   even agree on the measurement (for this face WebKit reports no left bearing
+   where Blink reports 1.01px). A title-independent definition beats a
+   sub-pixel one that is wrong on the next title. */
 :where(.wt-root) .wt-tab-dot {
-  margin-right: 2px;
+  margin-right: calc(var(--sp-2) - var(--sp-1));
 }
 
 /* The tab close (x): a centered, muted square icon button with a box on hover.

package/css/31-switcher.css

@@ -174,10 +174,13 @@
 
 /* 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. See 30-tabs.css for the derivation, for
-   why line-height must stay `normal` here, and for why this is margin arithmetic
-   over the bundled font rather than a text-box trim behind an @supports gate that
-   only one engine ever takes. */
+   that lifts the ink 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
+   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 {
   flex: 1 1 auto;
   overflow: hidden;
@@ -446,10 +449,13 @@
 
 /* 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. See 30-tabs.css for the derivation, for
-   why line-height must stay `normal` here, and for why this is margin arithmetic
-   over the bundled font rather than a text-box trim behind an @supports gate that
-   only one engine ever takes. */
+   that lifts the ink 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
+   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 {
   flex: 1 1 auto;
   overflow: hidden;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/web-terminal-ui",
-  "version": "5.2.1",
+  "version": "5.2.2",
   "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",
@@ -57,7 +57,7 @@
     "fast-check": "4.9.0",
     "happy-dom": "20.11.1",
     "html-validate": "11.6.0",
-    "knip": "6.30.0",
+    "knip": "6.31.0",
     "prettier": "3.9.6",
     "stylelint": "17.14.1",
     "stylelint-config-standard": "40.0.0",

package/src/features/tabs/index.ts

@@ -14,6 +14,7 @@ import type { ActivityMonitorApi } from "../activity-monitor.js";
 import type { MobileToolbarApi } from "../mobile-toolbar.js";
 import { fromHTML, holdFocusOnPress } from "../dom.js";
 import { createClickSwallow, placeMenuAt } from "../menu-position.js";
+import { centreChipLabels } from "./ink-centre.js";
 import type { CueStatus, SessionInfo, StatusRecord, Tab } from "./model.js";
 import {
   ACTIVE_TAB_KEY,
@@ -600,6 +601,12 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
           offArmed = kbApi.onCtrlArmedChange(reflectArmed);
         }
       }
+      // Measured optical centring for every chip label in both layouts: writes
+      // --label-ink-shift onto the strip and the switcher from the line box THIS
+      // engine produced for THIS font at THIS size, rather than the em constant
+      // in 00-tokens.css that can only be right at one size (see ink-centre.ts).
+      const stopInkCentring = centreChipLabels(varRoot, { strip: bar, switcher });
+
       // Mark the root so the CSS lifts the bottom-anchored chrome (banner, toast,
       // scroll-to-bottom, key grid) above the switcher bar on a coarse pointer.
       const root = ctx.surface().parentElement;
@@ -3213,6 +3220,7 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
           }
           barResize.disconnect();
           swReserve.disconnect();
+          stopInkCentring();
           surface.classList.remove("wt-with-tabbar");
           varRoot.style.removeProperty("--wt-tabbar-h");
           root?.classList.remove("wt-tabbed");

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

@@ -0,0 +1,262 @@
+// 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 MonaspiceNe NFM: 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.
+//
+// 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
+// CoreText, Linux WebKit through FreeType, which is why the strip read correct
+// in every local check and high on an iPad.
+//
+// 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
+// default for the pre-measurement paint (see 00-tokens.css); this only ever
+// narrows the error.
+import { fromHTML } from "../dom.js";
+
+/** Ink extents are measured at this size and scaled back to em: WebKit and Blink
+ *  quantise canvas TextMetrics ink values to whole pixels, which at 13px leaves
+ *  4% of error in a number the correction halves. At 400px the same quantisation
+ *  is worth 0.00125em. */
+const REF_PX = 400;
+
+/** Marks the deepest element of a probe chain — the one whose resolved font is
+ *  the thing being measured. */
+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
+ *  and `.wt-tab-bar` is `display: none` on a narrow one, so a probe reproducing
+ *  the full chain would measure zeros in exactly one of the two layouts. */
+const STRIP_PROBE = `<div class="wt-tab"><span class="wt-tab-label ${PROBE_CLASS}">${PROBE_TEXT}</span></div>`;
+const SWITCHER_PROBE = `<div class="wt-switcher-current"><span class="wt-switcher-label ${PROBE_CLASS}">${PROBE_TEXT}</span></div>`;
+
+/** What an engine and a font report about one label's typography. */
+export interface InkMetrics {
+  /** The line box the engine produced for this font at this size. */
+  readonly fontBoxPx: number;
+  /** Baseline offset from the line box's over edge. */
+  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. */
+export function inkShiftPx(m: InkMetrics): number {
+  const inkCentre = m.baselinePx + ((m.descInkEm - m.capInkEm) * m.fontSizePx) / 2;
+  return inkCentre - m.fontBoxPx / 2;
+}
+
+let ctx2d: CanvasRenderingContext2D | null | undefined;
+
+function canvas2d(): CanvasRenderingContext2D | null {
+  ctx2d ??= document.createElement("canvas").getContext("2d");
+  return ctx2d;
+}
+
+/** The font's own ink extents, 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 {
+  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)) {
+    return null;
+  }
+  return { capInkEm: capInk / REF_PX, descInkEm: descInk / REF_PX };
+}
+
+/** The engine's line box and baseline for a laid-out element's own font. The
+ *  baseline is read off a zero-height inline-block, whose bottom margin edge
+ *  sits ON the baseline by definition — the only thing in the DOM that reports
+ *  a baseline position. */
+function lineBox(label: HTMLElement): Pick<InkMetrics, "fontBoxPx" | "baselinePx"> | null {
+  const line = document.createElement("span");
+  line.style.position = "absolute";
+  line.style.whiteSpace = "pre";
+  line.style.font = "inherit";
+  line.textContent = PROBE_TEXT;
+  const strut = document.createElement("span");
+  strut.style.display = "inline-block";
+  strut.style.width = "0";
+  strut.style.height = "0";
+  line.appendChild(strut);
+  label.appendChild(line);
+  const box = line.getBoundingClientRect();
+  const baselinePx = strut.getBoundingClientRect().bottom - box.top;
+  line.remove();
+  if (!(box.height > 0) || !Number.isFinite(baselinePx)) {
+    return null;
+  }
+  return { fontBoxPx: box.height, baselinePx };
+}
+
+/** Measures one site and returns its shift plus the font signature it belongs
+ *  to. Returns null when the resolved font is unchanged since `cached` (the
+ *  resize path, which then does no ink or line-box work at all) and when the
+ *  site cannot be measured at all (no layout, no canvas, a display: none
+ *  probe) — callers leave the CSS default in place either way rather than
+ *  writing a wrong number.
+ *
+ *  The probe lives only for the duration of this synchronous call, deliberately.
+ *  Keeping a permanent hidden one would save a DOM mutation per resize, and it
+ *  would also put a second `.wt-tab` inside the root forever — which the strip's
+ *  test suite counts as a tab (`root.querySelectorAll(".wt-tab")`). Transient
+ *  means no other code, and no assertion, can ever observe it. */
+function measureSite(
+  varRoot: HTMLElement,
+  probeHTML: string,
+  cached: string | undefined,
+): { shiftPx: number; signature: string } | null {
+  const wrap = document.createElement("div");
+  wrap.setAttribute("aria-hidden", "true");
+  wrap.style.position = "absolute";
+  wrap.style.top = "0";
+  wrap.style.left = "0";
+  wrap.style.visibility = "hidden";
+  wrap.style.pointerEvents = "none";
+  wrap.appendChild(fromHTML(probeHTML));
+  varRoot.appendChild(wrap);
+  try {
+    const label = wrap.querySelector<HTMLElement>(`.${PROBE_CLASS}`);
+    if (!label) {
+      return null;
+    }
+    const cs = getComputedStyle(label);
+    const signature = `${cs.fontStyle} ${cs.fontWeight} ${cs.fontSize} ${cs.fontFamily}`;
+    if (signature === cached) {
+      return null;
+    }
+    const fontSizePx = Number.parseFloat(cs.fontSize);
+    if (!(fontSizePx > 0)) {
+      return null;
+    }
+    const ink = inkExtents(`${cs.fontStyle} ${cs.fontWeight} ${REF_PX}px ${cs.fontFamily}`);
+    const box = lineBox(label);
+    if (!ink || !box) {
+      return null;
+    }
+    const shiftPx = inkShiftPx({ ...box, ...ink, fontSizePx });
+    if (!Number.isFinite(shiftPx)) {
+      return null;
+    }
+    return { shiftPx, signature };
+  } finally {
+    wrap.remove();
+  }
+}
+
+/** The element a measured shift is written to, and the probe that resolves its
+ *  font. --label-ink-shift is scoped per host rather than set once on the root
+ *  because the two label sizes need two different pixel values, and every label
+ *  inside a host shares one size. */
+interface Site {
+  readonly host: HTMLElement;
+  readonly probeHTML: string;
+}
+
+/**
+ * Writes a measured --label-ink-shift onto the tab strip and the mobile
+ * switcher, and keeps it current.
+ *
+ * Re-measures on two kinds of event, which need two different policies:
+ *
+ * - A font finishing (or failing) to load. The first pass can run inside
+ *   `font-display: block`, where the line box is still the fallback's, and the
+ *   real face can change every number here. These FORCE a re-measure, because
+ *   the signature below cannot see them: computed style reports the DECLARED
+ *   font-family list whether or not the webfont ever arrived, so a cached
+ *   signature would match and pin the fallback's shift permanently. (It did,
+ *   until scripts/verify-chip-geometry.mjs caught it.)
+ * - A resize. rem-relative label sizes move with Safari's per-site page zoom,
+ *   and a new size means new rounding; but most resizes change neither, so this
+ *   path keeps the signature check and costs one computed-style read per site
+ *   when nothing moved.
+ *
+ * @returns teardown that drops the listeners and the written properties.
+ */
+export function centreChipLabels(
+  varRoot: HTMLElement,
+  hosts: { readonly strip: HTMLElement; readonly switcher: HTMLElement },
+): () => void {
+  const sites: readonly Site[] = [
+    { host: hosts.strip, probeHTML: STRIP_PROBE },
+    { host: hosts.switcher, probeHTML: SWITCHER_PROBE },
+  ];
+  const measured = new WeakMap<HTMLElement, string>();
+  let disposed = false;
+
+  const remeasure = (force: boolean): void => {
+    if (disposed) {
+      return;
+    }
+    for (const site of sites) {
+      const result = measureSite(
+        varRoot,
+        site.probeHTML,
+        force ? undefined : measured.get(site.host),
+      );
+      if (!result) {
+        continue;
+      }
+      site.host.style.setProperty("--label-ink-shift", `${result.shiftPx.toFixed(3)}px`);
+      measured.set(site.host, result.signature);
+    }
+  };
+
+  const onResize = (): void => {
+    remeasure(false);
+  };
+  const onFontsDone = (): void => {
+    remeasure(true);
+  };
+
+  remeasure(false);
+  // The DOM lib types document.fonts as always present; happy-dom ships no
+  // FontFaceSet at all, and neither does any engine without the CSS Font
+  // Loading API, so the honest type is the optional one.
+  const fonts = document.fonts as FontFaceSet | undefined;
+  // `ready` settles the initial load (including a failed one); `loadingdone`
+  // covers a face the host page adds afterwards, which `ready` never reports.
+  void fonts?.ready.then(onFontsDone);
+  fonts?.addEventListener("loadingdone", onFontsDone);
+  window.addEventListener("resize", onResize);
+
+  return () => {
+    disposed = true;
+    fonts?.removeEventListener("loadingdone", onFontsDone);
+    window.removeEventListener("resize", onResize);
+    for (const site of sites) {
+      site.host.style.removeProperty("--label-ink-shift");
+    }
+  };
+}