@godot-scene-web/hb-gpu 0.1.0

package/dist/webgl.js

@@ -0,0 +1,1624 @@
+import "./index.js";
+//#region src/webgl.ts
+/**
+* Upstream's `ATLAS_TEX_WIDTH`, and the width this renderer PREFERS rather than the one it gets.
+*
+* Wide and short keeps the unwrap arithmetic in `int` range. WebGL2 only guarantees
+* `MAX_TEXTURE_SIZE >= 2048`, so a device can refuse 4096 — read {@link HbGpuRenderer.atlasWidth}
+* for the width an instance actually built, and never assume this constant describes it. The
+* shader is handed the achieved width as `hb_gpu_atlas_width`, so any width is legal.
+*/
+const ATLAS_WIDTH = 4096;
+/**
+* Below this the renderer refuses rather than clamps.
+*
+* A 5 KB Han blob is ~675 texels: at 1024 wide the upload is at most a couple of `texSubImage2D`
+* calls, and narrower rows turn one glyph into dozens of them. A device reporting below WebGL2's
+* own guaranteed 2048 is broken or emulated, and is not one this renderer can be measured on.
+*/
+const MIN_ATLAS_WIDTH = 1024;
+const LEGACY_INSTANCE_FLOATS = 10;
+const BATCHED_INSTANCE_FLOATS = 21;
+/**
+* The GLSL preamble every stage gets, and the one line in it that is load-bearing.
+*
+* `#define HB_GPU_ATLAS_2D` selects `uniform highp isampler2D hb_gpu_atlas` plus the
+* `hb_gpu_atlas_width` unwrap over the `isamplerBuffer` path. It is defined HERE, in the shader,
+* and not by the wasm build: the C macro of the same name only reaches `util/gpu/demo-atlas.cc`,
+* which this package does not compile, so the `-DHB_GPU_ATLAS_2D` on the em++ line does not select
+* anything. The `#ifdef` that matters lives inside the GLSL the module hands back.
+*
+* `highp int` is not decoration either: atlas offsets are absolute texel indices into a stream that
+* runs to hundreds of thousands, and `mediump int` is only guaranteed 16 bits. Worse, a precision
+* that disagrees across the two stages fails to LINK with no diagnostic on some drivers, so this
+* string is shared by both on purpose.
+*/
+const GLSL_PREAMBLE = "#version 300 es\nprecision highp float;\nprecision highp int;\n#define HB_GPU_ATLAS_2D\n";
+/**
+* OUR macro, and the reason it is not HarfBuzz's `HB_GPU_NO_MSAA`, which is the whole safety
+* argument for {@link HbGpuRendererOptions.spreadTapMsaa}.
+*
+* `HB_GPU_NO_MSAA` is defined by the vendored library and guards `_hb_gpu_slug` — the FILL. Reusing
+* it to switch the dilation's taps would switch the fill's five-sample average off at the same time,
+* silently, and the fill is the one thing this trade is not allowed to touch. A separate name makes
+* that structural rather than a thing to remember: `hb_gpu_draw` reaches `_hb_gpu_slug` inside the
+* library's own source, which this define cannot reach into.
+*/
+const SPREAD_TAP_NO_MSAA_DEFINE = "#define HB_GPU_SPREAD_TAP_NO_MSAA\n";
+/**
+* THE DILATION'S WHOLE TAP BUDGET, as one number, and the reason it is one number.
+*
+* It bounds the flat loop in {@link FRAGMENT_MAIN} — one tap per iteration — so the compile-time
+* ceiling IS the worst-case tap count: 64 unrolled sites, plus `hb_gpu_draw`'s own centre tap, is 65
+* evaluations for the most expensive fragment there is. That was also the ceiling of the nested
+* `4 rings x 16 steps` loops this replaced, so the redistribution below is free at the top end.
+*
+* WHY THE SHAPE CHANGED RATHER THAN THE NUMBER. The nested form clamped EVERY ring to the same 16
+* steps, so past `radius * t > 2.5 px` all four rings ran 16 taps — and the outermost one, which is
+* the only ring that decides where the dilated boundary lands, was then the SPARSEST: at radius 12
+* its taps sit 4.71 px of arc apart, while ring 1 spends the same 16 on a circle a quarter the size
+* and puts them 1.18 px apart. Giving
+* the outer ring more steps in that shape would have meant raising the per-ring cap, and 4 x 28 is
+* 112 unrolled sites for a budget most fragments never spend. A flat loop makes "how many taps may a
+* fragment cost" and "how are they arranged" two independent decisions, and only the first one is a
+* perf number.
+*
+* INTERPOLATED INTO THE GLSL rather than restated there, so `spreadBudget.test.ts` can assert on the
+* arithmetic that divides it between rings and on the ceiling reaching the shader, from one source.
+*/
+const HB_GPU_SPREAD_MAX_TAPS = 64;
+/**
+* OUR entry point for the vertex stage. Roughly 30 lines, and unavoidably ours.
+*
+* HarfBuzz ships `hb_gpu_dilate` and no `main`, because it cannot know what a consumer's
+* attributes are called. Upstream writes the same wrapper for its demo in
+* `util/gpu/demo-vertex.glsl`; this one is written against `hb-gpu-vertex.glsl`'s documented
+* contract rather than copied from it, and it differs where the pipeline does — a corner is
+* interpolated out of an instance record here, where upstream reads four expanded vertices.
+*
+* `jac` IS THE INVERSE OF THE EM-TO-OBJECT LINEAR PART, and the y term is negative because em
+* space is y-up and this renderer's object space is y-down device pixels. HarfBuzz's header spells
+* out the case: em-to-object `[[s, 0], [0, -s]]` gives `jac = (1/s, 0, 0, -1/s)`, and `1/s` is
+* exactly `a_emPerPos`. Drop the sign and the dilation pushes the texcoord the wrong way in y,
+* which shows up as a half-pixel of missing ink along horizontal edges only.
+*
+* IT ALSO GROWS THE QUAD BY {@link HbGpuRenderer.setSpread}, AND WITHOUT THAT THERE IS NO OUTLINE
+* AT ALL. `a_position` / `a_texcoord` are the glyph's INK box: the fragment stage's dilation is a
+* max of coverage taps up to `spread` away, so ink that is `spread` OUTSIDE the box has to have a
+* fragment to be found from. Left out, every tap that would have reached ink is simply never
+* rasterised and the whole feature fails as "the outline did not appear" — silently, with a
+* perfectly correct-looking fill. Measured by deleting these two lines: the dilated ink box then
+* grows 0-1 px instead of 4, while the superset and interior checks stay green.
+*
+* THE EXPANSION GOES THROUGH `jac`, not through a hand-written sign pattern, and that is worth the
+* one extra line. `a_normal` IS the object-space outward normal at this corner (the file header
+* says why), so `a_normal * a_spreadPx` is the object-space displacement; `jac` is by definition
+* the map from an object displacement to the em displacement that matches it, which is exactly
+* what `hb_gpu_dilate` uses it for two lines below. Spelling the em half out separately would be a
+* second chance to get the y flip backwards, and a backwards y flip here reads as an outline that
+* is present but shifted — not as an error.
+*/
+const BATCHED_VERTEX_MAIN = `
+uniform mat4 u_viewProjection;
+uniform vec2 u_viewport;
+
+/* Per-vertex: the corner sign, which IS the outward normal at that corner. */
+in vec2 a_normal;
+
+/* Per-instance, divisor 1. */
+in vec4 a_position;   /* object-space box: (x at cx=0, y at cy=0, x at cx=1, y at cy=1) */
+in vec4 a_texcoord;   /* em-space ink box: (minX, minY, maxX, maxY) */
+in float a_emPerPos;  /* em units per object unit, i.e. upem / pixelsPerEm */
+in uint a_glyphLoc;   /* first texel of this glyph's blob in the atlas */
+in vec2 a_model0;
+in vec2 a_model1;
+in vec2 a_model2;
+in vec4 a_color;
+in float a_spreadPx;
+
+out vec2 v_texcoord;
+flat out uint v_glyphLoc;
+/* The spread in EM units for THIS instance. Flat, and a varying rather than a second uniform,
+ * because the object-to-em factor is a_emPerPos and that is per-instance: one uniform in em units
+ * could not mean the same number of pixels for two glyphs pushed at different pixelsPerEm. */
+flat out float v_spreadEm;
+flat out float v_spreadPx;
+flat out vec4 v_color;
+
+void main ()
+{
+  /* (-1, +1) -> (0, 0) and (+1, -1) -> (1, 1): the y term is flipped because a corner's outward
+   * normal points UP in object space exactly when it is the box's minimum em coordinate. */
+  vec2 corner = vec2 (a_normal.x, -a_normal.y) * 0.5 + 0.5;
+
+  vec2 pos = mix (a_position.xy, a_position.zw, corner);
+  vec2 tex = mix (a_texcoord.xy, a_texcoord.zw, corner);
+
+  vec4 jac = vec4 (a_emPerPos, 0.0, 0.0, -a_emPerPos);
+  mat4 model = mat4 (
+    vec4 (a_model0, 0.0, 0.0),
+    vec4 (a_model1, 0.0, 0.0),
+    vec4 (0.0, 0.0, 1.0, 0.0),
+    vec4 (a_model2, 0.0, 1.0));
+  mat4 mvp = u_viewProjection * model;
+  float spreadPx = a_spreadPx;
+  vec4 color = a_color;
+
+  /* At spread 0 both of these add 0.0, which is the identity for every finite value — the fill
+   * path really is byte-for-byte what it was before the outline path existed. */
+  vec2 spreadPos = a_normal * spreadPx;
+  pos += spreadPos;
+  tex += vec2 (dot (spreadPos, jac.xy), dot (spreadPos, jac.zw));
+
+  hb_gpu_dilate (pos, tex, a_normal, jac, mvp, u_viewport);
+
+  gl_Position = mvp * vec4 (pos, 0.0, 1.0);
+  v_texcoord = tex;
+  v_glyphLoc = a_glyphLoc;
+  v_spreadEm = spreadPx * a_emPerPos;
+  v_spreadPx = spreadPx;
+  v_color = color;
+}
+`;
+const VERTEX_MAIN = `
+uniform mat4 u_matViewProjection;
+uniform vec2 u_viewport;
+uniform float u_spreadPx;  /* OBJECT units, pre-model. 0 disables the whole path. */
+
+/* Per-vertex: the corner sign, which IS the outward normal at that corner. */
+in vec2 a_normal;
+
+/* Per-instance, divisor 1. */
+in vec4 a_position;   /* object-space box: (x at cx=0, y at cy=0, x at cx=1, y at cy=1) */
+in vec4 a_texcoord;   /* em-space ink box: (minX, minY, maxX, maxY) */
+in float a_emPerPos;  /* em units per object unit, i.e. upem / pixelsPerEm */
+in uint a_glyphLoc;   /* first texel of this glyph's blob in the atlas */
+
+out vec2 v_texcoord;
+flat out uint v_glyphLoc;
+/* The spread in EM units for THIS instance. Flat, and a varying rather than a second uniform,
+ * because the object-to-em factor is a_emPerPos and that is per-instance: one uniform in em units
+ * could not mean the same number of pixels for two glyphs pushed at different pixelsPerEm. */
+flat out float v_spreadEm;
+
+void main ()
+{
+  /* (-1, +1) -> (0, 0) and (+1, -1) -> (1, 1): the y term is flipped because a corner's outward
+   * normal points UP in object space exactly when it is the box's minimum em coordinate. */
+  vec2 corner = vec2 (a_normal.x, -a_normal.y) * 0.5 + 0.5;
+
+  vec2 pos = mix (a_position.xy, a_position.zw, corner);
+  vec2 tex = mix (a_texcoord.xy, a_texcoord.zw, corner);
+
+  vec4 jac = vec4 (a_emPerPos, 0.0, 0.0, -a_emPerPos);
+
+  /* At spread 0 both of these add 0.0, which is the identity for every finite value — the fill
+   * path really is byte-for-byte what it was before the outline path existed. */
+  vec2 spreadPos = a_normal * u_spreadPx;
+  pos += spreadPos;
+  tex += vec2 (dot (spreadPos, jac.xy), dot (spreadPos, jac.zw));
+
+  hb_gpu_dilate (pos, tex, a_normal, jac, u_matViewProjection, u_viewport);
+
+  gl_Position = u_matViewProjection * vec4 (pos, 0.0, 1.0);
+  v_texcoord = tex;
+  v_glyphLoc = a_glyphLoc;
+  v_spreadEm = u_spreadPx * a_emPerPos;
+}
+`;
+/**
+* OUR entry point for the fragment stage. Same ownership note as {@link VERTEX_MAIN}.
+*
+* STEM DARKENING AND GAMMA ARE HERE AND ON BY DEFAULT, and the thing that is now a MEASUREMENT
+* decision is switching them OFF — see {@link HbGpuRendererOptions.contrast} and
+* {@link HB_GPU_CONTRAST_NONE}. Both are contrast corrections that move coverage AWAY from correct
+* area coverage, which is exactly what a fidelity arm grades against (`docs/text-rendering.md`: the
+* reference is an 8x render box-downsampled, "a ceiling, not a mechanism"), so a HARNESS that left
+* them on would be scoring its own contrast curve. A shipping consumer is not a harness: raw
+* coverage puts a sub-pixel stem at mid-grey where a browser puts it near the ink colour, which is
+* measurably why DOM text out-reads this path at small sizes.
+*
+* The block below is `util/gpu/demo-fragment.glsl`'s, with two differences that are ours:
+* `brightness` comes off per-instance `v_color.rgb` directly (which is STRAIGHT, so upstream's divide by the
+* premultiplied alpha is already done) and the ppem is HarfBuzz's own `hb_gpu_ppem` rather than
+* `1.0 / max (fwidth (v_texcoord).xy)` — this file's render coordinates are FONT UNITS, so the
+* reciprocal of their derivative is pixels per font unit and would put the `smoothstep (8, 48)`
+* ramp a factor of `upem` off. `hb_gpu_ppem` folds the glyph's own scale in and is what
+* `hb_gpu_spread_tap` above already agrees with.
+*
+* THE OUTLINE IS A MAX OF COVERAGE TAPS, BECAUSE THERE IS NO DISTANCE FIELD TO OFFSET. HarfBuzz's
+* entire public GLSL surface is `hb_gpu_draw` (coverage), `hb_gpu_ppem` and `hb_gpu_stem_darken` —
+* there is no signed distance anywhere in the format, so "dilate by r" cannot be a threshold shift
+* and has to be "is any point within r of this one inside the glyph", sampled. See
+* {@link HbGpuRenderer.setSpread} for what that costs and where it differs from a real stroke.
+*
+* EXPORTED SO THE TAP BUDGET CAN BE ASSERTED WITHOUT A GPU. `spreadBudget.test.ts` reads the
+* interpolated {@link HB_GPU_SPREAD_MAX_TAPS} back out of this text; a compiled shader is the one
+* place the constant has to be right, and the pixel suite that compiles it is gated on a display.
+*/
+const BATCHED_FRAGMENT_MAIN = `
+uniform float u_gamma;       /* exponent on the final coverage; 1.0 is off */
+uniform float u_stemDarken;  /* > 0 runs hb_gpu_stem_darken; 0 is off */
+
+in vec2 v_texcoord;
+flat in uint v_glyphLoc;
+flat in float v_spreadEm;
+flat in float v_spreadPx;
+flat in vec4 v_color;
+
+out vec4 fragColor;
+
+const float HB_GPU_SPREAD_TAU = 6.2831853;
+/* Hard ceilings so the loop is bounded at compile time. One tap per iteration, so
+ * HB_GPU_SPREAD_MAX_TAPS + the centre tap is the worst case, and it is only reached by a fragment
+ * that is neither solid ink nor near any. See the TS constant of the same name. */
+const int HB_GPU_SPREAD_MAX_RINGS = 4;
+const int HB_GPU_SPREAD_MAX_TAPS = 64;
+/* "Already saturated": no tap can raise this, so stop. Not 1.0, because the coverage estimator
+ * lands a hair under it on a deep-interior fragment and an exact test would never fire. */
+const float HB_GPU_SPREAD_SOLID = 0.999;
+
+/*
+ * WHERE A TAP STOPS MEANING "how much ink is at this offset" AND STARTS MEANING "is this fragment
+ * inside the dilated silhouette". The knee of a smoothstep, and the whole of the fix below.
+ *
+ * NO BACKTICKS ANYWHERE IN THIS COMMENT, and that is not a style note: this whole string is a JS
+ * template literal, so one backtick ends the shader mid-sentence and the package fails to PARSE.
+ *
+ * THE BUG IT REMOVES. A dilated shape is the union of a disk of radius r swept along the outline:
+ * a BINARY shape, whose only partial coverage is at its own boundary. A max of raw coverage taps
+ * cannot produce that, because a max cannot exceed the largest coverage near the fragment — and at
+ * ppem 14 a Han stroke is thinner than a pixel, so its coverage PEAKS at 0.42 and the whole
+ * silhouette came out a translucent mottle at 0.62 of the ideal's ink.
+ *
+ * THE RANGE IS 0 TO 0.5, AND "A TAP ABOVE HALF COVERAGE IS INSIDE" IS THE RULE THAT FAILS. That is
+ * the obvious reading and it makes this case measurably WORSE, which is why the knee is a swept
+ * number rather than an argued one. Half of a PIXEL is not half of a sub-pixel STROKE: at ppem 14
+ * the fixture's peak coverage is 0.42, so a knee centred on 0.5 sits above anything the glyph can
+ * reach and ERASES the outline. What 0.5 is the right value for is the top of the range — a pixel
+ * centred exactly ON the outline reads 0.5, so "as covered as a pixel on the boundary" is the point
+ * at which a tap is fully inside, and everything below it ramps.
+ *
+ * SWEPT ON THE RTX 2060 THROUGH ANGLE, both fixtures, against 8x grown references. Low-ppem is
+ * 中 at 14 px per em rotated 10 degrees, spread 3 (SHALLOW COVERAGE); thin is a full stop at 96 px
+ * per em, spread 12 (SPARSE COVERING — no 64-tap set tiles a disk of that radius; the sweep was run
+ * when those taps were four rings of 16, and the rim column moved again when they were resplit).
+ *
+ *   knee          low rim rms   low ink ratio   low interior short   thin rim rms   thin ink ratio
+ *   none            77.89           0.622            38.5%              80.90           0.965
+ *   0.35 - 0.65    128.57           0.574            (worse still)     102.52           0.966
+ *   0.25 - 0.75    112.35           0.604             ---               99.72           0.965
+ *   0.20 - 0.50     76.87           0.870             ---               94.27           0.974
+ *   0.15 - 0.45     73.85           0.968             ---               90.15           0.978
+ *   0.10 - 0.40     84.75           1.037             ---               85.82           0.985
+ *   0.05 - 0.45     79.40           1.011             4.1%              82.16           0.986
+ *   0.05 - 0.50     72.64           0.968             7.4%              82.81           0.983
+ *   0.00 - 0.45     83.29           1.026             3.3%              78.86           0.990
+ *   0.00 - 0.55     69.73           0.947             9.3%              79.96           0.984
+ *   0.00 - 0.50     75.66           0.988             6.1%              79.10           0.987   <-
+ *
+ * The two upper rows are the "roughly half" hypothesis and both are worse than shipping nothing.
+ * 0 - 0.5 is the only row that improves EVERY column at once, and it is also the one with a
+ * sentence behind it rather than a fit.
+ *
+ * WHAT IT COSTS AT LARGE PPEM. A well-resolved glyph's tap coverage IS the area, so a tap sitting
+ * exactly on the outline reads 0.5 — and 0.5 is also the ideal answer at the dilated boundary,
+ * where this maps it to 1. So the boundary moves outward by a fraction of a pixel: measured, the
+ * 96 px per em ink box grows 5 px on one side for a spread of 4 instead of 4. Real, inside the
+ * fixtures' SPREAD_TOLERANCE_PX, and the price of an interior that is no longer translucent.
+ *
+ * PER TAP RATHER THAN ON THE MAX, AND NOT FOR THE REASON IT LOOKS LIKE. smoothstep is MONOTONE, so
+ * it commutes with max and the two placements give the same silhouette — measured, not reasoned:
+ * moving it after the loop reads ink ratio 0.989 against 0.988 and the same rim RMS to two decimal
+ * places. What the placement actually buys is the two things a monotone identity does not cover.
+ * First, the FILL IS THE FLOOR: cov enters the loop as hb_gpu_draw's own coverage and is never
+ * sharpened, so a dilated run stays a strict SUPERSET of the same run at spread 0 — sharpening the
+ * max would put the fill through the knee too, and smoothstep(0, 0.5, x) is BELOW x for x under
+ * ~0.08, so a faint fill pixel would come back dimmer than it was drawn. Second, the early-out
+ * below tests cov INSIDE the loop, and only a per-tap value can raise it early.
+ *
+ * IT DOES NOT MAKE THE EARLY-OUT FIRE AT 14 px, WHICH THE ROUND EXPECTED IT TO. A tap saturates to
+ * exactly 1 only once its raw coverage reaches HB_GPU_SPREAD_INSIDE_HIGH, and at ppem 14 the
+ * fixture's peak raw coverage is 0.42, which sharpens to 0.931 — still under
+ * HB_GPU_SPREAD_SOLID. So a fragment at that size still walks the whole tap set, and the frame-cost
+ * side effect that was predicted here IS NOT THERE. Above ppem 16 taps reached 1 before this change
+ * as well, so nothing moved there either. Lowering HB_GPU_SPREAD_SOLID would collect it, and is
+ * deliberately not done here: it is a cost decision with its own pixels to grade, on a rung where
+ * the tap budget is a device ceiling.
+ */
+const float HB_GPU_SPREAD_INSIDE_LOW = 0.0;
+const float HB_GPU_SPREAD_INSIDE_HIGH = 0.5;
+
+/*
+ * One coverage tap, WITH NO DERIVATIVE IN IT — which is the whole reason this exists.
+ *
+ * It is _hb_gpu_slug (hb-gpu-fragment.glsl, 14.4.0) with ppem lifted into a parameter. The
+ * library's own _hb_gpu_slug advertises itself as callable "from non-uniform control flow", and
+ * for GLSL it is not: it calls hb_gpu_ppem, which calls fwidth. The disk below has a per-fragment
+ * early-out, so every tap after that point IS non-uniform control flow, and a fwidth there is
+ * undefined by GLSL ES 3.00.
+ *
+ * MIRRORED RATHER THAN AVOIDED so an outline tap and a fill fragment agree. Lifting ppem is exact
+ * rather than an approximation: it is fwidth(v_texcoord) and the glyph's own scale, and fwidth of an
+ * interpolated varying is constant across an affine quad, so its value at a tap equals its value at
+ * the centre.
+ *
+ * THE MSAA HALF IS SWITCHABLE AND THE DEFAULT IS OFF — see
+ * {@link HbGpuRendererOptions.spreadTapMsaa}, which carries the measurement. Note the macro is
+ * HB_GPU_SPREAD_TAP_NO_MSAA and NOT the library's HB_GPU_NO_MSAA: that one guards _hb_gpu_slug,
+ * i.e. the FILL, which this trade must not touch.
+ *
+ * The vendored wasm is digest-pinned (vendor/VENDOR.md, test/vendor.test.ts), so the source this
+ * mirrors cannot move without a deliberate vendor bump.
+ */
+float hb_gpu_spread_tap (vec2 rc, vec2 pixelsPerEm, float ppem, uint glyphLoc_)
+{
+  float c = _hb_gpu_slug_single (rc, pixelsPerEm, glyphLoc_);
+#ifndef HB_GPU_SPREAD_TAP_NO_MSAA
+  if (ppem < 16.0)
+  {
+    vec2 emsPerPixel = 1.0 / pixelsPerEm;
+    vec2 d = emsPerPixel * (1.0 / 3.0);
+    float msaa = 0.25 *
+      (_hb_gpu_slug_single (rc + vec2 (-d.x, -d.y), pixelsPerEm, glyphLoc_) +
+       _hb_gpu_slug_single (rc + vec2 ( d.x, -d.y), pixelsPerEm, glyphLoc_) +
+       _hb_gpu_slug_single (rc + vec2 (-d.x,  d.y), pixelsPerEm, glyphLoc_) +
+       _hb_gpu_slug_single (rc + vec2 ( d.x,  d.y), pixelsPerEm, glyphLoc_));
+    c = mix (c, msaa, smoothstep (16.0, 8.0, ppem));
+  }
+#endif
+  return c;
+}
+
+void main ()
+{
+  float cov = hb_gpu_draw (v_texcoord, v_glyphLoc);
+
+  /* PER-PRIMITIVE CONTROL FLOW: the two derivative-taking calls inside see flat run state, so all
+   * fragments of one glyph primitive take the same branch. v_spreadPx and v_spreadEm are flat
+   * (constant over a primitive, which is what a derivative
+   * quad belongs to), so it is uniform by construction rather than by luck. v_spreadEm is also a
+   * genuine guard: a NaN or zero a_emPerPos fails it and takes the single-tap path. */
+  if (v_spreadPx > 0.0 && v_spreadEm > 0.0)
+  {
+    vec2 pixelsPerEm = 1.0 / fwidth (v_texcoord);
+    float ppem = hb_gpu_ppem (v_texcoord, v_glyphLoc);
+    /* The spread in DEVICE pixels — fwidth is a screen-space derivative, so this already carries
+     * the model scale and the device-pixel ratio. It only ever picks tap counts; the tap OFFSETS
+     * are in em units and are exact. */
+    float radiusPx = v_spreadEm * max (pixelsPerEm.x, pixelsPerEm.y);
+
+    /* CONCENTRIC RINGS, NOT ONE, and that is not a refinement. A dilated fragment is covered iff
+     * SOME offset within the disk lands on ink; taps on a single ring of radius r can all overshoot
+     * a feature narrower than 2r, which punches holes through the outline exactly where a glyph is
+     * thin — a comma, a hairline serif, a full stop. Ring spacing is held near 2/3 px, so the RADIAL
+     * half of the covering is sub-pixel out to the clamp at HB_GPU_SPREAD_MAX_RINGS.
+     *
+     * THE RADII STAY EQUALLY SPACED, which is worth saying because equal AREA is the obvious
+     * alternative and it is worse here. Pushing the rings outward concentrates them where the taps
+     * are already densest, and combined with the budget split below it both doubles the outward bias
+     * of the whole tap set and halves the radial margin the small-feature case relies on — the one
+     * where a full stop smaller than the tap radius has to be found by an INNER ring. */
+    int rings = clamp (int (ceil (radiusPx * 1.5)), 1, HB_GPU_SPREAD_MAX_RINGS);
+    /* 1 + 2 + ... + rings, the denominator of the budget split below. */
+    int denom = rings * (rings + 1) / 2;
+
+    /* ONE FLAT LOOP OVER THE WHOLE BUDGET, AND THE OUTER RING GETS MOST OF IT.
+     *
+     * Every ring used to be capped at the same number of steps, which sounds neutral and is not: a
+     * ring's taps are spread over a circumference proportional to its radius, so an equal share puts
+     * the WIDEST arc gaps on the outermost ring — the only one that decides where the dilated
+     * boundary lands. At radius 12 that was 4.71 px of arc between the taps that draw the edge,
+     * against 1.18 px on ring 1, and the boundary followed the tap count: measured against a Godot
+     * 4.5.1 golden, 0.3099 px of wobble at exactly 16 cycles per revolution where the engine has
+     * 0.0164.
+     *
+     * So the budget is split in proportion to ring RADIUS, i.e. to circumference: ring k of rings
+     * may spend (MAX_TAPS * k + denom/2) / denom taps, which at four rings is 6 / 13 / 19 / 26 and
+     * sums to exactly MAX_TAPS. It sums to exactly MAX_TAPS at one, two and three rings as well
+     * (64; 21 + 43; 11 + 21 + 32), so the flat bound is never the thing that truncates a ring — it
+     * is a hedge against a driver that insists on unrolling, not a second policy. At radius 12 the
+     * outer arc is then 2.90 px rather than 4.71.
+     *
+     * The lower clamp of 6 steps is what keeps a SMALL radius honest, and it is the reason the cap
+     * enters as max (cap, 6) rather than as cap: ring 1's share at four rings is exactly 6, and a
+     * hexagon is the coarsest ring that still surrounds its centre.
+     *
+     * ONE TAP PER ITERATION, so HB_GPU_SPREAD_MAX_TAPS is simultaneously the loop bound and the
+     * fragment's worst-case cost — the two used to be 4 x 16 and 65 and had to be reasoned about
+     * separately. Dynamic bounds and breaks are legal ESSL 3.00; the GLSL ES 1.00 Appendix A
+     * restriction that forced the nested constant shape does not apply to version 300 es. */
+    int ring = 0;
+    int step = 0;
+    int steps = 0;
+    float ringEm = 0.0;
+    float phase = 0.0;
+    for (int i = 0; i < HB_GPU_SPREAD_MAX_TAPS; i++)
+    {
+      /* THE INTERIOR EARLY-OUT: a fragment already covered by its own centre tap is trivially
+       * within r of ink, and interior fragments are most of a glyph. */
+      if (cov >= HB_GPU_SPREAD_SOLID) break;
+      if (step >= steps)
+      {
+        ring += 1;
+        /* The other exit: the rings this radius actually asked for are done. */
+        if (ring > rings) break;
+        float t = float (ring) / float (rings);
+        ringEm = v_spreadEm * t;
+        int cap = (HB_GPU_SPREAD_MAX_TAPS * ring + denom / 2) / denom;
+        steps = clamp (int (ceil (HB_GPU_SPREAD_TAU * radiusPx * t)), 6, max (cap, 6));
+        /* THE GOLDEN ANGLE, so no two rings put their taps on the same radii — which would leave
+         * wedge-shaped gaps between the rings rather than a covering. A fixed fraction of a step
+         * would do that for one pair of ring counts and line up for another; 137.5 degrees per ring
+         * is the rotation with no small-integer commensurability with any of them. */
+        phase = 2.39996 * float (ring);
+        step = 0;
+      }
+      float angle = phase + HB_GPU_SPREAD_TAU * float (step) / float (steps);
+      vec2 at = v_texcoord + ringEm * vec2 (cos (angle), sin (angle));
+      /* MAX, NOT A SUM, AND THE MAX IS WHY THIS IS IN THE SHADER. The alternative a caller could
+       * build without it — draw the run N times at N offsets — composites N times, so a
+       * translucent outline is N overlapping translucent copies and reads far darker than one
+       * stroke. One fragment, one coverage, one blend.
+       *
+       * SHARPENED BEFORE THE MAX, not after: the max is over a set of INSIDE tests, and the union
+       * of disks it approximates is a binary shape. Sharpening the max instead would sharpen a
+       * number that had already been flattened to the peak coverage nearby, which is the value
+       * that is wrong. See HB_GPU_SPREAD_INSIDE_LOW. */
+      cov = max (cov, smoothstep (HB_GPU_SPREAD_INSIDE_LOW,
+                                  HB_GPU_SPREAD_INSIDE_HIGH,
+                                  hb_gpu_spread_tap (at, pixelsPerEm, ppem, v_glyphLoc)));
+      step += 1;
+    }
+  }
+
+  /* CONTRAST, ON THE FINAL COVERAGE — and STEM DARKENING ONLY WHEN THE DILATION DID NOT RUN.
+   *
+   * An outline's rim is NOT a coverage ramp with the same problem the fill's has, which is what
+   * this block assumed when it shipped. Stem darkening exists because a sub-pixel STEM lands at
+   * mid-grey under linear coverage where a browser puts it near the ink colour; the fix is an
+   * exponent that pushes the middle of the ramp toward the foreground. A dilated fragment's
+   * coverage is not that number. The taps above are an INSIDE test (HB_GPU_SPREAD_INSIDE_LOW
+   * sharpens each one before the max), so the dilated boundary is already very nearly binary — and
+   * the engine this mirrors applies no curve at all to its outline: Godot strokes the glyph and
+   * hands the result to FreeType's plain grayscale raster. Measured against that golden, the curve
+   * took a 14 px outline's rim from 0.662 px to 1.965 px of equivalent ramp, three times the width,
+   * where Godot's own is 0.851. That is a halo — fattening for dark ink, thinning for light — and
+   * it is the one thing in this shader that made an outline softer than the engine's.
+   *
+   * THE GATE IS THE DILATION BRANCH'S OWN CONDITION, CHARACTER FOR CHARACTER, so the two cannot
+   * disagree about which fragments dilated. A bare v_spreadPx > 0.0 would also strip the
+   * correction from a DEGENERATE run — one whose a_emPerPos is zero or NaN, which fails
+   * v_spreadEm > 0.0 and takes the single-tap path. Such a fragment is a fill in every way that
+   * reaches the framebuffer, and it should keep a fill's darkening rather than lose it to a uniform
+   * that ended up doing nothing.
+   *
+   * GAMMA IS NOT GATED. It is an explicit consumer knob, defaults to 1 (skipped entirely below),
+   * and is polarity- and size-blind by construction; a consumer that deliberately sets one is
+   * asking for a transfer curve on the text, and putting the fill and the outline of the same run
+   * on different curves would be a stranger thing than either choice.
+   *
+   * THE PPEM IS FETCHED IN UNIFORM CONTROL FLOW AND THE COVERAGE TEST IS NOT ALLOWED TO CONTAIN IT.
+   * hb_gpu_ppem calls fwidth, which GLSL ES 3.00 leaves undefined once the 2x2 derivative quad can
+   * disagree about whether to run it — and "0.0 < cov < 1.0" is precisely a per-fragment condition.
+   * u_stemDarken is uniform while v_spreadPx and v_spreadEm are flat, which is the same
+   * argument the dilation branch above makes for its own hb_gpu_ppem call; darken is that branch's
+   * predicate negated, so a quad coherent enough to run the dilation is exactly as coherent about
+   * skipping the darkening. Upstream's demo puts its fwidth inside the coverage test; that is a
+   * desktop-GLSL liberty this cannot take.
+   */
+  bool fillPass = !(v_spreadPx > 0.0 && v_spreadEm > 0.0);
+  bool darken = u_stemDarken > 0.0 && fillPass;
+
+  float darkenPpem = 0.0;
+  if (darken)
+    darkenPpem = hb_gpu_ppem (v_texcoord, v_glyphLoc);
+
+  /* EDGE ONLY, which is upstream's guard and is not merely an optimisation here. Both corrections
+   * fix 0 and 1, so the interior and the background cannot move whatever the exponents are — but
+   * pow (0.0, y) is UNDEFINED for y <= 0 in GLSL ES 3.00, and u_gamma is a number a consumer chose.
+   * Skipping cov == 0.0 is what makes a hostile gamma a picture that is wrong rather than a NaN
+   * alpha over the whole quad. No derivative is taken inside, so a non-uniform branch is legal. */
+  if (cov > 0.0 && cov < 1.0)
+  {
+    float adj = cov;
+    if (darken)
+    {
+      /* v_color is STRAIGHT, so this IS upstream's dot (c.rgb, 1/3) / c.a with the divide already
+       * done. A flat 1/3 rather than a Rec.709 luma on purpose: hb_gpu_stem_darken's exponent
+       * curve is calibrated against HarfBuzz's own definition of "brightness", and weighting the
+       * channels differently would silently retune somebody else's constants. */
+      adj = hb_gpu_stem_darken (adj, dot (v_color.rgb, vec3 (1.0 / 3.0)), darkenPpem);
+    }
+    if (u_gamma != 1.0)
+      adj = pow (adj, u_gamma);
+    cov = adj;
+  }
+
+  float a = v_color.a * cov;
+  fragColor = vec4 (v_color.rgb * a, a);
+}
+`;
+const FRAGMENT_MAIN = `
+uniform vec4 u_color;   /* STRAIGHT rgba; premultiplied exactly once, below */
+uniform float u_spreadPx;
+uniform float u_gamma;       /* exponent on the final coverage; 1.0 is off */
+uniform float u_stemDarken;  /* > 0 runs hb_gpu_stem_darken; 0 is off */
+
+in vec2 v_texcoord;
+flat in uint v_glyphLoc;
+flat in float v_spreadEm;
+
+out vec4 fragColor;
+
+const float HB_GPU_SPREAD_TAU = 6.2831853;
+/* Hard ceilings so the loop is bounded at compile time. One tap per iteration, so
+ * HB_GPU_SPREAD_MAX_TAPS + the centre tap is the worst case, and it is only reached by a fragment
+ * that is neither solid ink nor near any. See the TS constant of the same name. */
+const int HB_GPU_SPREAD_MAX_RINGS = 4;
+const int HB_GPU_SPREAD_MAX_TAPS = 64;
+/* "Already saturated": no tap can raise this, so stop. Not 1.0, because the coverage estimator
+ * lands a hair under it on a deep-interior fragment and an exact test would never fire. */
+const float HB_GPU_SPREAD_SOLID = 0.999;
+
+/*
+ * WHERE A TAP STOPS MEANING "how much ink is at this offset" AND STARTS MEANING "is this fragment
+ * inside the dilated silhouette". The knee of a smoothstep, and the whole of the fix below.
+ *
+ * NO BACKTICKS ANYWHERE IN THIS COMMENT, and that is not a style note: this whole string is a JS
+ * template literal, so one backtick ends the shader mid-sentence and the package fails to PARSE.
+ *
+ * THE BUG IT REMOVES. A dilated shape is the union of a disk of radius r swept along the outline:
+ * a BINARY shape, whose only partial coverage is at its own boundary. A max of raw coverage taps
+ * cannot produce that, because a max cannot exceed the largest coverage near the fragment — and at
+ * ppem 14 a Han stroke is thinner than a pixel, so its coverage PEAKS at 0.42 and the whole
+ * silhouette came out a translucent mottle at 0.62 of the ideal's ink.
+ *
+ * THE RANGE IS 0 TO 0.5, AND "A TAP ABOVE HALF COVERAGE IS INSIDE" IS THE RULE THAT FAILS. That is
+ * the obvious reading and it makes this case measurably WORSE, which is why the knee is a swept
+ * number rather than an argued one. Half of a PIXEL is not half of a sub-pixel STROKE: at ppem 14
+ * the fixture's peak coverage is 0.42, so a knee centred on 0.5 sits above anything the glyph can
+ * reach and ERASES the outline. What 0.5 is the right value for is the top of the range — a pixel
+ * centred exactly ON the outline reads 0.5, so "as covered as a pixel on the boundary" is the point
+ * at which a tap is fully inside, and everything below it ramps.
+ *
+ * SWEPT ON THE RTX 2060 THROUGH ANGLE, both fixtures, against 8x grown references. Low-ppem is
+ * 中 at 14 px per em rotated 10 degrees, spread 3 (SHALLOW COVERAGE); thin is a full stop at 96 px
+ * per em, spread 12 (SPARSE COVERING — no 64-tap set tiles a disk of that radius; the sweep was run
+ * when those taps were four rings of 16, and the rim column moved again when they were resplit).
+ *
+ *   knee          low rim rms   low ink ratio   low interior short   thin rim rms   thin ink ratio
+ *   none            77.89           0.622            38.5%              80.90           0.965
+ *   0.35 - 0.65    128.57           0.574            (worse still)     102.52           0.966
+ *   0.25 - 0.75    112.35           0.604             ---               99.72           0.965
+ *   0.20 - 0.50     76.87           0.870             ---               94.27           0.974
+ *   0.15 - 0.45     73.85           0.968             ---               90.15           0.978
+ *   0.10 - 0.40     84.75           1.037             ---               85.82           0.985
+ *   0.05 - 0.45     79.40           1.011             4.1%              82.16           0.986
+ *   0.05 - 0.50     72.64           0.968             7.4%              82.81           0.983
+ *   0.00 - 0.45     83.29           1.026             3.3%              78.86           0.990
+ *   0.00 - 0.55     69.73           0.947             9.3%              79.96           0.984
+ *   0.00 - 0.50     75.66           0.988             6.1%              79.10           0.987   <-
+ *
+ * The two upper rows are the "roughly half" hypothesis and both are worse than shipping nothing.
+ * 0 - 0.5 is the only row that improves EVERY column at once, and it is also the one with a
+ * sentence behind it rather than a fit.
+ *
+ * WHAT IT COSTS AT LARGE PPEM. A well-resolved glyph's tap coverage IS the area, so a tap sitting
+ * exactly on the outline reads 0.5 — and 0.5 is also the ideal answer at the dilated boundary,
+ * where this maps it to 1. So the boundary moves outward by a fraction of a pixel: measured, the
+ * 96 px per em ink box grows 5 px on one side for a spread of 4 instead of 4. Real, inside the
+ * fixtures' SPREAD_TOLERANCE_PX, and the price of an interior that is no longer translucent.
+ *
+ * PER TAP RATHER THAN ON THE MAX, AND NOT FOR THE REASON IT LOOKS LIKE. smoothstep is MONOTONE, so
+ * it commutes with max and the two placements give the same silhouette — measured, not reasoned:
+ * moving it after the loop reads ink ratio 0.989 against 0.988 and the same rim RMS to two decimal
+ * places. What the placement actually buys is the two things a monotone identity does not cover.
+ * First, the FILL IS THE FLOOR: cov enters the loop as hb_gpu_draw's own coverage and is never
+ * sharpened, so a dilated run stays a strict SUPERSET of the same run at spread 0 — sharpening the
+ * max would put the fill through the knee too, and smoothstep(0, 0.5, x) is BELOW x for x under
+ * ~0.08, so a faint fill pixel would come back dimmer than it was drawn. Second, the early-out
+ * below tests cov INSIDE the loop, and only a per-tap value can raise it early.
+ *
+ * IT DOES NOT MAKE THE EARLY-OUT FIRE AT 14 px, WHICH THE ROUND EXPECTED IT TO. A tap saturates to
+ * exactly 1 only once its raw coverage reaches HB_GPU_SPREAD_INSIDE_HIGH, and at ppem 14 the
+ * fixture's peak raw coverage is 0.42, which sharpens to 0.931 — still under
+ * HB_GPU_SPREAD_SOLID. So a fragment at that size still walks the whole tap set, and the frame-cost
+ * side effect that was predicted here IS NOT THERE. Above ppem 16 taps reached 1 before this change
+ * as well, so nothing moved there either. Lowering HB_GPU_SPREAD_SOLID would collect it, and is
+ * deliberately not done here: it is a cost decision with its own pixels to grade, on a rung where
+ * the tap budget is a device ceiling.
+ */
+const float HB_GPU_SPREAD_INSIDE_LOW = 0.0;
+const float HB_GPU_SPREAD_INSIDE_HIGH = 0.5;
+
+/*
+ * One coverage tap, WITH NO DERIVATIVE IN IT — which is the whole reason this exists.
+ *
+ * It is _hb_gpu_slug (hb-gpu-fragment.glsl, 14.4.0) with ppem lifted into a parameter. The
+ * library's own _hb_gpu_slug advertises itself as callable "from non-uniform control flow", and
+ * for GLSL it is not: it calls hb_gpu_ppem, which calls fwidth. The disk below has a per-fragment
+ * early-out, so every tap after that point IS non-uniform control flow, and a fwidth there is
+ * undefined by GLSL ES 3.00.
+ *
+ * MIRRORED RATHER THAN AVOIDED so an outline tap and a fill fragment agree. Lifting ppem is exact
+ * rather than an approximation: it is fwidth(v_texcoord) and the glyph's own scale, and fwidth of an
+ * interpolated varying is constant across an affine quad, so its value at a tap equals its value at
+ * the centre.
+ *
+ * THE MSAA HALF IS SWITCHABLE AND THE DEFAULT IS OFF — see
+ * {@link HbGpuRendererOptions.spreadTapMsaa}, which carries the measurement. Note the macro is
+ * HB_GPU_SPREAD_TAP_NO_MSAA and NOT the library's HB_GPU_NO_MSAA: that one guards _hb_gpu_slug,
+ * i.e. the FILL, which this trade must not touch.
+ *
+ * The vendored wasm is digest-pinned (vendor/VENDOR.md, test/vendor.test.ts), so the source this
+ * mirrors cannot move without a deliberate vendor bump.
+ */
+float hb_gpu_spread_tap (vec2 rc, vec2 pixelsPerEm, float ppem, uint glyphLoc_)
+{
+  float c = _hb_gpu_slug_single (rc, pixelsPerEm, glyphLoc_);
+#ifndef HB_GPU_SPREAD_TAP_NO_MSAA
+  if (ppem < 16.0)
+  {
+    vec2 emsPerPixel = 1.0 / pixelsPerEm;
+    vec2 d = emsPerPixel * (1.0 / 3.0);
+    float msaa = 0.25 *
+      (_hb_gpu_slug_single (rc + vec2 (-d.x, -d.y), pixelsPerEm, glyphLoc_) +
+       _hb_gpu_slug_single (rc + vec2 ( d.x, -d.y), pixelsPerEm, glyphLoc_) +
+       _hb_gpu_slug_single (rc + vec2 (-d.x,  d.y), pixelsPerEm, glyphLoc_) +
+       _hb_gpu_slug_single (rc + vec2 ( d.x,  d.y), pixelsPerEm, glyphLoc_));
+    c = mix (c, msaa, smoothstep (16.0, 8.0, ppem));
+  }
+#endif
+  return c;
+}
+
+void main ()
+{
+  float cov = hb_gpu_draw (v_texcoord, v_glyphLoc);
+
+  /* UNIFORM CONTROL FLOW, AND IT HAS TO BE: the two derivative-taking calls inside are legal only
+   * because every fragment of a 2x2 derivative quad takes this branch together. u_spreadPx is a
+   * real uniform and v_spreadEm is flat (constant over a primitive, which is what a derivative
+   * quad belongs to), so it is uniform by construction rather than by luck. v_spreadEm is also a
+   * genuine guard: a NaN or zero a_emPerPos fails it and takes the single-tap path. */
+  if (u_spreadPx > 0.0 && v_spreadEm > 0.0)
+  {
+    vec2 pixelsPerEm = 1.0 / fwidth (v_texcoord);
+    float ppem = hb_gpu_ppem (v_texcoord, v_glyphLoc);
+    /* The spread in DEVICE pixels — fwidth is a screen-space derivative, so this already carries
+     * the model scale and the device-pixel ratio. It only ever picks tap counts; the tap OFFSETS
+     * are in em units and are exact. */
+    float radiusPx = v_spreadEm * max (pixelsPerEm.x, pixelsPerEm.y);
+
+    /* CONCENTRIC RINGS, NOT ONE, and that is not a refinement. A dilated fragment is covered iff
+     * SOME offset within the disk lands on ink; taps on a single ring of radius r can all overshoot
+     * a feature narrower than 2r, which punches holes through the outline exactly where a glyph is
+     * thin — a comma, a hairline serif, a full stop. Ring spacing is held near 2/3 px, so the RADIAL
+     * half of the covering is sub-pixel out to the clamp at HB_GPU_SPREAD_MAX_RINGS.
+     *
+     * THE RADII STAY EQUALLY SPACED, which is worth saying because equal AREA is the obvious
+     * alternative and it is worse here. Pushing the rings outward concentrates them where the taps
+     * are already densest, and combined with the budget split below it both doubles the outward bias
+     * of the whole tap set and halves the radial margin the small-feature case relies on — the one
+     * where a full stop smaller than the tap radius has to be found by an INNER ring. */
+    int rings = clamp (int (ceil (radiusPx * 1.5)), 1, HB_GPU_SPREAD_MAX_RINGS);
+    /* 1 + 2 + ... + rings, the denominator of the budget split below. */
+    int denom = rings * (rings + 1) / 2;
+
+    /* ONE FLAT LOOP OVER THE WHOLE BUDGET, AND THE OUTER RING GETS MOST OF IT.
+     *
+     * Every ring used to be capped at the same number of steps, which sounds neutral and is not: a
+     * ring's taps are spread over a circumference proportional to its radius, so an equal share puts
+     * the WIDEST arc gaps on the outermost ring — the only one that decides where the dilated
+     * boundary lands. At radius 12 that was 4.71 px of arc between the taps that draw the edge,
+     * against 1.18 px on ring 1, and the boundary followed the tap count: measured against a Godot
+     * 4.5.1 golden, 0.3099 px of wobble at exactly 16 cycles per revolution where the engine has
+     * 0.0164.
+     *
+     * So the budget is split in proportion to ring RADIUS, i.e. to circumference: ring k of rings
+     * may spend (MAX_TAPS * k + denom/2) / denom taps, which at four rings is 6 / 13 / 19 / 26 and
+     * sums to exactly MAX_TAPS. It sums to exactly MAX_TAPS at one, two and three rings as well
+     * (64; 21 + 43; 11 + 21 + 32), so the flat bound is never the thing that truncates a ring — it
+     * is a hedge against a driver that insists on unrolling, not a second policy. At radius 12 the
+     * outer arc is then 2.90 px rather than 4.71.
+     *
+     * The lower clamp of 6 steps is what keeps a SMALL radius honest, and it is the reason the cap
+     * enters as max (cap, 6) rather than as cap: ring 1's share at four rings is exactly 6, and a
+     * hexagon is the coarsest ring that still surrounds its centre.
+     *
+     * ONE TAP PER ITERATION, so HB_GPU_SPREAD_MAX_TAPS is simultaneously the loop bound and the
+     * fragment's worst-case cost — the two used to be 4 x 16 and 65 and had to be reasoned about
+     * separately. Dynamic bounds and breaks are legal ESSL 3.00; the GLSL ES 1.00 Appendix A
+     * restriction that forced the nested constant shape does not apply to version 300 es. */
+    int ring = 0;
+    int step = 0;
+    int steps = 0;
+    float ringEm = 0.0;
+    float phase = 0.0;
+    for (int i = 0; i < HB_GPU_SPREAD_MAX_TAPS; i++)
+    {
+      /* THE INTERIOR EARLY-OUT: a fragment already covered by its own centre tap is trivially
+       * within r of ink, and interior fragments are most of a glyph. */
+      if (cov >= HB_GPU_SPREAD_SOLID) break;
+      if (step >= steps)
+      {
+        ring += 1;
+        /* The other exit: the rings this radius actually asked for are done. */
+        if (ring > rings) break;
+        float t = float (ring) / float (rings);
+        ringEm = v_spreadEm * t;
+        int cap = (HB_GPU_SPREAD_MAX_TAPS * ring + denom / 2) / denom;
+        steps = clamp (int (ceil (HB_GPU_SPREAD_TAU * radiusPx * t)), 6, max (cap, 6));
+        /* THE GOLDEN ANGLE, so no two rings put their taps on the same radii — which would leave
+         * wedge-shaped gaps between the rings rather than a covering. A fixed fraction of a step
+         * would do that for one pair of ring counts and line up for another; 137.5 degrees per ring
+         * is the rotation with no small-integer commensurability with any of them. */
+        phase = 2.39996 * float (ring);
+        step = 0;
+      }
+      float angle = phase + HB_GPU_SPREAD_TAU * float (step) / float (steps);
+      vec2 at = v_texcoord + ringEm * vec2 (cos (angle), sin (angle));
+      /* MAX, NOT A SUM, AND THE MAX IS WHY THIS IS IN THE SHADER. The alternative a caller could
+       * build without it — draw the run N times at N offsets — composites N times, so a
+       * translucent outline is N overlapping translucent copies and reads far darker than one
+       * stroke. One fragment, one coverage, one blend.
+       *
+       * SHARPENED BEFORE THE MAX, not after: the max is over a set of INSIDE tests, and the union
+       * of disks it approximates is a binary shape. Sharpening the max instead would sharpen a
+       * number that had already been flattened to the peak coverage nearby, which is the value
+       * that is wrong. See HB_GPU_SPREAD_INSIDE_LOW. */
+      cov = max (cov, smoothstep (HB_GPU_SPREAD_INSIDE_LOW,
+                                  HB_GPU_SPREAD_INSIDE_HIGH,
+                                  hb_gpu_spread_tap (at, pixelsPerEm, ppem, v_glyphLoc)));
+      step += 1;
+    }
+  }
+
+  /* CONTRAST, ON THE FINAL COVERAGE — and STEM DARKENING ONLY WHEN THE DILATION DID NOT RUN.
+   *
+   * An outline's rim is NOT a coverage ramp with the same problem the fill's has, which is what
+   * this block assumed when it shipped. Stem darkening exists because a sub-pixel STEM lands at
+   * mid-grey under linear coverage where a browser puts it near the ink colour; the fix is an
+   * exponent that pushes the middle of the ramp toward the foreground. A dilated fragment's
+   * coverage is not that number. The taps above are an INSIDE test (HB_GPU_SPREAD_INSIDE_LOW
+   * sharpens each one before the max), so the dilated boundary is already very nearly binary — and
+   * the engine this mirrors applies no curve at all to its outline: Godot strokes the glyph and
+   * hands the result to FreeType's plain grayscale raster. Measured against that golden, the curve
+   * took a 14 px outline's rim from 0.662 px to 1.965 px of equivalent ramp, three times the width,
+   * where Godot's own is 0.851. That is a halo — fattening for dark ink, thinning for light — and
+   * it is the one thing in this shader that made an outline softer than the engine's.
+   *
+   * THE GATE IS THE DILATION BRANCH'S OWN CONDITION, CHARACTER FOR CHARACTER, so the two cannot
+   * disagree about which fragments dilated. A bare u_spreadPx > 0.0 would also strip the
+   * correction from a DEGENERATE run — one whose a_emPerPos is zero or NaN, which fails
+   * v_spreadEm > 0.0 and takes the single-tap path. Such a fragment is a fill in every way that
+   * reaches the framebuffer, and it should keep a fill's darkening rather than lose it to a uniform
+   * that ended up doing nothing.
+   *
+   * GAMMA IS NOT GATED. It is an explicit consumer knob, defaults to 1 (skipped entirely below),
+   * and is polarity- and size-blind by construction; a consumer that deliberately sets one is
+   * asking for a transfer curve on the text, and putting the fill and the outline of the same run
+   * on different curves would be a stranger thing than either choice.
+   *
+   * THE PPEM IS FETCHED IN UNIFORM CONTROL FLOW AND THE COVERAGE TEST IS NOT ALLOWED TO CONTAIN IT.
+   * hb_gpu_ppem calls fwidth, which GLSL ES 3.00 leaves undefined once the 2x2 derivative quad can
+   * disagree about whether to run it — and "0.0 < cov < 1.0" is precisely a per-fragment condition.
+   * u_stemDarken and u_spreadPx are real uniforms and v_spreadEm is flat, which is the same
+   * argument the dilation branch above makes for its own hb_gpu_ppem call; darken is that branch's
+   * predicate negated, so a quad coherent enough to run the dilation is exactly as coherent about
+   * skipping the darkening. Upstream's demo puts its fwidth inside the coverage test; that is a
+   * desktop-GLSL liberty this cannot take.
+   */
+  bool fillPass = !(u_spreadPx > 0.0 && v_spreadEm > 0.0);
+  bool darken = u_stemDarken > 0.0 && fillPass;
+
+  float darkenPpem = 0.0;
+  if (darken)
+    darkenPpem = hb_gpu_ppem (v_texcoord, v_glyphLoc);
+
+  /* EDGE ONLY, which is upstream's guard and is not merely an optimisation here. Both corrections
+   * fix 0 and 1, so the interior and the background cannot move whatever the exponents are — but
+   * pow (0.0, y) is UNDEFINED for y <= 0 in GLSL ES 3.00, and u_gamma is a number a consumer chose.
+   * Skipping cov == 0.0 is what makes a hostile gamma a picture that is wrong rather than a NaN
+   * alpha over the whole quad. No derivative is taken inside, so a non-uniform branch is legal. */
+  if (cov > 0.0 && cov < 1.0)
+  {
+    float adj = cov;
+    if (darken)
+    {
+      /* u_color is STRAIGHT, so this IS upstream's dot (c.rgb, 1/3) / c.a with the divide already
+       * done. A flat 1/3 rather than a Rec.709 luma on purpose: hb_gpu_stem_darken's exponent
+       * curve is calibrated against HarfBuzz's own definition of "brightness", and weighting the
+       * channels differently would silently retune somebody else's constants. */
+      adj = hb_gpu_stem_darken (adj, dot (u_color.rgb, vec3 (1.0 / 3.0)), darkenPpem);
+    }
+    if (u_gamma != 1.0)
+      adj = pow (adj, u_gamma);
+    cov = adj;
+  }
+
+  float a = u_color.a * cov;
+  fragColor = vec4 (u_color.rgb * a, a);
+}
+`;
+/** Stem darkening on, gamma neutral. What a renderer built without a `contrast` option gets. */
+const HB_GPU_CONTRAST_DEFAULT = Object.freeze({
+	gamma: 1,
+	stemDarkening: true
+});
+/**
+* No contrast curve at all: the fragment writes the coverage it computed.
+*
+* FOR MEASUREMENT ARMS, and they should say so where they pass it. A fidelity probe that grades an
+* arm against an 8x area-coverage reference is grading the RASTERIZER, and an arm carrying a
+* contrast curve scores the curve instead — `docs/text-rendering.md`'s distortion figures (0.196
+* Han at ppem 14, 0.017 at ppem 49) only mean what they say against raw coverage.
+*/
+const HB_GPU_CONTRAST_NONE = Object.freeze({
+	gamma: 1,
+	stemDarkening: false
+});
+/** A compiled shader, or the reason there is not one. Never a throw — see `createHbGpuRenderer`. */
+function compileShader(gl, type, source) {
+	const stage = type === gl.VERTEX_SHADER ? "vertex" : "fragment";
+	const shader = gl.createShader(type);
+	if (!shader) return {
+		reason: "gl-object",
+		message: `gl.createShader(${stage}) returned null — the context is lost or out of resources`
+	};
+	gl.shaderSource(shader, source);
+	gl.compileShader(shader);
+	if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
+		const log = gl.getShaderInfoLog(shader) || "(no log)";
+		gl.deleteShader(shader);
+		return {
+			reason: "shader-compile",
+			message: `${stage} shader failed to compile — ${log}`
+		};
+	}
+	return { shader };
+}
+/**
+* A WebGL2 renderer for hb-gpu blobs, in a context somebody else owns.
+*
+* `null`, NOT A THROW, for every construction failure — the idiom `createCanvasStage` already sets
+* in this repo, and the difference between a measurement arm and a shipped renderer. A consumer
+* that cannot have this one falls back to its DOM text path; a consumer that WANTS to be loud
+* passes `onError` and is told the reason, because a silently skipped renderer reports as a cheap
+* one.
+*
+* DESIGN SPACE IS DEVICE PIXELS, and not by preference: `u_viewport` is the framebuffer size and
+* `hb_gpu_dilate` uses it with the projection to work out how far half a screen pixel is in object
+* units. Any scale in the projection would make the dilation and the quad disagree, and a dilation
+* that is wrong by a fraction is a rim of clipped antialiasing around every glyph.
+*/
+let rendererIdentity = 0;
+/** Non-enumerable provenance survives a direct slot hand-off but deliberately not `{ ...slot }`. */
+const SLOT_OWNER = Symbol("hb-gpu-slot-owner");
+function createHbGpuRenderer(module, options) {
+	const rid = ++rendererIdentity;
+	const gl = options.gl;
+	const report = (reason, message) => {
+		options.onError?.({
+			reason,
+			message: `hb-gpu: ${message}`
+		});
+	};
+	const refuse = (reason, message) => {
+		report(reason, message);
+		return null;
+	};
+	if (gl.isContextLost()) return refuse("context-lost", "the context handed to createHbGpuRenderer is already lost — every object built now would be dead on arrival");
+	const maxTextureSize = Number(gl.getParameter(gl.MAX_TEXTURE_SIZE)) || 0;
+	if (maxTextureSize < MIN_ATLAS_WIDTH) return refuse("texture-size", `MAX_TEXTURE_SIZE is ${maxTextureSize}, below the ${MIN_ATLAS_WIDTH} this renderer needs (WebGL2 itself guarantees 2048) — the atlas cannot be built`);
+	const atlasWidth = Math.min(ATLAS_WIDTH, maxTextureSize);
+	if (atlasWidth !== 4096) report("atlas-clamped", `MAX_TEXTURE_SIZE is ${maxTextureSize}, so the atlas is ${atlasWidth} texels wide instead of ${ATLAS_WIDTH} — correct (the width is a uniform) but each blob now spans more rows and costs more texSubImage2D calls`);
+	const spreadTapMsaa = options.spreadTapMsaa ?? false;
+	const contrast = options.contrast ?? HB_GPU_CONTRAST_DEFAULT;
+	const perInstanceRunState = options.perInstanceRunState === true;
+	const instanceFloatsPerRecord = perInstanceRunState ? BATCHED_INSTANCE_FLOATS : LEGACY_INSTANCE_FLOATS;
+	const instanceBytes = instanceFloatsPerRecord * 4;
+	let contrastGamma = contrast.gamma;
+	if (!Number.isFinite(contrastGamma) || contrastGamma <= 0) {
+		report("degenerate-contrast", `contrast.gamma is ${String(contrast.gamma)}, which \`pow\` cannot take as an exponent — using 1 (no gamma). Stem darkening is unaffected and is ${contrast.stemDarkening ? "on" : "off"}.`);
+		contrastGamma = 1;
+	}
+	const contrastStemDarken = contrast.stemDarkening ? 1 : 0;
+	const requestedTexels = Math.max(1, options.atlasTexels ?? atlasWidth * 256);
+	const requestedRows = Math.max(1, Math.ceil(requestedTexels / atlasWidth));
+	const atlasHeight = Math.min(requestedRows, maxTextureSize);
+	if (atlasHeight !== requestedRows) report("atlas-clamped", `${requestedTexels} texels needs ${requestedRows} rows but MAX_TEXTURE_SIZE caps the texture at ${maxTextureSize} — the atlas holds ${atlasHeight * atlasWidth} texels, and a working set larger than that will thrash the ring`);
+	const capacityTexels = atlasHeight * atlasWidth;
+	let program = null;
+	let uViewProjection = null;
+	let uMatViewProjection = null;
+	let uColor = null;
+	let uSpreadPx = null;
+	let uViewport = null;
+	let uGamma = null;
+	let uStemDarken = null;
+	let uAtlas = null;
+	let uAtlasWidth = null;
+	let aNormal = -1;
+	let aPosition = -1;
+	let aTexcoord = -1;
+	let aEmPerPos = -1;
+	let aGlyphLoc = -1;
+	let aModel0 = -1;
+	let aModel1 = -1;
+	let aModel2 = -1;
+	let aColor = -1;
+	let aSpreadPx = -1;
+	let atlasTexture = null;
+	let vao = null;
+	let cornerBuffer = null;
+	let instanceBuffer = null;
+	let instanceCapacity = 256;
+	let instanceData = new ArrayBuffer(instanceCapacity * instanceBytes);
+	let instanceFloats = new Float32Array(instanceData);
+	let instanceUints = new Uint32Array(instanceData);
+	function buildProgram() {
+		const vertex = compileShader(gl, gl.VERTEX_SHADER, GLSL_PREAMBLE + module.shaderLibrary(0) + (perInstanceRunState ? BATCHED_VERTEX_MAIN : VERTEX_MAIN));
+		if ("message" in vertex) return vertex;
+		const fragment = compileShader(gl, gl.FRAGMENT_SHADER, GLSL_PREAMBLE + (spreadTapMsaa ? "" : SPREAD_TAP_NO_MSAA_DEFINE) + module.shaderLibrary(1) + (perInstanceRunState ? BATCHED_FRAGMENT_MAIN : FRAGMENT_MAIN));
+		if ("message" in fragment) {
+			gl.deleteShader(vertex.shader);
+			return fragment;
+		}
+		const created = gl.createProgram();
+		if (!created) {
+			gl.deleteShader(vertex.shader);
+			gl.deleteShader(fragment.shader);
+			return {
+				reason: "gl-object",
+				message: "gl.createProgram returned null (context lost?)"
+			};
+		}
+		gl.attachShader(created, vertex.shader);
+		gl.attachShader(created, fragment.shader);
+		gl.linkProgram(created);
+		gl.deleteShader(vertex.shader);
+		gl.deleteShader(fragment.shader);
+		if (!gl.getProgramParameter(created, gl.LINK_STATUS)) {
+			const log = gl.getProgramInfoLog(created) || "(no log)";
+			gl.deleteProgram(created);
+			return {
+				reason: "program-link",
+				message: `program failed to link — ${log}`
+			};
+		}
+		program = created;
+		if (perInstanceRunState) uViewProjection = gl.getUniformLocation(created, "u_viewProjection");
+		else uMatViewProjection = gl.getUniformLocation(created, "u_matViewProjection");
+		uViewport = gl.getUniformLocation(created, "u_viewport");
+		if (!perInstanceRunState) {
+			uColor = gl.getUniformLocation(created, "u_color");
+			uSpreadPx = gl.getUniformLocation(created, "u_spreadPx");
+		}
+		uGamma = gl.getUniformLocation(created, "u_gamma");
+		uStemDarken = gl.getUniformLocation(created, "u_stemDarken");
+		uAtlas = gl.getUniformLocation(created, "hb_gpu_atlas");
+		uAtlasWidth = gl.getUniformLocation(created, "hb_gpu_atlas_width");
+		aNormal = gl.getAttribLocation(created, "a_normal");
+		aPosition = gl.getAttribLocation(created, "a_position");
+		aTexcoord = gl.getAttribLocation(created, "a_texcoord");
+		aEmPerPos = gl.getAttribLocation(created, "a_emPerPos");
+		aGlyphLoc = gl.getAttribLocation(created, "a_glyphLoc");
+		if (perInstanceRunState) {
+			aModel0 = gl.getAttribLocation(created, "a_model0");
+			aModel1 = gl.getAttribLocation(created, "a_model1");
+			aModel2 = gl.getAttribLocation(created, "a_model2");
+			aColor = gl.getAttribLocation(created, "a_color");
+			aSpreadPx = gl.getAttribLocation(created, "a_spreadPx");
+		}
+		const missing = [
+			["a_normal", aNormal],
+			["a_position", aPosition],
+			["a_texcoord", aTexcoord],
+			["a_emPerPos", aEmPerPos],
+			["a_glyphLoc", aGlyphLoc],
+			...perInstanceRunState ? [
+				["a_model0", aModel0],
+				["a_model1", aModel1],
+				["a_model2", aModel2],
+				["a_color", aColor],
+				["a_spreadPx", aSpreadPx]
+			] : []
+		].filter(([, location]) => location < 0).map(([name]) => name);
+		if (missing.length > 0) return {
+			reason: "program-link",
+			message: `the linked program has no location for ${missing.join(", ")} — the shader library does not match this file's main()`
+		};
+		gl.useProgram(created);
+		gl.uniform1i(uAtlas, 0);
+		gl.uniform1i(uAtlasWidth, atlasWidth);
+		gl.uniform1f(uGamma, contrastGamma);
+		gl.uniform1f(uStemDarken, contrastStemDarken);
+		return null;
+	}
+	function buildAtlasTexture() {
+		const created = gl.createTexture();
+		if (!created) return {
+			reason: "gl-object",
+			message: "gl.createTexture returned null (context lost?)"
+		};
+		atlasTexture = created;
+		gl.activeTexture(gl.TEXTURE0);
+		gl.bindTexture(gl.TEXTURE_2D, created);
+		gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA16I, atlasWidth, atlasHeight, 0, gl.RGBA_INTEGER, gl.SHORT, null);
+		gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
+		gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
+		gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+		gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+		return null;
+	}
+	function bindInstanceAttributes() {
+		gl.bindBuffer(gl.ARRAY_BUFFER, instanceBuffer);
+		gl.enableVertexAttribArray(aPosition);
+		gl.vertexAttribPointer(aPosition, 4, gl.FLOAT, false, instanceBytes, 0);
+		gl.vertexAttribDivisor(aPosition, 1);
+		gl.enableVertexAttribArray(aTexcoord);
+		gl.vertexAttribPointer(aTexcoord, 4, gl.FLOAT, false, instanceBytes, 16);
+		gl.vertexAttribDivisor(aTexcoord, 1);
+		gl.enableVertexAttribArray(aEmPerPos);
+		gl.vertexAttribPointer(aEmPerPos, 1, gl.FLOAT, false, instanceBytes, 32);
+		gl.vertexAttribDivisor(aEmPerPos, 1);
+		gl.enableVertexAttribArray(aGlyphLoc);
+		gl.vertexAttribIPointer(aGlyphLoc, 1, gl.UNSIGNED_INT, instanceBytes, 36);
+		gl.vertexAttribDivisor(aGlyphLoc, 1);
+		if (!perInstanceRunState) return;
+		gl.enableVertexAttribArray(aModel0);
+		gl.vertexAttribPointer(aModel0, 2, gl.FLOAT, false, instanceBytes, 40);
+		gl.vertexAttribDivisor(aModel0, 1);
+		gl.enableVertexAttribArray(aModel1);
+		gl.vertexAttribPointer(aModel1, 2, gl.FLOAT, false, instanceBytes, 48);
+		gl.vertexAttribDivisor(aModel1, 1);
+		gl.enableVertexAttribArray(aModel2);
+		gl.vertexAttribPointer(aModel2, 2, gl.FLOAT, false, instanceBytes, 56);
+		gl.vertexAttribDivisor(aModel2, 1);
+		gl.enableVertexAttribArray(aColor);
+		gl.vertexAttribPointer(aColor, 4, gl.FLOAT, false, instanceBytes, 64);
+		gl.vertexAttribDivisor(aColor, 1);
+		gl.enableVertexAttribArray(aSpreadPx);
+		gl.vertexAttribPointer(aSpreadPx, 1, gl.FLOAT, false, instanceBytes, 80);
+		gl.vertexAttribDivisor(aSpreadPx, 1);
+	}
+	function buildGeometry() {
+		const createdVao = gl.createVertexArray();
+		const createdCorner = gl.createBuffer();
+		const createdInstance = gl.createBuffer();
+		if (!createdVao || !createdCorner || !createdInstance) return {
+			reason: "gl-object",
+			message: "gl.createVertexArray/createBuffer returned null (context lost?)"
+		};
+		vao = createdVao;
+		cornerBuffer = createdCorner;
+		instanceBuffer = createdInstance;
+		gl.bindVertexArray(createdVao);
+		gl.bindBuffer(gl.ARRAY_BUFFER, createdCorner);
+		gl.bufferData(gl.ARRAY_BUFFER, new Float32Array([
+			-1,
+			1,
+			-1,
+			-1,
+			1,
+			1,
+			1,
+			-1
+		]), gl.STATIC_DRAW);
+		gl.enableVertexAttribArray(aNormal);
+		gl.vertexAttribPointer(aNormal, 2, gl.FLOAT, false, 0, 0);
+		gl.bindBuffer(gl.ARRAY_BUFFER, createdInstance);
+		gl.bufferData(gl.ARRAY_BUFFER, instanceData.byteLength, gl.DYNAMIC_DRAW);
+		bindInstanceAttributes();
+		gl.bindVertexArray(null);
+		return null;
+	}
+	function buildGlObjects() {
+		return buildProgram() ?? buildAtlasTexture() ?? buildGeometry();
+	}
+	/** Forget every handle WITHOUT calling GL. What a lost context leaves behind. */
+	function dropGlObjects() {
+		program = null;
+		atlasTexture = null;
+		vao = null;
+		cornerBuffer = null;
+		instanceBuffer = null;
+	}
+	function deleteGlObjects() {
+		if (vao) gl.deleteVertexArray(vao);
+		if (cornerBuffer) gl.deleteBuffer(cornerBuffer);
+		if (instanceBuffer) gl.deleteBuffer(instanceBuffer);
+		if (atlasTexture) gl.deleteTexture(atlasTexture);
+		if (program) gl.deleteProgram(program);
+		dropGlObjects();
+	}
+	const initialFailure = buildGlObjects();
+	if (initialFailure) {
+		deleteGlObjects();
+		return refuse(initialFailure.reason, initialFailure.message);
+	}
+	const faces = [];
+	/** Compatibility/debug lookup only; hot resolve/push use the numeric face maps below. */
+	const allocations = /* @__PURE__ */ new Map();
+	const byFace = [];
+	/** Identity proof for slots this renderer minted; structural legacy slots have no entry here. */
+	const ownedSlots = /* @__PURE__ */ new WeakMap();
+	/** Live allocations, always sorted by atlas offset. */
+	const order = [];
+	let cursor = 0;
+	let touchCounter = 0;
+	/** Monotonic touch stamp. One counter, one place it advances. */
+	const touch = () => {
+		touchCounter += 1;
+		return touchCounter;
+	};
+	/** Monotonic allocation stamp. Never reused, never reset — see {@link GlyphSlot.generation}. */
+	let generationCounter = 0;
+	let evictions = 0;
+	let staleSkips = 0;
+	let liveTexels = 0;
+	let frameIndex = 0;
+	let blobGlyphs = 0;
+	let blobBytes = 0;
+	let contextLost = false;
+	let designWidth = Math.max(1, options.designWidth);
+	let designHeight = Math.max(1, options.designHeight);
+	let framebufferWidth = Math.max(1, options.framebufferWidth ?? options.designWidth);
+	let framebufferHeight = Math.max(1, options.framebufferHeight ?? options.designHeight);
+	/**
+	* Place `texels` texels and return the offset, evicting whatever the cursor lands on.
+	*
+	* A BUMP RING, NOT `die ("Ran out of atlas memory")`. Allocations are laid down in touch order,
+	* so sweeping the cursor forward overwrites the OLDEST region first — which is LRU for the
+	* workload this exists for, a glyph pool larger than the atlas where every resident glyph is
+	* touched at most once a frame. It is only an approximation once a key is re-uploaded, and the
+	* approximation is not what makes this safe.
+	*
+	* WHAT MAKES IT SAFE IS THE IN-USE GUARD, AND THAT GUARD STAYS A THROW. Everything else in this
+	* file degrades to `null` plus an `onError`, because a shipped renderer must let its consumer
+	* fall back. This one does not, and the judgement is deliberate:
+	*
+	*   - It is not a runtime condition. It says the atlas cannot hold ONE FRAME's working set, which
+	*     is a sizing decision the embedder made before any frame ran. `atlas.capacityTexels` and
+	*     `atlas.liveTexels` are published precisely so it can be made correctly.
+	*   - Neither repair is honest. Evicting the victim draws a DIFFERENT glyph's outline in its
+	*     place, at the right size, in the right position, perfectly antialiased — unreadable text
+	*     that looks like working text. Declining the new glyph instead leaves the frame short, every
+	*     frame, forever, reported only as a counter nobody reads.
+	*   - It is not the hot loop. `push` never throws; this is the cache-miss path.
+	*/
+	function removeAllocation(entry) {
+		if (!entry.live) return;
+		entry.live = false;
+		allocations.delete(entry.key);
+		byFace[entry.faceId]?.delete(entry.glyphId);
+		const index = order.indexOf(entry);
+		if (index >= 0) order.splice(index, 1);
+		liveTexels -= entry.texels;
+	}
+	function allocate(key, texels) {
+		if (cursor + texels > capacityTexels) cursor = 0;
+		const start = cursor;
+		const end = cursor + texels;
+		let first = 0;
+		let last = order.length;
+		while (first < last) {
+			const middle = first + last >>> 1;
+			if (order[middle].offset + order[middle].texels <= start) first = middle + 1;
+			else last = middle;
+		}
+		let after = first;
+		while (after < order.length && order[after].offset < end) after += 1;
+		for (let i = first; i < after; i += 1) {
+			const victim = order[i];
+			if (victim.usedFrame === frameIndex) throw new Error(`hb-gpu: the atlas (${capacityTexels} texels) cannot hold one frame's glyphs — placing "${key}" would overwrite "${victim.key}", already drawn this frame`);
+		}
+		for (let i = first; i < after; i += 1) {
+			const victim = order[i];
+			victim.live = false;
+			allocations.delete(victim.key);
+			byFace[victim.faceId]?.delete(victim.glyphId);
+			liveTexels -= victim.texels;
+			evictions += 1;
+		}
+		if (after > first) order.splice(first, after - first);
+		cursor = end;
+		return start;
+	}
+	/**
+	* Upload one blob's texels, row by row.
+	*
+	* ROW BY ROW BECAUSE THE STREAM IS 1-D AND THE TEXTURE IS NOT. A blob is a run of texels at some
+	* absolute offset; that run generally starts mid-row and spans several. `texSubImage2D` can only
+	* write rectangles, so each row-fragment is its own call — which is upstream's loop, and the
+	* single most delicate arithmetic in this file. Off by one row and the glyph's band headers read
+	* as curve data.
+	*/
+	function uploadTexels(offset, texels) {
+		const shorts = texels.byteOffset % 2 === 0 ? new Int16Array(texels.buffer, texels.byteOffset, texels.byteLength / 2) : new Int16Array(texels.slice().buffer);
+		gl.activeTexture(gl.TEXTURE0);
+		gl.bindTexture(gl.TEXTURE_2D, atlasTexture);
+		const previousAlignment = Number(gl.getParameter(gl.UNPACK_ALIGNMENT)) || 4;
+		if (previousAlignment !== 4) gl.pixelStorei(gl.UNPACK_ALIGNMENT, 4);
+		const previousFlipY = Boolean(gl.getParameter(gl.UNPACK_FLIP_Y_WEBGL));
+		const previousPremultiply = Boolean(gl.getParameter(gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL));
+		if (previousFlipY) gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, false);
+		if (previousPremultiply) gl.pixelStorei(gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL, false);
+		let remaining = texels.byteLength / 8;
+		let source = 0;
+		let destination = offset;
+		while (remaining > 0) {
+			const x = destination % atlasWidth;
+			const y = Math.floor(destination / atlasWidth);
+			const run = Math.min(atlasWidth - x, remaining);
+			gl.texSubImage2D(gl.TEXTURE_2D, 0, x, y, run, 1, gl.RGBA_INTEGER, gl.SHORT, shorts, source * 4);
+			source += run;
+			destination += run;
+			remaining -= run;
+		}
+		if (previousAlignment !== 4) gl.pixelStorei(gl.UNPACK_ALIGNMENT, previousAlignment);
+		if (previousFlipY) gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, true);
+		if (previousPremultiply) gl.pixelStorei(gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL, true);
+	}
+	let instanceCount = 0;
+	const model = new Float32Array([
+		1,
+		0,
+		0,
+		1,
+		0,
+		0
+	]);
+	const color = new Float32Array([
+		1,
+		1,
+		1,
+		1
+	]);
+	/** Object units, and 0 is the fill path. See {@link HbGpuRenderer.setSpread}. */
+	let spreadPx = 0;
+	const mvp = new Float32Array(16);
+	let mvpDirty = true;
+	let colorDirty = true;
+	let spreadDirty = true;
+	let viewportDirty = true;
+	/**
+	* Design -> clip as `(scaleX, scaleY, translateX, translateY)`, byte-identical to
+	* `createCanvasStage`'s `toClip`.
+	*
+	* `scaleY` is NEGATIVE because design space measures y DOWNWARDS and clip space upwards. Computed
+	* here rather than read off a stage because this renderer no longer has one — and restated in the
+	* same four numbers, in the same order, so the two cannot silently diverge.
+	*
+	* THE DESIGN PAIR, NOT THE FRAMEBUFFER PAIR. The framebuffer pair is `u_viewport` and only that.
+	*/
+	const toClip = new Float32Array(4);
+	function refreshProjection() {
+		toClip[0] = 2 / designWidth;
+		toClip[1] = -2 / designHeight;
+		toClip[2] = -1;
+		toClip[3] = 1;
+	}
+	refreshProjection();
+	/**
+	* Design-to-clip as the column-major `mat4` GLSL wants. The batched program receives only this
+	* projection; the established renderer keeps its complete model-view-projection uniform.
+	*
+	* ONE matrix, and it has to be this one. `hb_gpu_dilate` is handed the same `m` and works out
+	* how far half a screen pixel is by pushing the vertex AND its normal through it, so any part of
+	* the transform applied elsewhere — a quad rotated on the CPU, a viewport scale — is a transform
+	* the dilation cannot see.
+	*/
+	function refreshMatrix() {
+		const sx = toClip[0];
+		const sy = toClip[1];
+		mvp.fill(0);
+		mvp[0] = perInstanceRunState ? sx : sx * model[0];
+		mvp[1] = perInstanceRunState ? 0 : sy * model[1];
+		mvp[4] = perInstanceRunState ? 0 : sx * model[2];
+		mvp[5] = perInstanceRunState ? sy : sy * model[3];
+		mvp[10] = 1;
+		mvp[12] = perInstanceRunState ? toClip[2] : sx * model[4] + toClip[2];
+		mvp[13] = perInstanceRunState ? toClip[3] : sy * model[5] + toClip[3];
+		mvp[15] = 1;
+	}
+	function growInstances() {
+		instanceCapacity *= 2;
+		const next = new ArrayBuffer(instanceCapacity * instanceBytes);
+		new Uint8Array(next).set(new Uint8Array(instanceData));
+		instanceData = next;
+		instanceFloats = new Float32Array(instanceData);
+		instanceUints = new Uint32Array(instanceData);
+		gl.bindVertexArray(vao);
+		gl.bindBuffer(gl.ARRAY_BUFFER, instanceBuffer);
+		gl.bufferData(gl.ARRAY_BUFFER, instanceData.byteLength, gl.DYNAMIC_DRAW);
+		bindInstanceAttributes();
+		gl.bindVertexArray(null);
+	}
+	/**
+	* The slot an allocation describes. ONE expression, and that is the point of it.
+	*
+	* A fresh slot, a slot for a glyph that was already resident and a slot handed back by
+	* {@link HbGpuRenderer.resolve} all come from here, so they cannot disagree about the ink box,
+	* the generation or the offset. It reads the ALLOCATION only — it takes no `EncodedGlyph` —
+	* which is what lets `resolve` exist without an encoder.
+	*/
+	function slotFor(entry) {
+		return entry.slot;
+	}
+	return {
+		gl,
+		atlasWidth,
+		get contextLost() {
+			return contextLost;
+		},
+		registerFace(font, label) {
+			const upem = font.upem;
+			if (!Number.isInteger(upem) || upem <= 0) return refuse("degenerate-upem", `face "${label ?? faces.length}" reports upem ${upem} — every glyph scaled by it would be NaN and draw nothing`);
+			const face = {
+				id: faces.length,
+				label: label ?? `face${faces.length}`,
+				upem,
+				font
+			};
+			faces.push(face);
+			byFace.push(/* @__PURE__ */ new Map());
+			return face;
+		},
+		upload(face, glyphId, glyph) {
+			if (contextLost) {
+				report("context-lost", `upload of glyph ${glyphId} ignored while the context is lost — call rebuild() from webglcontextrestored`);
+				return null;
+			}
+			const registered = faces[face.id];
+			if (!registered || registered !== face) return refuse("face-unregistered", `face "${face.label}" (id ${face.id}) was not registered with this renderer — its keys would collide with whatever face holds that id`);
+			const key = `${face.id}/${glyphId}`;
+			const existing = byFace[face.id]?.get(glyphId);
+			if (existing) {
+				existing.usedAt = touch();
+				return slotFor(existing);
+			}
+			if (glyph.texels.length === 0) return null;
+			if (glyph.texels.length % 8 !== 0) return refuse("blob-malformed", `blob for "${key}" is ${glyph.texels.length} bytes, not a whole number of 8-byte texels — it would be uploaded a texel short and read as curve data`);
+			const texels = glyph.texels.length / 8;
+			if (texels > capacityTexels) return refuse("blob-too-large", `glyph "${key}" needs ${texels} texels but the whole atlas is ${capacityTexels} — raise atlasTexels; this glyph will not be drawn`);
+			const offset = allocate(key, texels);
+			uploadTexels(offset, glyph.texels);
+			generationCounter += 1;
+			const entry = {
+				key,
+				faceId: face.id,
+				glyphId,
+				offset,
+				texels,
+				generation: generationCounter,
+				live: true,
+				rid,
+				usedAt: touch(),
+				usedFrame: -1,
+				upem: face.upem,
+				minX: glyph.extents.xBearing,
+				minY: glyph.extents.yBearing + glyph.extents.height,
+				maxX: glyph.extents.xBearing + glyph.extents.width,
+				maxY: glyph.extents.yBearing
+			};
+			const slot = {
+				faceId: face.id,
+				glyphId,
+				key,
+				generation: entry.generation,
+				loc: entry.offset,
+				upem: entry.upem,
+				minX: entry.minX,
+				minY: entry.minY,
+				maxX: entry.maxX,
+				maxY: entry.maxY,
+				texels: entry.texels
+			};
+			Object.defineProperty(slot, SLOT_OWNER, { value: rid });
+			const owned = {
+				...entry,
+				slot
+			};
+			ownedSlots.set(slot, owned);
+			allocations.set(key, owned);
+			byFace[face.id].set(glyphId, owned);
+			let insertion = 0;
+			while (insertion < order.length && order[insertion].offset < offset) insertion += 1;
+			order.splice(insertion, 0, owned);
+			liveTexels += texels;
+			blobGlyphs += 1;
+			blobBytes += glyph.texels.length;
+			return slotFor(owned);
+		},
+		resolve(face, glyphId) {
+			if (contextLost) return null;
+			const registered = faces[face.id];
+			if (!registered || registered !== face) return refuse("face-unregistered", `face "${face.label}" (id ${face.id}) was not registered with this renderer — resolve() cannot answer for it, and every glyph of the run would be missing`);
+			const entry = byFace[face.id]?.get(glyphId);
+			if (!entry) return null;
+			entry.usedAt = touch();
+			return slotFor(entry);
+		},
+		begin() {
+			frameIndex += 1;
+			instanceCount = 0;
+		},
+		push(slot, x, y, pixelsPerEm) {
+			if (contextLost) return;
+			const owned = ownedSlots.get(slot);
+			const owner = slot[SLOT_OWNER];
+			const entry = owned ? owned : owner !== void 0 && owner !== rid ? void 0 : slot.faceId !== void 0 && slot.glyphId !== void 0 ? byFace[slot.faceId]?.get(slot.glyphId) : allocations.get(slot.key);
+			if (!entry || entry.rid !== rid || !entry.live || entry.generation !== slot.generation || entry.offset !== slot.loc) {
+				staleSkips += 1;
+				return;
+			}
+			if (instanceCount >= instanceCapacity) growInstances();
+			entry.usedFrame = frameIndex;
+			entry.usedAt = touch();
+			const scale = pixelsPerEm / slot.upem;
+			const base = instanceCount * instanceFloatsPerRecord;
+			instanceFloats[base] = x + scale * slot.minX;
+			instanceFloats[base + 1] = y - scale * slot.minY;
+			instanceFloats[base + 2] = x + scale * slot.maxX;
+			instanceFloats[base + 3] = y - scale * slot.maxY;
+			instanceFloats[base + 4] = slot.minX;
+			instanceFloats[base + 5] = slot.minY;
+			instanceFloats[base + 6] = slot.maxX;
+			instanceFloats[base + 7] = slot.maxY;
+			instanceFloats[base + 8] = 1 / scale;
+			instanceUints[base + 9] = slot.loc >>> 0;
+			if (perInstanceRunState) {
+				for (let i = 0; i < 6; i += 1) instanceFloats[base + 10 + i] = model[i];
+				instanceFloats[base + 16] = color[0];
+				instanceFloats[base + 17] = color[1];
+				instanceFloats[base + 18] = color[2];
+				instanceFloats[base + 19] = color[3];
+				instanceFloats[base + 20] = spreadPx;
+			}
+			instanceCount += 1;
+		},
+		setModel(next) {
+			for (let i = 0; i < 6; i += 1) {
+				if (!perInstanceRunState && model[i] !== next[i]) mvpDirty = true;
+				model[i] = next[i];
+			}
+		},
+		setColor(r, g, b, a) {
+			if (!perInstanceRunState) colorDirty ||= color[0] !== r || color[1] !== g || color[2] !== b || color[3] !== a;
+			color[0] = r;
+			color[1] = g;
+			color[2] = b;
+			color[3] = a;
+		},
+		setSpread(px) {
+			const next = Number.isFinite(px) && px > 0 ? px : 0;
+			if (!perInstanceRunState && spreadPx !== next) spreadDirty = true;
+			spreadPx = next;
+		},
+		setViewport(width, height, bufferWidth, bufferHeight) {
+			const nextDesignWidth = Math.max(1, width);
+			const nextDesignHeight = Math.max(1, height);
+			const nextFramebufferWidth = Math.max(1, bufferWidth ?? width);
+			const nextFramebufferHeight = Math.max(1, bufferHeight ?? height);
+			if (designWidth !== nextDesignWidth || designHeight !== nextDesignHeight) {
+				designWidth = nextDesignWidth;
+				designHeight = nextDesignHeight;
+				refreshProjection();
+				mvpDirty = true;
+			}
+			if (framebufferWidth !== nextFramebufferWidth || framebufferHeight !== nextFramebufferHeight) {
+				framebufferWidth = nextFramebufferWidth;
+				framebufferHeight = nextFramebufferHeight;
+				viewportDirty = true;
+			}
+		},
+		end() {
+			if (contextLost || instanceCount === 0) return {
+				instances: 0,
+				drawCalls: 0
+			};
+			if (!program || !vao || !instanceBuffer || !atlasTexture) return {
+				instances: 0,
+				drawCalls: 0
+			};
+			gl.useProgram(program);
+			gl.bindVertexArray(vao);
+			gl.bindBuffer(gl.ARRAY_BUFFER, instanceBuffer);
+			gl.bufferSubData(gl.ARRAY_BUFFER, 0, instanceFloats, 0, instanceCount * instanceFloatsPerRecord);
+			gl.activeTexture(gl.TEXTURE0);
+			gl.bindTexture(gl.TEXTURE_2D, atlasTexture);
+			if (mvpDirty) {
+				refreshMatrix();
+				gl.uniformMatrix4fv(perInstanceRunState ? uViewProjection : uMatViewProjection, false, mvp);
+				mvpDirty = false;
+			}
+			if (!perInstanceRunState && colorDirty) {
+				gl.uniform4fv(uColor, color);
+				colorDirty = false;
+			}
+			if (!perInstanceRunState && spreadDirty) {
+				gl.uniform1f(uSpreadPx, spreadPx);
+				spreadDirty = false;
+			}
+			if (viewportDirty) {
+				gl.uniform2f(uViewport, framebufferWidth, framebufferHeight);
+				viewportDirty = false;
+			}
+			gl.enable(gl.BLEND);
+			gl.blendEquation(gl.FUNC_ADD);
+			gl.blendFunc(gl.ONE, gl.ONE_MINUS_SRC_ALPHA);
+			gl.drawArraysInstanced(gl.TRIANGLE_STRIP, 0, 4, instanceCount);
+			gl.bindVertexArray(null);
+			return {
+				instances: instanceCount,
+				drawCalls: 1
+			};
+		},
+		notifyContextLost() {
+			contextLost = true;
+			instanceCount = 0;
+			dropGlObjects();
+		},
+		rebuild() {
+			const failure = buildGlObjects();
+			if (failure) {
+				deleteGlObjects();
+				report(failure.reason, `rebuild after context loss failed — ${failure.message}`);
+				return false;
+			}
+			mvpDirty = true;
+			colorDirty = true;
+			spreadDirty = true;
+			viewportDirty = true;
+			const resident = [...order];
+			const dropped = [];
+			for (const entry of resident) {
+				const face = faces[entry.faceId];
+				const glyph = face ? face.font.encode(entry.glyphId) : null;
+				if (!glyph || glyph.texels.length !== entry.texels * 8) {
+					removeAllocation(entry);
+					dropped.push(entry.key);
+					continue;
+				}
+				uploadTexels(entry.offset, glyph.texels);
+			}
+			contextLost = false;
+			if (dropped.length > 0) report("rebuild-incomplete", `${dropped.length} of ${resident.length} resident glyphs could not be re-encoded after a context loss (${dropped.slice(0, 8).join(", ")}${dropped.length > 8 ? ", …" : ""}) — their faces' fonts must outlive the renderer; those glyphs will be skipped until re-uploaded`);
+			return true;
+		},
+		get atlas() {
+			return {
+				liveBytes: liveTexels * 8,
+				reservationBytes: atlasWidth * atlasHeight * 8,
+				entries: allocations.size,
+				liveTexels,
+				capacityTexels,
+				evictions,
+				faces: faces.length,
+				staleSkips
+			};
+		},
+		get blobs() {
+			return {
+				glyphs: blobGlyphs,
+				totalBytes: blobBytes,
+				bytesPerGlyph: blobGlyphs > 0 ? blobBytes / blobGlyphs : 0
+			};
+		},
+		dispose() {
+			if (!contextLost) deleteGlObjects();
+			else dropGlObjects();
+			faces.length = 0;
+			allocations.clear();
+			byFace.length = 0;
+			order.length = 0;
+		}
+	};
+}
+//#endregion
+export { ATLAS_WIDTH, FRAGMENT_MAIN, HB_GPU_CONTRAST_DEFAULT, HB_GPU_CONTRAST_NONE, HB_GPU_SPREAD_MAX_TAPS, createHbGpuRenderer };
+
+//# sourceMappingURL=webgl.js.map