ranger-compiler 3.5.0 → 3.5.2

package/dist/lib/evg/gl/evg-gestures.js

@@ -0,0 +1,209 @@
+// SPDX-License-Identifier: MIT
+//
+// Pan and zoom on an EVG canvas, from the pointers the browser reports.
+//
+// Every page that draws a scene bigger than its canvas needs the same four
+// gestures, and each of them had been written again in its own standalone:
+// drag to pan, wheel to zoom, a press that does not travel is a click, and —
+// missing everywhere — two fingers to pinch. This is that handling, once.
+//
+// WHAT IT DOES NOT DO. It never touches the scene: it reads the view the host
+// gives it (`view()`) and hands back another (`setView()`), so the host keeps
+// deciding what a view is, when to paint one, and how to coalesce them. The
+// host's own `setView` is expected to schedule rather than paint — a pinch
+// reports far more moves than a display can show.
+//
+// THE ANCHOR is what makes a zoom feel like a zoom: the point under the
+// cursor, or under the midpoint of two fingers, stays where it is. The world
+// point below it is `(screen - pan) / scale`, and keeping it there after the
+// scale changes gives `pan' = screen - (screen - pan) * (scale' / scale)` —
+// which is also what moves the picture when the fingers move, so a pinch pans
+// and zooms in one expression rather than two that fight.
+//
+// A trackpad pinch is not a touch: browsers report it as a wheel with `ctrl`
+// held, at a fraction of a notch per event. It gets its own factor, or a
+// pinch crawls where a wheel flies. Safari's own `gesture*` events are read
+// too, because a Safari trackpad may send those instead.
+
+/** How far a press may travel and still be a click, in CSS pixels. */
+const DRAG_SLOP = 4;
+
+const dist = (a, b) => Math.hypot(a.x - b.x, a.y - b.y);
+const mid = (a, b) => ({ x: (a.x + b.x) / 2, y: (a.y + b.y) / 2 });
+
+/**
+ * Attach pan and zoom to a canvas.
+ *
+ *   attachViewGestures(canvas, {
+ *     view: () => ({ x, y, sc }),   // the pan and scale in force
+ *     setView: (x, y, sc) => {},    // schedule this one
+ *     minZoom, maxZoom,             // optional clamps
+ *     onTap: (clientX, clientY) => {},   // a press that did not travel
+ *     onCursor: (name) => {},       // "grab" / "grabbing", for the host's CSS
+ *   })
+ *
+ * Returns a function that removes every listener again.
+ */
+export function attachViewGestures(el, opts) {
+  const view = opts.view;
+  const setView = opts.setView;
+  const minZoom = opts.minZoom ?? 0.05;
+  const maxZoom = opts.maxZoom ?? 16;
+  const onTap = opts.onTap || (() => {});
+  const onCursor = opts.onCursor || (() => {});
+
+  // Every pointer currently down on the canvas, in canvas coordinates.
+  const points = new Map();
+  let drag = null;   // one pointer: a pan, or a click that has not moved yet
+  let pinch = null;  // two pointers: the scale and the midpoint they started at
+  let gestureScale = 1;
+
+  const at = (ev) => {
+    const r = el.getBoundingClientRect();
+    return { x: ev.clientX - r.left, y: ev.clientY - r.top };
+  };
+
+  /** Scale by `factor` about a point on the canvas, which stays put. */
+  function zoomAbout(factor, px, py) {
+    const now = view();
+    const next = Math.min(maxZoom, Math.max(minZoom, now.sc * factor));
+    if (next === now.sc) return;
+    const k = next / now.sc;
+    setView(px - (px - now.x) * k, py - (py - now.y) * k, next);
+  }
+
+  function beginPinch() {
+    const [a, b] = [...points.values()];
+    pinch = { d0: dist(a, b), m0: mid(a, b), view: { ...view() } };
+    drag = null;
+    onCursor("grabbing");
+  }
+
+  function movePinch() {
+    const [a, b] = [...points.values()];
+    const d = dist(a, b);
+    if (!pinch.d0 || !d) return;
+    const m = mid(a, b);
+    const want = pinch.view.sc * (d / pinch.d0);
+    const sc = Math.min(maxZoom, Math.max(minZoom, want));
+    const k = sc / pinch.view.sc;
+    // The world point under the fingers' midpoint when the pinch began is
+    // put back under the midpoint where they are now: the spread scales,
+    // the travel pans.
+    setView(m.x - (pinch.m0.x - pinch.view.x) * k, m.y - (pinch.m0.y - pinch.view.y) * k, sc);
+  }
+
+  // Capture keeps the moves coming when a finger leaves the canvas, and is
+  // not worth a broken gesture when the browser will not give it: a pointer
+  // the host synthesised has no capture to take.
+  const capture = (id) => { try { el.setPointerCapture(id); } catch (_) { /* no capture */ } };
+  const release = (id) => { try { if (el.hasPointerCapture(id)) el.releasePointerCapture(id); } catch (_) { /* gone */ } };
+
+  const onDown = (ev) => {
+    points.set(ev.pointerId, at(ev));
+    capture(ev.pointerId);
+    if (points.size === 2) {
+      beginPinch();
+      return;
+    }
+    if (points.size > 2) return;
+    const now = view();
+    drag = { id: ev.pointerId, from: at(ev), ox: now.x, oy: now.y, moved: false, button: ev.button };
+  };
+
+  const onMove = (ev) => {
+    if (!points.has(ev.pointerId)) return;
+    points.set(ev.pointerId, at(ev));
+    if (pinch && points.size >= 2) {
+      movePinch();
+      return;
+    }
+    if (!drag || ev.pointerId !== drag.id) return;
+    const p = at(ev);
+    const dx = p.x - drag.from.x;
+    const dy = p.y - drag.from.y;
+    if (!drag.moved && Math.abs(dx) + Math.abs(dy) < DRAG_SLOP) return;
+    if (!drag.moved) onCursor("grabbing");
+    drag.moved = true;
+    // The scene is laid out in CSS pixels and so is the pan: the pointer's
+    // travel goes in as it comes. Scaling it by the device pixel ratio makes
+    // the page slide at twice the cursor's speed on a HiDPI screen.
+    setView(drag.ox + dx, drag.oy + dy, view().sc);
+  };
+
+  const onUp = (ev) => {
+    const had = points.delete(ev.pointerId);
+    release(ev.pointerId);
+    if (!had) return;
+    onCursor("grab");
+    if (pinch) {
+      pinch = null;
+      // One finger left on the glass goes on panning from where it is,
+      // rather than the picture stopping until it is lifted and put down.
+      if (points.size === 1) {
+        const [id] = [...points.keys()];
+        const now = view();
+        drag = { id, from: points.get(id), ox: now.x, oy: now.y, moved: true, button: 0 };
+      }
+      return;
+    }
+    if (!drag || ev.pointerId !== drag.id) return;
+    const wasDrag = drag.moved;
+    const button = drag.button;
+    drag = null;
+    if (!wasDrag && button === 0) onTap(ev.clientX, ev.clientY);
+  };
+
+  const onWheel = (ev) => {
+    ev.preventDefault();
+    // Firefox reports wheel deltas in lines and Chrome in pixels: one notch
+    // of the same wheel arrives as 3 there and as 100 here. Counting a line
+    // as 33 pixels makes a notch a notch in both, which is the point — a
+    // line's real height would make Firefox scroll at half speed.
+    const perUnit = ev.deltaMode === 1 ? 33 : ev.deltaMode === 2 ? 400 : 1;
+    const dy = Math.max(-240, Math.min(240, ev.deltaY * perUnit));
+    // A trackpad pinch is a wheel with ctrl held, and it arrives a fraction
+    // of a notch at a time: on the wheel's own scale a pinch would crawl.
+    const rate = ev.ctrlKey ? 0.01 : 0.0015;
+    const p = at(ev);
+    zoomAbout(Math.exp(-dy * rate), p.x, p.y);
+  };
+
+  // Safari's trackpad pinch, which is not a wheel. Preventing the default is
+  // what keeps it from zooming the whole page instead of the canvas.
+  const onGestureStart = (ev) => { ev.preventDefault(); gestureScale = ev.scale || 1; };
+  const onGestureChange = (ev) => {
+    ev.preventDefault();
+    const s = ev.scale || 1;
+    if (!gestureScale) gestureScale = s;
+    const p = at(ev);
+    zoomAbout(s / gestureScale, p.x, p.y);
+    gestureScale = s;
+  };
+  const onGestureEnd = (ev) => { ev.preventDefault(); gestureScale = 1; };
+
+  el.addEventListener("pointerdown", onDown);
+  el.addEventListener("pointermove", onMove);
+  el.addEventListener("pointerup", onUp);
+  el.addEventListener("pointercancel", onUp);
+  el.addEventListener("wheel", onWheel, { passive: false });
+  el.addEventListener("gesturestart", onGestureStart);
+  el.addEventListener("gesturechange", onGestureChange);
+  el.addEventListener("gestureend", onGestureEnd);
+
+  return function detach() {
+    el.removeEventListener("pointerdown", onDown);
+    el.removeEventListener("pointermove", onMove);
+    el.removeEventListener("pointerup", onUp);
+    el.removeEventListener("pointercancel", onUp);
+    el.removeEventListener("wheel", onWheel);
+    el.removeEventListener("gesturestart", onGestureStart);
+    el.removeEventListener("gesturechange", onGestureChange);
+    el.removeEventListener("gestureend", onGestureEnd);
+    points.clear();
+    drag = null;
+    pinch = null;
+  };
+}
+
+export { DRAG_SLOP };

package/dist/lib/evg/gl/evg-list.js

@@ -0,0 +1,167 @@
+// SPDX-License-Identifier: MIT
+//
+// The display list as the painter wants it, read straight off the Ranger
+// object — no JSON in between.
+//
+// A host that shares a process with the app used to ask for `toJson()` and
+// parse it back: a string of every coordinate on the page written and read
+// on every frame, and a heap of garbage to collect after. That is the whole
+// of what this file removes. It has to produce exactly what `toJson` would,
+// key for key — `rt:scroll` holds the two against each other on every frame
+// it draws — because the painter was written against the JSON and nothing in
+// it should have to know which way the list arrived.
+//
+// Numbers come through as they are rather than rounded to the hundredth the
+// JSON writer spells, which is the one difference: the painter gets what the
+// layout computed, not its decimal form.
+
+/** The commands of an `EVGDisplayList` in the JSON writer's shape. */
+/** The camera the list carries, or null. Mirrors `viewOfBinary`. */
+export function viewOf(dl) {
+  if (!dl || !dl.hasView) return null;
+  return { x: dl.viewX || 0, y: dl.viewY || 0, scale: dl.viewScale === undefined ? 1 : dl.viewScale };
+}
+
+export function cmdsOf(dl) {
+  const attribute = !!dl.attribute;
+  const out = new Array(dl.cmds.length);
+  for (let i = 0; i < dl.cmds.length; i += 1) {
+    const c = dl.cmds[i];
+    const o = { k: c.kind };
+    if (attribute) o.n = c.node;
+    if (c.layer > 0) o.layer = c.layer;
+    o.x = c.x;
+    o.y = c.y;
+    o.w = c.w;
+    o.h = c.h;
+    if (c.perCorner) o.rc = [c.radius, c.radiusTR, c.radiusBR, c.radiusBL];
+    if (c.radius > 0) o.r = c.radius;
+    if (c.thickness > 0) {
+      o.t = c.thickness;
+      // Guarded, not just compared: this reads the Ranger object off a
+      // BUILT bundle, and a bundle compiled before a field existed has no
+      // such property. `undefined !== 0` is true, so an unguarded test
+      // would hand the painter `cap: undefined` rather than no cap.
+      if (c.strokeCap) o.cap = c.strokeCap;
+      if (c.strokeJoin) o.join = c.strokeJoin;
+      if (c.strokeDash) {
+        o.dash = c.strokeDash;
+        if (c.strokeDashOffset) o.dashoff = c.strokeDashOffset;
+      }
+    }
+    o.c = [c.r, c.g, c.b, c.a];
+    if (c.hasGrad) {
+      o.gd = c.gradDir;
+      o.c2 = [c.r2, c.g2, c.b2, c.a2];
+    }
+    if (c.text.length > 0) {
+      o.text = c.text;
+      o.font = c.fontFamily;
+      o.size = c.fontSize;
+      if (c.fontWeight.length > 0) o.weight = c.fontWeight;
+      if (c.letterSpacing !== 0) o.ls = c.letterSpacing;
+      if (c.textAlign === "italic") o.italic = true;
+    }
+    if (c.src.length > 0) o.src = c.src;
+    if (c.flipH) o.fx = true;
+    if (c.flipV) o.fy = true;
+    // The crop window into the source: a picture is not always shown whole,
+    // and a reader that drops this draws the whole frame where a detail
+    // belongs.
+    if (c.hasCrop) o.cu = [c.cropX, c.cropY, c.cropX + c.cropW, c.cropY + c.cropH];
+    if (c.rotate !== 0) {
+      o.rot = c.rotate;
+      if (c.hasRotOrigin) {
+        o.rox = c.rotOriginX;
+        o.roy = c.rotOriginY;
+      }
+    }
+    if (c.backdropBlur > 0) o.bb = c.backdropBlur;
+    // The effect instance this rectangle carries, by name — the display list's
+    // `efx`. Guarded like the stroke fields above: a bundle compiled before
+    // the field existed has no such property.
+    if (c.effectId) o.efx = c.effectId;
+    // The shadow, which the JSON never carried and the binary now does
+    // (`evg-binary.js`): written here too so the two readers agree key for
+    // key, and so a painter that wants it has it whichever way the list came.
+    if (c.hasShadow) {
+      o.sh = { x: c.shadowX, y: c.shadowY, blur: c.shadowBlur, c: [c.shadowR, c.shadowG, c.shadowB, c.shadowA] };
+    }
+    if (c.pts.length > 0) {
+      o.pts = c.pts.slice();
+      o.ends = c.ringEnds.length === 0 ? [c.pts.length] : c.ringEnds.slice();
+      if (c.evenOdd) o.eo = 1;
+    }
+    out[i] = o;
+  }
+  return out;
+}
+
+/** The surface effect, or undefined — the JSON's `effect`. */
+export function effectOf(dl) {
+  if (!dl.effectKind || dl.effectKind.length === 0) return undefined;
+  const drops = [];
+  for (let i = 0; i < dl.effectAges.length; i += 1) {
+    drops.push([dl.effectXs[i], dl.effectYs[i], dl.effectAges[i]]);
+  }
+  return {
+    kind: dl.effectKind,
+    drops,
+    speed: dl.effectSpeed,
+    width: dl.effectWidth,
+    strength: dl.effectStrength,
+    decay: dl.effectDecay,
+    highlight: dl.effectHighlight,
+    rings: dl.effectRings,
+    stagger: dl.effectStagger,
+    falloff: dl.effectFalloff,
+    shine: dl.effectShine,
+    gloss: dl.effectGloss,
+    bump: dl.effectBump,
+    light: [dl.effectLightX, dl.effectLightY, dl.effectLightZ],
+  };
+}
+
+/** The element-scoped effects — the JSON's `effects`. One per element that
+ *  declared `evg-surface-effect`, with the box the layout gave it, the
+ *  trigger the sheet wrote and whatever `evg-fx-*` parameters came with it.
+ *  Undefined when the page declares none, which keeps a list that has no
+ *  effects on it exactly the object it was. */
+export function effectsOf(dl) {
+  const ids = dl.fxIds;
+  if (!ids || ids.length === 0) return undefined;
+  const out = new Array(ids.length);
+  for (let i = 0; i < ids.length; i += 1) {
+    const p = {};
+    const start = dl.fxParamStart[i];
+    for (let k = 0; k < dl.fxParamCount[i]; k += 1) p[dl.fxParamNames[start + k]] = dl.fxParamValues[start + k];
+    // Written in the order `toJson` writes them, so the two readers produce
+    // objects a person can diff as well as a comparison can.
+    const e = { id: ids[i], kind: dl.fxKinds[i] };
+    if (dl.fxTriggers[i]) e.on = dl.fxTriggers[i];
+    e.box = [dl.fxX[i], dl.fxY[i], dl.fxW[i], dl.fxH[i]];
+    if (dl.fxRadius[i] > 0) e.r = dl.fxRadius[i];
+    e.p = p;
+    out[i] = e;
+  }
+  return out;
+}
+
+/** How far each scroll layer's content has moved since the list was built —
+ *  the JSON's `shifts`. Read on every frame: it is the one thing about a kept
+ *  list that changes. */
+export function shiftsOf(dl) {
+  const out = new Array(dl.layerShiftX.length);
+  for (let i = 0; i < dl.layerShiftX.length; i += 1) out[i] = [dl.layerShiftX[i], dl.layerShiftY[i]];
+  return out;
+}
+
+/** The whole list, as `JSON.parse(dl.toJson())` would give it. */
+export function listOf(dl) {
+  const out = { seq: dl.buildSeq, shifts: shiftsOf(dl), cmds: cmdsOf(dl) };
+  const effect = effectOf(dl);
+  if (effect) out.effect = effect;
+  const effects = effectsOf(dl);
+  if (effects) out.effects = effects;
+  return out;
+}

package/dist/lib/evg/gl/evg-measure.js

@@ -0,0 +1,186 @@
+// SPDX-License-Identifier: MIT
+//
+// The browser measures, EVG breaks the lines.
+//
+// PLAN_NATIVE_HOSTS.md S0, the web half. `EVGHostTextMeasurer` (Ranger) takes
+// ONE function from the platform — width of a run, and a face's ascent,
+// descent and line gap — and every layout in the compiled module then
+// measures with it. This file is that function for a browser: a 2D canvas
+// context and `measureText`, with the font shorthand built EXACTLY as the
+// painters build theirs (`evg-webgl.js` and `evg-html.js` `fontSpec`), so the
+// face the layout measured with is the face the atlas or the `<text>` node
+// draws with. Before this, the layout measured with the advance table — one
+// browser's sans, snapshotted once — and the painter drew with whatever this
+// browser resolved, which is the gap S0 exists to close.
+//
+// It works in a Worker too (`OffscreenCanvas`), which is what S1 wants: the
+// engine off the main thread, measuring where it lays out.
+//
+// WHAT IT DOES NOT DO. It does not decide which module to install into: a
+// page that bundles several generated modules has several `EVGDefaultMeasurer`
+// singletons — two copies of a class are two classes — and installs into
+// each. `installCanvasMeasurer(modules)` takes the list.
+//
+// ONE FACT WORTH KNOWING. Canvas has no line gap. `fontBoundingBoxAscent` and
+// `Descent` are the face's, but `line-height: normal` in CSS is ascent +
+// descent + the face's lineGap, and the sans fallback's gap is real: 1.15em
+// of line box against 1.117em of ascent + descent. So in a document the gap
+// is measured off a hidden element with `line-height: normal`, once per face;
+// in a worker there is no element, and the host says "unknown" (a negative
+// number), which the Ranger side reads as zero.
+
+const LRO = "\u202D", PDF = "\u202C";
+
+/**
+ * The family a command names, stripped of the `-Bold` suffix
+ * `EVGElement.effectiveFontFamily` adds for a bold element. The suffix is a
+ * convention for the TTF measurers (`FontManager` reads `Family-Bold` as the
+ * bold face); a browser reads it as a family nobody has and falls to the
+ * stack. The weight arrives separately, and that is what the browser uses.
+ */
+export function familyOf(name) {
+  const f = name || "";
+  return f.endsWith("-Bold") ? f.slice(0, -5) : f;
+}
+
+/**
+ * Make a measurer for one compiled module and attach the browser to it.
+ *
+ * @param {object} mod  the generated module: `EVGHostTextMeasurer` and
+ *                      `EVGDefaultMeasurer` are read off it
+ * @param {object} [opts]
+ * @param {string[]} [opts.fallback]  the families the browser may fall back
+ *                      to, in order — the same list handed to the painter's
+ *                      `setFontFallback`, so the two walks agree
+ * @param {boolean} [opts.install=true]  make it the module's default
+ * @returns {{ measurer: object, refresh: () => void, detach: () => void }}
+ */
+export function createCanvasMeasurer(mod, opts = {}) {
+  if (!mod || typeof mod.EVGHostTextMeasurer !== "function") {
+    throw new Error("evg-measure: the module has no EVGHostTextMeasurer — import EVGLayout.rgr (or EVGTextEngine.rgr) in the Ranger program");
+  }
+  const stackList = (opts.fallback || []).filter((f) => f && f.length).map((f) => `"${f}"`);
+  stackList.push("sans-serif");
+  const fallbackStack = stackList.join(", ");
+
+  const ctx = makeContext();
+  // Face metrics by font spec: the vertical numbers are a property of the
+  // face at a size, not of any string, so three answers serve every run.
+  const faces = new Map();
+  let currentFont = "";
+
+  const spec = (family, size, bold, italic) => {
+    const fam = family && family.length ? `"${family}", ${fallbackStack}` : fallbackStack;
+    return `${italic ? "italic " : ""}${bold ? "bold " : ""}${size}px ${fam}`;
+  };
+
+  const setFont = (s) => {
+    if (s !== currentFont) {
+      ctx.font = s;
+      currentFont = s;
+    }
+  };
+
+  const faceOf = (s, size) => {
+    let f = faces.get(s);
+    if (f) return f;
+    setFont(s);
+    // "Hg" rather than any run: the face's box is the same for every string.
+    const m = ctx.measureText("Hg");
+    const asc = m.fontBoundingBoxAscent || 0;
+    const desc = m.fontBoundingBoxDescent || 0;
+    f = { asc, desc, gap: normalGap(s, asc + desc, size) };
+    faces.set(s, f);
+    return f;
+  };
+
+  const metric = (kind, text, family, size, bold, italic) => {
+    const s = spec(family, size, bold, italic);
+    if (kind === 0) {
+      if (!text) return 0;
+      setFont(s);
+      // The same bidi override the painters apply: EVG has already ordered
+      // the runs, and a measurement that reorders inside one is a different
+      // width from the one that will be drawn.
+      return ctx.measureText(LRO + text + PDF).width;
+    }
+    const f = faceOf(s, size);
+    if (kind === 1) return f.asc;
+    if (kind === 2) return f.desc;
+    return f.gap;
+  };
+
+  const measurer = new mod.EVGHostTextMeasurer();
+  measurer.attach(metric, "canvas");
+  if (opts.install !== false) mod.EVGDefaultMeasurer.install(measurer);
+
+  return {
+    measurer,
+    /** A face finished loading (`document.fonts.ready`): forget what was
+     *  measured with the fallback and move the key, so every engine holding
+     *  this measurer measures again. */
+    refresh() {
+      faces.clear();
+      currentFont = "";
+      measurer.invalidate();
+    },
+    /** Back to the table. */
+    detach() {
+      measurer.detach();
+      if (opts.install !== false) mod.EVGDefaultMeasurer.uninstall();
+    },
+  };
+}
+
+/**
+ * The same, for every module a page bundles. Returns one handle whose
+ * `refresh` refreshes them all — a page has one `document.fonts.ready`.
+ */
+export function installCanvasMeasurer(modules, opts = {}) {
+  const list = Array.isArray(modules) ? modules : [modules];
+  const made = list.map((m) => createCanvasMeasurer(m, opts));
+  return {
+    measurers: made.map((h) => h.measurer),
+    refresh() { for (const h of made) h.refresh(); },
+    detach() { for (const h of made) h.detach(); },
+  };
+}
+
+// ---------------------------------------------------------------------------
+
+function makeContext() {
+  if (typeof document !== "undefined" && document.createElement) {
+    const canvas = document.createElement("canvas");
+    canvas.width = 8;
+    canvas.height = 8;
+    const ctx = canvas.getContext("2d");
+    if (ctx) return ctx;
+  }
+  if (typeof OffscreenCanvas !== "undefined") {
+    const ctx = new OffscreenCanvas(8, 8).getContext("2d");
+    if (ctx) return ctx;
+  }
+  throw new Error("evg-measure: no 2D canvas context available here");
+}
+
+// The line gap, from the one place a browser states it: the height of a
+// line box at `line-height: normal`. Measured at the face's own size — the
+// gap scales with the em, and rounding at a small size is what it is.
+let probe = null;
+function normalGap(fontSpec, ascPlusDesc, size) {
+  if (typeof document === "undefined" || !document.body) return -1;
+  if (!probe) {
+    probe = document.createElement("div");
+    probe.setAttribute("aria-hidden", "true");
+    probe.style.cssText = "position:absolute;left:-10000px;top:0;visibility:hidden;white-space:nowrap;line-height:normal;padding:0;border:0;margin:0;pointer-events:none";
+    probe.textContent = "Hg";
+    document.body.appendChild(probe);
+  }
+  probe.style.font = fontSpec;
+  const h = probe.getBoundingClientRect().height;
+  if (!(h > 0) || !(ascPlusDesc > 0)) return -1;
+  const gap = h - ascPlusDesc;
+  // A negative gap is a rounding artefact of a box measured in whole pixels
+  // against metrics measured in fractions; a face has no negative gap.
+  return gap > 0 ? gap : 0;
+}