@tn3270/gui 0.0.0-stage → 0.1.0

package/app/ui.css

@@ -0,0 +1,843 @@
+/*
+  Shared chrome for every HTML surface in this project: the GUI's transfer window, the GUI's
+  keypad window, and the web gateway's keypad overlay.
+
+  ## ONE FILE, THREE DOCUMENTS, AND THAT IS A REQUIREMENT RATHER THAN TIDINESS
+
+  The user's call, 2026-10-06: the keypad and the transfer window must be stylistically similar.
+  `transfer.html` inlined these rules, so a second HTML surface meant a second copy and a third
+  meant a third -- and three copies of one `font:` declaration diverge the first time anybody
+  touches one of them.
+
+  ## "NATIVE, NOT X-ISH", CONCRETELY
+
+  The user asked for something that "looks like a native app, not an X-windows app", with a
+  pleasant font. That means, specifically:
+
+   - `system-ui`, so each platform supplies its own face rather than us shipping one;
+   - `color-scheme: light dark`, so the OS theme is honored instead of a hardcoded palette;
+   - system color KEYWORDS (`GrayText`, `Canvas`, `CanvasText`) rather than hex values, so
+     high-contrast and dark modes keep working without a second stylesheet.
+
+  NOTHING HERE USES THE 3270 ATLAS. That is the entire point of moving the keypad off the canvas:
+  the old one drew its buttons as 3270 glyphs through x3270's `3270.bdf`, which is why the user
+  called it ugly.
+
+  ## THE 3270 SCREEN ITSELF IS NOT STYLED BY THIS FILE
+
+  The canvas is pixels blitted from an atlas and must stay that way, so `gui/index.html` and
+  `web/static/index.html` keep their own two-line style blocks. Those two also encode a
+  LOAD-BEARING difference from each other -- `overflow:hidden` against `overflow:auto`, measured
+  against a 43-row model 4 -- and merging them into here would lose it.
+
+  A SECOND REASON NOT TO TOUCH THOSE PAGES: `gui/src/main.ts:1234` records that the click path's
+  `offsetX` arithmetic depends on the canvas sitting at the viewport origin -- "give the page a
+  body margin and every click here misses by it". The `body { padding }` below applies to the two
+  HTML surfaces, never to a canvas page.
+*/
+
+:root { color-scheme: light dark; }
+
+/*
+  SCOPED TO `.ui-surface`, NOT APPLIED TO `body`, AND THAT WAS MEASURED RATHER THAN FORESEEN.
+
+  The first version styled `body` directly, which was fine while only the transfer and keypad
+  WINDOWS loaded this file -- in those, the HTML form IS the document. The web gateway loads it
+  into the page that also holds the 3270 CANVAS, and `body { padding: 12px 14px }` displaced that
+  canvas: `browser-shot.mjs` reported both goldens differing, and the measurement was content
+  moving from x=1 to x=16, a 15px shift of the whole screen.
+
+  That is worse than a cosmetic regression. `gui/src/main.ts` records that the click path's
+  `offsetX` arithmetic assumes the canvas sits at the viewport origin -- "give the page a body
+  margin and every click here misses by it" -- so padding on `body` would have put every keypad
+  and selection click 15px off target in the browser, silently, with the goldens as the only
+  witness. The warning was already written down in this file's own header; scoping is what makes
+  it structural instead of advisory.
+
+  So every HTML surface carries `class="ui-surface"` on its `body`, and the canvas pages simply do
+  not. The keypad OVERLAY is styled through `#keypad-overlay` below, which is its own element and
+  never the page.
+*/
+body.ui-surface {
+  font: 13px system-ui, sans-serif;
+  margin: 0;
+  padding: 12px 14px;
+}
+
+.ui-surface h1 { font-size: 13px; font-weight: 600; margin: 0 0 10px; }
+
+/* The overlay is a surface too, but it is an element inside a canvas page rather than a body. */
+#keypad-overlay h1 { font-size: 13px; font-weight: 600; margin: 0 0 10px; }
+
+/* ---- The transfer form ---- */
+
+.row {
+  display: grid;
+  grid-template-columns: 90px 1fr auto;
+  gap: 6px 8px;
+  align-items: center;
+  margin-bottom: 6px;
+}
+
+.ui-surface label { text-align: right; color: GrayText; }
+.ui-surface input, .ui-surface select { font: inherit; padding: 2px 4px; min-width: 0; }
+.ui-surface input[disabled], .ui-surface select[disabled] { opacity: 0.5; }
+
+/*
+  NO `#status.error` RULE, deliberately -- moved here from `transfer.html` with its reasoning
+  intact, because the reasoning is what stops it being re-added. `UiDeps.setStatus` takes a BARE
+  STRING: a help line, a progress report and a validator complaint are indistinguishable by the
+  time they reach the DOM, so nothing in `transferBoot.ts` could ever add that class and the rule
+  would be dead CSS promising a color it never paints. Styling an error needs the distinction
+  carried across the boundary -- a second argument on `setStatus`, or a separate `setError` --
+  which is a change to `transferUi.ts`'s interface and its tests, not to markup.
+*/
+#status { margin: 10px 0 12px; min-height: 2.4em; white-space: pre-wrap; color: GrayText; }
+
+/*
+  THE CONNECT DIALOG'S ERROR LINE, and unlike `#status` above it IS only ever an error: the boot
+  file writes nothing else to it, so a colour here cannot lie. WRAPPED, never clipped -- a usage
+  line is long, and the remedy in a TLS message must not be cut off. `min-height` reserves two lines
+  so the buttons do not jump when an error appears; a longer message grows the box and scrolls.
+*/
+#connect-error {
+  /* Whole lines, so the box never cuts one in half: two reserved, five before it scrolls. */
+  line-height: 1.3; min-height: calc(2 * 1.3em); max-height: calc(5 * 1.3em);
+  margin: 8px 0 10px; overflow-y: auto;
+  white-space: pre-wrap; overflow-wrap: anywhere; color: #c62828;
+}
+/* A checkbox in the row's wide middle column would otherwise sit centred, away from its label. */
+#connect-form input[type="checkbox"] { justify-self: start; margin-left: 0; }
+@media (prefers-color-scheme: dark) { #connect-error { color: #ff6e6e; } }
+
+#buttons { display: flex; gap: 8px; justify-content: flex-end; }
+.ui-surface button, #keypad-overlay button, #transfer-overlay button {
+  font: inherit;
+  padding: 3px 12px;
+}
+
+/*
+  THE FOCUS RING, AND IT IS AN ACCESSIBILITY FIX RATHER THAN A FLOURISH.
+
+  Before this rule there was NO `:focus` and NO `outline` anywhere in this file, so every button in
+  the keypad and in both transfer surfaces relied on the browser's default ring -- which differs
+  between Firefox and Chromium and can read poorly against the `Canvas` background these overlays
+  set deliberately. The transfer form is built to be keyboard-navigable (`transferBoot.ts`'s focus
+  memo, `transferUi.ts`'s `caretAfterEdit`, and the tab order `TRANSFER_FIELDS` fixes), so having no
+  visible focus indicator was a real defect and not a cosmetic one.
+
+  `:focus-visible` AND NOT `:focus`. The latter leaves a ring behind after a mouse click, which is
+  the reason the pseudo-class was split in the first place. That is the right rule for every button
+  an operator TABS to.
+
+  **BUT IT IS NOT ENOUGH FOR A PROGRAMMATIC FOCUS, which this comment originally claimed it was.**
+  MEASURED the same day: `:focus-visible` is decided by the UA's heuristic about the user's LAST
+  INPUT MODALITY, not by how the focus was set -- so the Save button that `transferBoot.ts` focuses
+  on a completed receive did NOT match it, because the operator got there by CLICKING Start. See
+  the `#transfer-save` rule below, which is why it exists.
+
+  THIS REACHES THE ELECTRON GUI TOO, deliberately. This file lives in `packages/gui` and is served
+  to the browser as a third asset root (`web/src/httpstatic.ts` sets out why at length); the GUI's
+  keypad and transfer windows had no focus indicator either, and the user requirement that the two
+  look alike is what made the stylesheet shared at all.
+
+  SYSTEM COLOUR, like `GrayText` on the status lines and `Canvas` on the surfaces, so the ring
+  follows the operator's own theme rather than hard-coding a colour that might vanish into it.
+  `outline-offset` keeps it clear of the glyphs on the keypad's 3.4em buttons.
+*/
+.ui-surface button:focus-visible,
+#keypad-overlay button:focus-visible,
+#transfer-overlay button:focus-visible {
+  outline: 2px solid Highlight;
+  outline-offset: 2px;
+}
+
+/*
+  AND `#transfer-save` NEEDS PLAIN `:focus` AS WELL -- MEASURED, NOT ASSUMED.
+
+  `transferBoot.ts` focuses this button when a receive completes, and the rule above DID NOT PAINT:
+  `browser-clicks.mjs` reported `:focus-visible matched: false` with the focus correctly on
+  `#transfer-save`. `:focus-visible` is decided by the UA's heuristic about the user's LAST INPUT
+  MODALITY, not by how the focus was set -- and the operator reaches a completed transfer by
+  CLICKING Start, so the modality is pointer and the ring is suppressed. Confirmed against MDN
+  2026-10-22. The autofocus would have landed invisibly, which is the whole defect it exists to fix.
+
+  SO THIS ONE BUTTON OPTS INTO `:focus` TOO, and the usual objection does not apply to it. `:focus`
+  is avoided generally because it leaves a ring on a button the operator merely clicked -- but
+  clicking THIS button saves the file and `transferBoot.ts` then DISABLES it (`hasUnsaved()` goes
+  false), so the lingering-ring case cannot arise: there is no state where Save is both clicked and
+  still focusable. The narrow selector is deliberate; widening it to every button would
+  reintroduce exactly what `:focus-visible` is for.
+*/
+#transfer-overlay #transfer-save:focus {
+  outline: 2px solid Highlight;
+  outline-offset: 2px;
+}
+
+/* ---- The keypad ---- */
+
+/*
+  One block per semantic group from `KEYPAD_BLOCKS`, each a wrapping flex row of buttons.
+
+  NO FIXED PIXEL GRID AND NO PER-KEY POSITIONING, which is the substantive difference from the
+  canvas keypad: that one computed a left edge in CHARACTER CELLS for every key (`KeypadKey.col`,
+  six cells per key, sized to fit inside 80 columns). Here the browser lays the buttons out, so a
+  longer label grows its own button instead of overflowing into the next one -- the 5-character
+  limit on `KeypadKey.label` exists for the canvas, and is why labels read `FldMk` and `BkSp`.
+  Those abbreviations stay for now: they are shared with the TUI overlay, and widening them is a
+  separate change to a table two front ends read.
+*/
+.keypad-block { margin: 0 0 10px; }
+
+.keypad-block > h2 {
+  font-size: 11px;
+  font-weight: 600;
+  color: GrayText;
+  margin: 0 0 4px;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+}
+
+.keypad-keys { display: flex; flex-wrap: wrap; gap: 4px; }
+.keypad-keys > button { min-width: 3.4em; padding: 3px 6px; }
+
+/*
+  THE WEB OVERLAY, which the GUI does not use: in a window the keypad IS the document, but a
+  browser tab has only the one pane, so the web gets an overlay over its canvas.
+
+  OPAQUE, NOT TRANSLUCENT -- the user's call, and there is a measured reason to respect it. The
+  TUI's overlay once had host text leak through into its chord column, and opacity was the
+  hard-won fix. An overlay that lets the screen show through is a legibility bug waiting to be
+  re-found, so `background: Canvas` is a rule rather than a default.
+
+  `position: fixed` AND NOT A SIBLING IN FLOW, for the reason the header gives: the canvas must
+  stay at the viewport origin or every keypad click in the OTHER front end misses by the offset.
+  Fixed positioning paints over it without displacing it.
+
+  `overflow: auto` because the keypad is taller than some viewports and a browser page cannot
+  resize its own window -- the same argument that made `web/static/index.html` scroll where the
+  Electron page does not.
+*/
+#keypad-overlay {
+  position: fixed;
+  inset: 0;
+  overflow: auto;
+  background: Canvas;
+  color: CanvasText;
+  padding: 12px 14px;
+}
+
+#keypad-overlay[hidden] { display: none; }
+#keypad-overlay > .keypad-close { position: absolute; top: 8px; right: 10px; }
+
+/*
+  THE WEB TRANSFER OVERLAY, 2026-10-07, which the GUI does not use either: in Electron the transfer
+  form IS a window (`transfer.html`, styled through `body.ui-surface` above), and a browser tab has
+  only the one pane.
+
+  THE TWO RULES ARE THE KEYPAD'S, and both are load-bearing -- but `position: fixed` earns its
+  keep HERE for a different measured reason than the one the keypad's comment gives, and the
+  difference is worth writing down because the obvious claim is FALSE for this element:
+
+   - `position: fixed`, so the form appears IN THE VIEWPORT. It does NOT exist to stop the canvas
+     being displaced: this overlay follows `<canvas id="screen">` in document order, so a static
+     one lands BELOW it and cannot push it anywhere. MEASURED 2026-10-07 under real Chromium with
+     `position: static`, the form shown: the canvas rect was byte-identical (`x:0 y:0` either
+     way), `browser-shot.mjs` still scored 1/1, and what actually broke was the FORM -- its top
+     edge sat at y=773 in a 773px viewport, i.e. entirely below the fold, `body.scrollHeight`
+     grew from 773 to 1105, and `elementFromPoint` over the Start button returned `null` instead
+     of `transfer-start`. So the honest statement is that a static overlay is an INVISIBLE,
+     UNCLICKABLE form the operator must scroll to find, not a displaced canvas.
+     The displacement hazard is real and is the keypad's: `gui/src/main.ts` records what it costs
+     -- "give the page a body margin and every click here misses by it" -- and
+     `browser-clicks.mjs` measured 15px of it once, from this file styling `body`. That is why
+     the shared rules above are scoped to `.ui-surface`. Fixed positioning keeps this element
+     structurally incapable of contributing to it, which is worth having; it is just not what a
+     mutation of this line would demonstrate.
+   - `background: Canvas`, opaque rather than translucent. The TUI's overlay once let host text
+     leak through into its chord column and opacity was the hard-won fix; here the surface
+     contains EDITABLE FIELDS over a logged-on session, which is strictly worse to read through.
+
+  `inset: 0` IS DELIBERATELY NOT COPIED FROM THE KEYPAD. That one fills the viewport because 48
+  buttons need the room; this form is ten rows, and covering the whole screen would hide the host
+  output the operator is naming files from. So it is a panel in the top-left with a `max-height`
+  and its own scrollbar, for the same reason the keypad has one: a browser page cannot resize its
+  own window.
+
+  VISIBILITY IS DRIVEN BY THE `hidden` ATTRIBUTE, matching `#keypad-overlay` above and
+  `transferOverlay.ts`, which sets `element.hidden` and never `style.display` -- an inline style
+  would beat this rule by specificity and silently diverge the two overlays' mechanisms.
+*/
+#transfer-overlay {
+  position: fixed;
+  top: 0;
+  left: 0;
+  max-height: 100%;
+  overflow: auto;
+  background: Canvas;
+  color: CanvasText;
+  padding: 12px 14px;
+  border: 1px solid GrayText;
+}
+
+#transfer-overlay[hidden] { display: none; }
+
+#transfer-overlay h1 { font-size: 13px; font-weight: 600; margin: 0 0 10px; }
+
+/*
+  TWO COLUMNS, LABEL AND CONTROL, matching the transfer WINDOW's `.row` grid in spirit without
+  reusing it: that one is a three-column grid per row because the window draws a Browse button
+  beside the `Local file` input. Here Browse lives in the static button row below the fields, so
+  the rows need no third column -- and one grid over all the rows keeps the labels aligned without
+  a fixed pixel width.
+*/
+#transfer-fields {
+  display: grid;
+  grid-template-columns: auto 1fr;
+  gap: 6px 8px;
+  align-items: center;
+}
+
+#transfer-overlay label { text-align: right; color: GrayText; }
+#transfer-overlay input, #transfer-overlay select { font: inherit; padding: 2px 4px; min-width: 0; }
+#transfer-overlay input[disabled], #transfer-overlay select[disabled] { opacity: 0.5; }
+#transfer-overlay button[disabled] { opacity: 0.5; }
+
+/* Mirrors `#status` above, including the `min-height` that stops the panel resizing per message. */
+#transfer-status { margin: 10px 0 12px; min-height: 2.4em; white-space: pre-wrap; color: GrayText; }
+
+#transfer-buttons { display: flex; gap: 8px; }
+
+/*
+  THE WEB MODEL/OVERSIZE PICKER, Alt-M, 2026-11-04 -- the GUI's Model menu as an overlay, since a
+  browser tab has no menu bar. The transfer overlay's rules, for that overlay's measured reasons:
+  `position: fixed` so it is in the viewport whatever the page has scrolled to; `background:
+  Canvas`, OPAQUE, so the 3270 screen does not show through the labels; a top-left panel with its
+  own scrollbar rather than `inset: 0`, because eleven radios do not need the whole screen; and
+  visibility through the `hidden` attribute, never `style.display`, which would beat this rule by
+  specificity. The Electron GUI does not use it: there the picker IS the Model menu.
+*/
+#geometry-overlay {
+  position: fixed;
+  top: 0;
+  left: 0;
+  max-height: 100%;
+  overflow: auto;
+  background: Canvas;
+  color: CanvasText;
+  padding: 12px 14px;
+  border: 1px solid GrayText;
+  font: 13px system-ui, sans-serif;
+}
+
+#geometry-overlay[hidden] { display: none; }
+#geometry-overlay h1 { font-size: 13px; font-weight: 600; margin: 0 4.5em 4px 0; }
+#geometry-overlay > .geometry-close { position: absolute; top: 8px; right: 10px; }
+#geometry-overlay button { font: inherit; padding: 3px 12px; }
+#geometry-overlay button:focus-visible { outline: 2px solid Highlight; outline-offset: 2px; }
+#geometry-overlay .geometry-help { margin: 0 0 8px; color: GrayText; }
+/* A GRID, not the flex row it was: the Disconnect button (2026-11-05) is the root's first child and
+   takes a whole row of its own, at its own width, above the two groups side by side. */
+#geometry-choices { display: grid; grid-template-columns: auto auto; justify-content: start; gap: 12px; align-items: start; }
+#geometry-choices > .geometry-disconnect { grid-column: 1 / -1; justify-self: start; }
+#geometry-choices fieldset { border: 1px solid GrayText; margin: 0; padding: 4px 10px 6px; }
+#geometry-choices legend { color: GrayText; }
+#geometry-choices label { display: block; white-space: nowrap; padding: 1px 0; }
+#geometry-choices input[disabled] + span { opacity: 0.5; }
+/* Mirrors `#transfer-status`, including the `min-height` that stops the panel resizing per message. */
+#geometry-status { margin: 8px 0 0; min-height: 2.4em; max-width: 40em; white-space: pre-wrap; color: GrayText; }
+
+/* ---- The full 122-key keyboard ---- */
+
+/*
+  ============================================================================================
+  THE FULL KEYBOARD, IN TWO HALVES: `.keyboard-surface` IS THE KEYBOARD, `#keyboard-overlay` IS
+  ONE PLACE TO PUT IT
+  ============================================================================================
+
+  ## WHY THIS IS SPLIT AT ALL, 2026-10-23
+
+  Every one of these rules was scoped to `#keyboard-overlay` when the WEB gateway was the only
+  front end with a keyboard. The Electron window (`keyboard.html`) is a DOCUMENT, not an overlay
+  over a canvas, so under the old scoping it matched NONE of them -- and the failure is not a
+  blank window but something worse to diagnose: `.ui-surface button { padding: 3px 12px }` on line
+  98 still applies, so the caps render as ordinary buttons at the wrong size, in rows, looking
+  like a keyboard that has merely been styled badly. `uiAssets.test.ts` records the same shape for
+  a missing stylesheet: the whole thing works and looks like 1993.
+
+  ## THE SPLIT FOLLOWS THE KEYPAD'S OWN PRECEDENT
+
+  `.keypad-keys` (line 185) is the keypad's shared layout and `#keypad-overlay` (line 205) is its
+  web-only framing -- the same division, already in this file, for the same reason. So:
+
+   - `.keyboard-surface` CARRIES THE KEYBOARD: the pitch, the font, the regions, the rows, the cap
+     geometry. Both front ends put this class on whatever element holds the keyboard.
+   - `#keyboard-overlay` CARRIES THE OVERLAY: fixed positioning, the dock, the opaque background,
+     the scroll, and the `hidden` rule. The Electron window needs none of these -- a window IS
+     positioned and opaque by being a window.
+
+  THE PITCH AND FONT ARE ON THE CLASS, NOT THE ID, and that is the half most easily got wrong:
+  they look like framing and they are not. `--kb-pitch` is what every cap's width calc multiplies,
+  so on the id it would be absent in the window and every cap would compute from an undefined
+  variable.
+*/
+.keyboard-surface {
+  /*
+    ONE PITCH VARIABLE, which is the whole reason `KEYBOARD_3279` holds KEY UNITS rather than
+    pixels: the table says a cap is 1 or 1.5 or 7 units wide, and this decides what a unit is. To
+    make the keyboard bigger or smaller, change this number and nothing else.
+  */
+  /*
+    THE PITCH AND THE FONT TOGETHER, AND THE FONT IS THE ONE THAT WAS WRONG.
+
+    MEASURED 2026-10-22 from the user's screenshots: `PF13` rendered as `PF1`, `PF24` as `PF2` and
+    `Attn` as `Attr` -- every four-character label silently clipped by the `overflow: hidden`
+    below, which made the whole PF strip useless since PF13-24 became indistinguishable from
+    PF1-12.
+
+    THE ARITHMETIC, so the next change is not another guess: a cap is `--kb-pitch` wide less 4px of
+    padding. At 11px, four characters of system-ui need about 24px, against 26px usable -- it
+    "fits" by 2px in theory and clips in practice, because the font metric is an average and
+    capitals are wider. At 9px the same label needs about 20px, which leaves real room.
+
+    The user's requirement, which is the right test to keep: **the common three-letter names
+    (`PA1`, `PF3`, `Esc`) must fit**, and the four-character ones (`PF13`, `Attn`, `Dup`) are the
+    cases that actually bite.
+
+    THE SHIPPED PAIR IS 28px AND 8px, ARRIVED AT BY MEASUREMENT RATHER THAN TASTE. A cap is
+    28 - 4 = 24px usable, and at 8px a character of system-ui averages ~4.5px, so FIVE characters
+    fit per line -- which is what `Clear`, `Pause`, `Enter`, `Space` and `Field` need. Six would
+    require either a 6px font (unreadable) or a 34px pitch (a 816px-wide surface), so the
+    six-character legends are STACKED instead, which is what the hardware does anyway.
+
+    The lower band is 24 key units, so 28px gives ~672px -- inside a 24x80 screen's ~720px with
+    room for the gaps between regions, where the original 30px gave exactly 720px and left none.
+
+    `keyboard3279.test.ts` copies these two numbers and fails if a legend cannot fit. CHANGE IT
+    WHEN YOU CHANGE THESE.
+  */
+  --kb-pitch: 28px;
+  /*
+    THE FAMILY, AND ITS ABSENCE IS WHY THE KEYBOARD WENT SERIF.
+
+    `font: 13px system-ui, sans-serif` is set on `body.ui-surface` -- which is the ELECTRON pages'
+    body. The web gateway's page is a bare `<body>` holding a canvas, so this overlay inherited
+    from it, and a bare body's default family is SERIF. The `font: inherit` added to the caps in
+    the previous commit then faithfully inherited the wrong thing: it fixed the SIZE (they had been
+    stuck at the UA's 13.33px) and exposed the family at the same time.
+
+    SET HERE RATHER THAN ON THE CAPS, so one declaration covers the overlay, and `system-ui` to
+    match the rest of this stylesheet -- each platform supplies its own face rather than us
+    shipping one, which is the reasoning this file's header already gives.
+  */
+  /*
+    AN EXPLICIT FALLBACK CHAIN FOR THE ARROW GLYPHS, 2026-10-22.
+
+    The cursor cluster and several other caps draw a dozen glyphs from Unicode's Arrows block
+    (U+2190..U+21FF): two-headed arrows, arrows to bar, white arrows, an arrow with a stroke. A
+    font that lacks any of them renders a TOFU BOX, which looks like a defect in the keyboard
+    rather than in the font.
+
+    MEASURED: `browser-clicks.mjs` now compares each glyph's advance width against U+FFFD's in the
+    RESOLVED font and fails if any matches or is zero. On this machine `system-ui` resolves to a
+    face that has all twelve. **BUT `system-ui` IS A DIFFERENT FACE ON EVERY PLATFORM**, so that
+    result does not travel -- hence the named fallbacks after it, each chosen because it ships with
+    broad Arrows coverage on the platform it belongs to:
+
+      - `Segoe UI Symbol` -- Windows, the usual home for these when Segoe UI itself falls short.
+      - `Apple Symbols` -- macOS, which is the user's own platform.
+      - `Noto Sans Symbols 2` / `DejaVu Sans` -- Linux, the latter being near-universal there.
+
+    THE ORDER PUTS `system-ui` FIRST DELIBERATELY: the keyboard should look native where it can,
+    and a fallback only has to catch the glyphs the native face is missing -- per-character
+    fallback is how CSS font lists already work, so naming these costs nothing when they are
+    unneeded.
+  */
+  font-family: system-ui, 'Segoe UI Symbol', 'Apple Symbols',
+    'Noto Sans Symbols 2', 'DejaVu Sans', sans-serif;
+  font-size: 8px;
+}
+
+/*
+  THE WEB OVERLAY'S OWN HALF: BOTTOM-DOCKED, BECAUSE THE GEOMETRY ALLOWS NOTHING ELSE.
+
+  The reference hardware is 2.6:1 and about 24 key units across, so at a readable pitch the
+  keyboard is as wide as a 24x80 screen itself. Corner-anchoring it -- the arrangement the user
+  was considering for the compact KEYPAD -- is simply not available to this surface.
+
+  `position: fixed` LIKE THE OTHER TWO OVERLAYS, and load-bearing for the reason recorded further
+  up this file: the click path's `offsetX` arithmetic assumes the canvas sits at the viewport
+  origin, and a sibling in normal flow would push it down and break the OTHER front end's keypad
+  and selection clicks through the shared renderer.
+
+  OPAQUE, like the keypad, and that is also load-bearing: `keypadOverlay.ts` records that the TUI's
+  keypad once let host text bleed into its chord column. A 3270 screen behind 117 buttons is a
+  denser background still.
+
+  `overflow: auto` rather than `hidden`, matching the web page's own rule: a short viewport must be
+  able to reach the bottom row rather than having it clipped away.
+
+  NONE OF THIS IS WANTED IN THE ELECTRON WINDOW, which is the reason the two halves are separate: a
+  window is already positioned, already opaque, and already scrolls. `max-height: 60vh` in
+  particular would be actively wrong there -- it exists to stop an overlay eating the screen it is
+  drawn over, and in a window there is nothing behind it to protect.
+*/
+#keyboard-overlay {
+  position: fixed;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  max-height: 60vh;
+  overflow: auto;
+  background: Canvas;
+  color: CanvasText;
+  padding: 8px 10px;
+}
+
+#keyboard-overlay[hidden] { display: none; }
+
+/*
+  THE REGIONS SIT SIDE BY SIDE, LIKE THE REAL KEYBOARD -- MEASURED AND CORRECTED 2026-10-22.
+
+  They were plain block `div`s, so all five STACKED VERTICALLY and the surface was a tall column
+  nothing could display at once. That was wrong at EVERY width, not only on a narrow screen: there
+  was no horizontal layout at all, so nothing could have placed them.
+
+  TWO BANDS, BECAUSE THAT IS WHAT THE HARDWARE HAS. The PF strip runs across the top on its own;
+  the other four regions -- the left special bar, the main block, the cursor cluster and the
+  numeric pad -- sit in a row beneath it. Measured from the table: the lower band is 24 key units
+  wide and the PF strip is 12, so a single row of all five would have been 36 units and needlessly
+  wide.
+
+  `flex-wrap` IS DELIBERATELY ON for the lower band: on a genuinely narrow window the numeric pad
+  drops to a second line rather than being clipped. That is the behaviour the stacked column was
+  accidentally giving at all widths; here it is a fallback instead of the default.
+
+  `align-items: flex-start` so the shorter regions top-align with the main block rather than
+  stretching to its height.
+*/
+.keyboard-surface .keyboard-bands { display: flex; flex-direction: column; gap: 10px; }
+
+.keyboard-surface .keyboard-band {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: flex-start;
+  gap: 14px;
+}
+
+/*
+  WRAP PRIORITY, SO A NARROW WINDOW DEGRADES SENSIBLY RATHER THAN ARBITRARILY.
+
+  `flex-wrap: wrap` above already reflows the regions when the window narrows -- but on its own it
+  wraps in DOCUMENT ORDER, which is the table's order, and that is the wrong priority: the 2-unit
+  left special bar would keep its slot ahead of the 15-unit main block, so the main keyboard would
+  be the thing pushed to a second line. `order` makes the priority deliberate.
+
+  THE MAIN BLOCK IS FIRST AND MUST NEVER WRAP: it is the keyboard. Then the cursor cluster (the
+  arrows and Dup/Field Mark, which an operator reaches for often), then the numeric pad, and the
+  left special bar LAST because it is two units wide and holds four blank caps plus four PC keys
+  that do nothing here -- the cheapest thing on the surface to push down.
+
+  MEASURED BREAKPOINTS at pitch 28px with 14px gaps, so the degradation is known rather than
+  discovered: all four side by side need ~734px; without the numpad ~608px; main plus the special
+  bar ~510px; the main block alone ~440px. Nothing here hard-codes those -- flexbox finds them --
+  but they are written down so a future pitch change can be reasoned about.
+*/
+.keyboard-surface .keyboard-region { flex: 0 0 auto; }
+
+/*
+  ORDER: THE LEFT SPECIAL BAR IS FIRST, BECAUSE IT IS ON THE FAR LEFT OF THE HARDWARE.
+
+  CORRECTED 2026-10-22: it was ordered LAST, which put the Attn/Clear cluster on the far RIGHT --
+  the user caught it on a screenshot. That was a wrap-priority decision (two units wide, four
+  blank caps, the cheapest thing to push down) applied to the wrong property: `order` governs
+  POSITION, and on this keyboard that cluster sits left of the main block.
+
+  WRAP PRIORITY AND POSITION ARE NOW SEPARATE CONCERNS. Position comes from `order` and matches the
+  hardware left to right; what drops first when the window narrows is `flex-wrap`'s business, and
+  the container queries below tighten the gaps before anything has to move at all.
+*/
+.keyboard-surface #keyboard-special-left { order: 0; }
+.keyboard-surface #keyboard-main { order: 1; }
+.keyboard-surface #keyboard-cursor { order: 2; }
+.keyboard-surface #keyboard-numpad { order: 3; }
+
+/*
+  PER-REGION FONT SIZES, WHICH IS WHAT THE REAL HARDWARE DOES.
+
+  The user's observation, and it is the fix: "on my actual Model M, they're just F1-12, but the
+  characters are noticeably smaller than A-Z are". A 3270 keyboard does NOT letter every cap at one
+  size -- the PF and PA legends are visibly smaller than the alphabet.
+
+  WHY ONE GLOBAL SIZE COULD NOT WORK, measured: `PF13` is four capitals-and-digits on a one-unit
+  cap, and `Clear`, `Space`, `Enter`, `Shift` are five. At 24px of usable width, five capitals need
+  the font below 6.5px to fit -- unreadable. So the choice was never "what size fits everything",
+  it was "which regions need smaller type", and the hardware answers that.
+
+  THE MAIN BLOCK KEEPS THE LARGEST TYPE because its caps are mostly ONE character (`Q`, `4`, `;`)
+  and the one five-character legend it has -- `Shift` -- sits on a 1.25-unit cap with room.
+*/
+/*
+  THE PF STRIP IS CENTRED OVER THE ALPHANUMERIC BLOCK, which is where the hardware has it.
+
+  The user's request, and the arithmetic is why it needs a rule rather than `justify-content`: the
+  PF strip is 12 key units and the main block is 15, sitting at an offset of its own because the
+  left special bar (2 units) precedes it. Centring the strip within the WHOLE band would put it
+  over the gap between the main block and the cursor cluster.
+
+  SO THE OFFSET IS COMPUTED FROM THE TABLE'S OWN GEOMETRY: the special bar's 2 units plus the gap,
+  then half the difference between the main block's 15 units and the strip's 12 -- i.e. 1.5 units.
+  Written as a `calc` on the pitch so it tracks a pitch change, and as `margin-left` rather than
+  padding so it cannot interact with the band's own gap.
+*/
+.keyboard-surface #keyboard-pf {
+  margin-left: calc(2 * (var(--kb-pitch) + 2px) + 14px + 1.5 * (var(--kb-pitch) + 2px));
+}
+
+/*
+  THE SIZES, RAISED 2026-10-22 BECAUSE 7px WAS UNREADABLE -- the user's words, and the only
+  judgement in this file that a harness cannot make.
+
+  THE HEADROOM CAME FROM THE PREVIOUS FIX RATHER THAN FROM SHRINKING ANYTHING. `box-sizing:
+  border-box` and `font: inherit` together recovered real width inside each cap (a 28px cap now
+  offers 26px for text, not 24px, and the type is the size the stylesheet asks for rather than the
+  UA's 13.33px). So these can go UP while `browser-clicks.mjs` still reports no cap clipped --
+  which is the check that must stay green, and the reason these numbers are not a guess.
+
+  `PF13` is the binding constraint at 4 characters on a one-unit cap: measured per-character width
+  is 0.61em, so 4 chars at 9px need ~22px of the 26px available. 10px would need ~24.4px and leave
+  under 2px of slack, which is where the last three rounds of clipping lived.
+*/
+.keyboard-surface #keyboard-main { font-size: 11px; }
+.keyboard-surface #keyboard-pf { font-size: 9px; }
+.keyboard-surface #keyboard-cursor { font-size: 9px; }
+.keyboard-surface #keyboard-special-left { font-size: 9px; }
+.keyboard-surface #keyboard-numpad { font-size: 10px; }
+
+/*
+  AND A CONTAINER QUERY FOR THE ONE THING FLEX CANNOT DO: at the narrowest widths the gaps between
+  regions are wasted space, so they tighten before anything else has to move.
+
+  `@container` RATHER THAN `@media`, DELIBERATELY. The question is how wide THIS SURFACE is, not
+  how wide the viewport is. They were the same when the web overlay was the only surface -- it is
+  bottom-docked and full-width -- but a media query would be measuring the wrong box the moment
+  that changed, and the Electron window IS that moment: it is a window the operator can resize
+  independently of anything.
+
+  ON `.keyboard-surface` AND NOT ON `#keyboard-overlay`, 2026-10-23, for the reason the pitch is:
+  the container is the thing being queried, so naming the overlay would leave the window with no
+  container at all and these two blocks would silently never apply there. In the web page this
+  changes nothing -- the overlay element is the one carrying the class.
+*/
+.keyboard-surface { container-type: inline-size; container-name: keyboard; }
+
+@container keyboard (width < 760px) {
+  .keyboard-surface .keyboard-band { gap: 8px; }
+}
+
+@container keyboard (width < 620px) {
+  /*
+    Below the width where the numpad can sit beside the main block, the PF strip is the other
+    thing that benefits from tightening: 12 units plus padding is ~356px, so it still fits on one
+    line well past this point, and keeping it there matters more than the gap.
+  */
+  .keyboard-surface .keyboard-band { gap: 6px; }
+  .keyboard-surface .keyboard-bands { gap: 6px; }
+}
+.keyboard-surface .keyboard-row { display: flex; gap: 2px; margin-bottom: 2px; }
+
+/*
+  A ROW-SPANNING CAP, WHICH IS WHAT MAKES THE MAIN BLOCK A RECTANGLE.
+
+  The Return key covers the QWERTY and home rows on the real keyboard, and without it the home row
+  ends 1.25 units short of the one above -- the raggedness the user asked to fix. `--kb-h` is set
+  by `keyboardUi.ts` only on a cap whose table entry declares a height.
+
+  `position: relative` ON THE ROW and `absolute` on the tall cap, rather than a grid: the rows are
+  flex containers and converting the whole block to grid would re-do a layout that is otherwise
+  correct. The cap is positioned from the row's RIGHT edge, because the only tall cap on this
+  keyboard is flush right -- stated as the limit it is, rather than pretending to be general.
+
+  AND `right: 0` MEANS THE TABLE'S `x` IS NEVER READ FOR THIS CAP, which a mutation found on
+  2026-10-23: changing the Return's `x` from 13.75 to 13.5 moved nothing, because its WIDTH alone
+  decides its left edge. `keyboard3279.ts` carried a long comment crediting the `x` with keeping
+  the `{` clickable; it is the width that does. A tall cap added elsewhere would need this rule
+  generalised before its `x` meant anything.
+
+  THE HEIGHT IS `n` CAPS PLUS THE `n-1` GAPS BETWEEN THEIR ROWS, the same arithmetic the width
+  formula uses for units, with `margin-bottom: 2px` per row being the vertical gap.
+*/
+.keyboard-surface .keyboard-row { position: relative; }
+
+.keyboard-surface .keyboard-row > button[style*='--kb-h'] {
+  position: absolute;
+  right: 0;
+  top: 0;
+  /*
+    `2px` PER ROW GAP, NOT `4px` -- the cap was 2 units tall and 2px TOO TALL, so it crowded the
+    Shift row below it where every other key leaves a clean gap. The user spotted it.
+
+    THE VERTICAL GAP IS `margin-bottom: 2px` ON `.keyboard-row`, so an n-row cap spans n caps and
+    the n-1 margins between them. I had written `4px`, which is the HORIZONTAL `gap` doubled -- a
+    plausible-looking number from the wrong axis.
+  */
+  height: calc(var(--kb-h) * var(--kb-pitch) + (var(--kb-h) - 1) * 2px);
+}
+
+/*
+  THE RETURN KEY IS A PLAIN RECTANGLE, AND THE GAP BESIDE IT IS LEFT OVERSIZED ON PURPOSE.
+
+  ## THE HISTORY, BECAUSE IT IS A THREE-ROUND LESSON AND THE THIRD ROUND IS THIS ONE
+
+  The hardware's Return is an inverted L: its top half reaches further left than its bottom,
+  because the QWERTY row's punctuation stops 0.25 units short of the home row's. Drawing that
+  faithfully was attempted twice and BOTH attempts were wrong in the same way:
+
+   - A WIDER BOX. It overlapped the `{` cap below -- the home row's content really does run to
+     13.75u -- and the user saw the `{` lose its border. `browser-clicks.mjs`: `OVERLAPS by 7px`.
+   - A `::before` PAINTING THE TAB. Geometrically honest (a pseudo-element is not in the layout
+     flow, so the `{` stayed clickable) and still WRONG FOR THE USER, who looked at the result and
+     named two faults no measurement had: the overhanging half LOOKS LIKE A KEY BUT IS DEAD, and
+     the join between the element and its pseudo-element draws a VERTICAL BAR through the middle
+     of what should be one cap.
+
+  ## SO THE KEY IS RECTANGULAR AND THE SPACE IS JUST SPACE
+
+  THE CAP KEEPS THE GEOMETRY IT ALREADY HAD -- x=13.75, 1.25 units, two rows tall -- and nothing
+  is painted into the 0.25 units to its left. That space becomes a gap several times wider than
+  every other gap in the row, which is what the user asked for and reads as deliberate rather than
+  as a mistake: an oversized gap is obviously a gap, where a dead half-key is not obviously dead.
+
+  THE RULE THIS SETTLES: a shape that cannot be made clickable should not be drawn as a key. The
+  earlier rule -- paint may extend where no other key is, a clip may not hide an overlap -- was
+  about honesty to the LAYOUT, and it was right as far as it went. This is about honesty to the
+  PERSON: a cap-shaped region that does nothing is a lie told in pixels, however correct its box.
+
+  `browser-clicks.mjs` asserts all three clauses of this: the gap below equals the ordinary row
+  gap, the gap to its left is at least 3x it, and `::before`'s `content` is `none`.
+*/
+
+/*
+  THE CAP WIDTH COMES FROM THE TABLE, through the `--kb-w` custom property `keyboardUi.ts` sets
+  per button. `flex: 0 0 auto` stops flex from helpfully resizing caps and destroying the layout
+  the table describes.
+*/
+.keyboard-surface .keyboard-row > button {
+  flex: 0 0 auto;
+  /*
+    `border-box`, AND ITS ABSENCE WAS THE REAL BUG BEHIND THREE ROUNDS OF CLIPPED LABELS.
+
+    A `<button>` defaults to `content-box`, so the 2px padding and the 1px border were ADDED to
+    the width: a 28px cap reported `clientWidth: 24` for text, and the three font reductions I
+    tried were all fighting 6px of chrome rather than a font that was too big. MEASURED by asking
+    the browser which caps overflowed (`scrollWidth > clientWidth`) instead of modelling it --
+    `PF13` at 7px measures 17.2px of text and still reported `37 > 24`.
+
+    THE LESSON, which is why this comment is long: I estimated a per-character ratio twice (0.56,
+    then 0.75) and the user caught the clipping on a screenshot both times. The browser knew the
+    answer all along and `browser-clicks.mjs` now asks it. The real ratio is 0.61 -- so BOTH
+    estimates bracketed it, and neither was the problem.
+  */
+  /*
+    `font: inherit` -- AND ITS ABSENCE IS WHY THREE ROUNDS OF FONT REDUCTION DID NOTHING.
+
+    A `<button>` does NOT inherit `font` from its parent: browsers apply their own UA default, and
+    Chromium's is 13.33px. The rule further up this file that sets `font: inherit` for buttons
+    lists `.ui-surface`, `#keypad-overlay` and `#transfer-overlay` -- and NOT this overlay, which
+    did not exist when it was written. So every cap rendered at 13.33px no matter what
+    `font-size` the region carried, and the per-region sizes below were dead declarations.
+
+    MEASURED, not deduced: the harness printed PF13's computed box as `font: 13.3333px` while the
+    stylesheet said 7px. Three screenshots, three font reductions, and the font was never the
+    thing being changed.
+  */
+  font: inherit;
+  box-sizing: border-box;
+  /*
+    A MULTI-UNIT CAP MUST ABSORB THE GAPS IT SPANS -- found 2026-10-22 on the numeric pad.
+
+    This was `--kb-w * --kb-pitch`, which is one cap's width per unit and NO allowance for the 2px
+    gaps BETWEEN those units. So an n-unit cap came out 2*(n-1)px short and everything after it in
+    its row shifted left: the user spotted it as the numpad's `.` not lining up under the `3` and
+    `Ent` not under the `-`, because the double-width `0` beside them was 2px narrow. The
+    spacebar, at 7 units, was 12px short.
+
+    `+ (w - 1) * 2px` IS THE GAP COUNT, and it is exact rather than a fudge: n caps have n-1 gaps
+    between them, and a cap spanning n units replaces exactly those. The `2px` matches
+    `.keyboard-row`'s own `gap`, which is the one duplication here -- change both together.
+  */
+  width: calc(var(--kb-w, 1) * var(--kb-pitch) + (var(--kb-w, 1) - 1) * 2px);
+  height: var(--kb-pitch);
+  padding: 0 1px;
+  border-width: 1px;
+  /*
+    `overflow: hidden` IS THE TRAP THAT HID THE FONT BUG, kept because a cap must not grow and
+    destroy the layout the table describes -- but it fails SILENTLY, turning `PF13` into `PF1`
+    with no visible sign anything was lost. The font size above is what stops it mattering; this
+    comment is here so the next person to see a clipped label looks at the font rather than at
+    this line.
+  */
+  overflow: hidden;
+  /*
+    TWO LINES ARE ALLOWED, BECAUSE THE HARDWARE USES THEM -- corrected 2026-10-22.
+
+    `white-space: nowrap` was here, which forced every legend onto one line and made nine caps
+    unfittable at ANY sane font size: `Cursr Sel`, `Print Screen`, `Scroll Lock`, `Dup / PA1`,
+    `Field Mark / PA2` and the rest are MULTI-WORD legends on SINGLE-UNIT caps, and the real
+    keyboard prints them stacked. Asking for one line was the error; shrinking the font would
+    never have fixed it.
+
+    `pre-line` RATHER THAN `normal`: the labels carry explicit newlines now (see
+    `keyboard3279.ts`), so the break lands where the hardware puts it instead of wherever the cap
+    happens to run out. A legend with no newline still behaves as before.
+  */
+  white-space: pre-line;
+  /* The glyphs are small, so centre them rather than leaving them hard against the left edge. */
+  text-align: center;
+  line-height: 1.05;
+  /* Two stacked lines need the room; `height` was a single line's worth. */
+  min-height: var(--kb-pitch);
+  height: auto;
+}
+
+/*
+  AN INERT CAP, AND IT IS DELIBERATELY NOT THE HOUSE `opacity: 0.5`.
+
+  That pattern appears three times above for DISABLED CONTROLS, and it means "not right now -- try
+  again when a transfer finishes". An inert 3279 key means something different: "this exists on the
+  hardware and will never do anything here". Same visual, two incompatible promises, and a Cancel
+  button at 0.5 telling you to wait would be a lie on `Scroll Lock`.
+
+  THE LABEL MUST STAY READABLE, which is the functional reason rather than an aesthetic one: half
+  the value of drawing `Cursr Sel` at all is seeing WHERE IT SITS on the hardware, and 0.5 opacity
+  on a small cap at this font size could make `Print Screen` unreadable -- which defeats the
+  faithfulness the whole surface exists for. Hence `opacity: 1` explicitly, in case a future rule
+  above starts matching these buttons.
+
+  `keyboardUi.ts` STILL SETS THE `disabled` ATTRIBUTE, so clicks do nothing and keyboard and
+  screen-reader behaviour are correct. Only the styling departs. DO NOT "fix" this into consistency
+  with the rules above -- it was the user's explicit choice, of three options offered.
+
+  SHIFT IS NOT SELECTED HERE even though it too has no action: it carries `data-shift` and no
+  `disabled`, because it is a live control. An inert cap and an actionless-but-live cap look
+  different on purpose.
+*/
+.keyboard-surface button[disabled] {
+  color: GrayText;
+  background: color-mix(in srgb, Canvas 92%, CanvasText 8%);
+  border-style: inset;
+  opacity: 1;
+}
+
+/*
+  THE ARMED ONE-SHOT SHIFT, so the state is VISIBLE rather than remembered.
+
+  Without this the modifier would be invisible: press Shift, look at the keyboard, and nothing says
+  whether the next character will be shifted. `keyboardUi.ts` sets `data-armed` on BOTH Shift caps
+  together, since neither is distinguishable to us.
+*/
+.keyboard-surface button[data-armed='true'] {
+  background: Highlight;
+  color: HighlightText;
+  border-style: inset;
+}