@godot-scene-web/hb-gpu 0.1.0

package/dist/webgl.d.ts

@@ -0,0 +1,523 @@
+import { EncodedGlyph, HbGpu, HbGpuFailure, HbGpuFont } from "./index.js";
+
+//#region src/webgl.d.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.
+ */
+declare const ATLAS_WIDTH = 4096;
+/**
+ * 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.
+ */
+declare const HB_GPU_SPREAD_MAX_TAPS = 64;
+declare const FRAGMENT_MAIN = "\nuniform vec4 u_color;   /* STRAIGHT rgba; premultiplied exactly once, below */\nuniform float u_spreadPx;\nuniform float u_gamma;       /* exponent on the final coverage; 1.0 is off */\nuniform float u_stemDarken;  /* > 0 runs hb_gpu_stem_darken; 0 is off */\n\nin vec2 v_texcoord;\nflat in uint v_glyphLoc;\nflat in float v_spreadEm;\n\nout vec4 fragColor;\n\nconst float HB_GPU_SPREAD_TAU = 6.2831853;\n/* Hard ceilings so the loop is bounded at compile time. One tap per iteration, so\n * HB_GPU_SPREAD_MAX_TAPS + the centre tap is the worst case, and it is only reached by a fragment\n * that is neither solid ink nor near any. See the TS constant of the same name. */\nconst int HB_GPU_SPREAD_MAX_RINGS = 4;\nconst int HB_GPU_SPREAD_MAX_TAPS = 64;\n/* \"Already saturated\": no tap can raise this, so stop. Not 1.0, because the coverage estimator\n * lands a hair under it on a deep-interior fragment and an exact test would never fire. */\nconst float HB_GPU_SPREAD_SOLID = 0.999;\n\n/*\n * WHERE A TAP STOPS MEANING \"how much ink is at this offset\" AND STARTS MEANING \"is this fragment\n * inside the dilated silhouette\". The knee of a smoothstep, and the whole of the fix below.\n *\n * NO BACKTICKS ANYWHERE IN THIS COMMENT, and that is not a style note: this whole string is a JS\n * template literal, so one backtick ends the shader mid-sentence and the package fails to PARSE.\n *\n * THE BUG IT REMOVES. A dilated shape is the union of a disk of radius r swept along the outline:\n * a BINARY shape, whose only partial coverage is at its own boundary. A max of raw coverage taps\n * cannot produce that, because a max cannot exceed the largest coverage near the fragment \u2014 and at\n * ppem 14 a Han stroke is thinner than a pixel, so its coverage PEAKS at 0.42 and the whole\n * silhouette came out a translucent mottle at 0.62 of the ideal's ink.\n *\n * THE RANGE IS 0 TO 0.5, AND \"A TAP ABOVE HALF COVERAGE IS INSIDE\" IS THE RULE THAT FAILS. That is\n * the obvious reading and it makes this case measurably WORSE, which is why the knee is a swept\n * number rather than an argued one. Half of a PIXEL is not half of a sub-pixel STROKE: at ppem 14\n * the fixture's peak coverage is 0.42, so a knee centred on 0.5 sits above anything the glyph can\n * reach and ERASES the outline. What 0.5 is the right value for is the top of the range \u2014 a pixel\n * centred exactly ON the outline reads 0.5, so \"as covered as a pixel on the boundary\" is the point\n * at which a tap is fully inside, and everything below it ramps.\n *\n * SWEPT ON THE RTX 2060 THROUGH ANGLE, both fixtures, against 8x grown references. Low-ppem is\n * \u4E2D at 14 px per em rotated 10 degrees, spread 3 (SHALLOW COVERAGE); thin is a full stop at 96 px\n * per em, spread 12 (SPARSE COVERING \u2014 no 64-tap set tiles a disk of that radius; the sweep was run\n * when those taps were four rings of 16, and the rim column moved again when they were resplit).\n *\n *   knee          low rim rms   low ink ratio   low interior short   thin rim rms   thin ink ratio\n *   none            77.89           0.622            38.5%              80.90           0.965\n *   0.35 - 0.65    128.57           0.574            (worse still)     102.52           0.966\n *   0.25 - 0.75    112.35           0.604             ---               99.72           0.965\n *   0.20 - 0.50     76.87           0.870             ---               94.27           0.974\n *   0.15 - 0.45     73.85           0.968             ---               90.15           0.978\n *   0.10 - 0.40     84.75           1.037             ---               85.82           0.985\n *   0.05 - 0.45     79.40           1.011             4.1%              82.16           0.986\n *   0.05 - 0.50     72.64           0.968             7.4%              82.81           0.983\n *   0.00 - 0.45     83.29           1.026             3.3%              78.86           0.990\n *   0.00 - 0.55     69.73           0.947             9.3%              79.96           0.984\n *   0.00 - 0.50     75.66           0.988             6.1%              79.10           0.987   <-\n *\n * The two upper rows are the \"roughly half\" hypothesis and both are worse than shipping nothing.\n * 0 - 0.5 is the only row that improves EVERY column at once, and it is also the one with a\n * sentence behind it rather than a fit.\n *\n * WHAT IT COSTS AT LARGE PPEM. A well-resolved glyph's tap coverage IS the area, so a tap sitting\n * exactly on the outline reads 0.5 \u2014 and 0.5 is also the ideal answer at the dilated boundary,\n * where this maps it to 1. So the boundary moves outward by a fraction of a pixel: measured, the\n * 96 px per em ink box grows 5 px on one side for a spread of 4 instead of 4. Real, inside the\n * fixtures' SPREAD_TOLERANCE_PX, and the price of an interior that is no longer translucent.\n *\n * PER TAP RATHER THAN ON THE MAX, AND NOT FOR THE REASON IT LOOKS LIKE. smoothstep is MONOTONE, so\n * it commutes with max and the two placements give the same silhouette \u2014 measured, not reasoned:\n * moving it after the loop reads ink ratio 0.989 against 0.988 and the same rim RMS to two decimal\n * places. What the placement actually buys is the two things a monotone identity does not cover.\n * First, the FILL IS THE FLOOR: cov enters the loop as hb_gpu_draw's own coverage and is never\n * sharpened, so a dilated run stays a strict SUPERSET of the same run at spread 0 \u2014 sharpening the\n * max would put the fill through the knee too, and smoothstep(0, 0.5, x) is BELOW x for x under\n * ~0.08, so a faint fill pixel would come back dimmer than it was drawn. Second, the early-out\n * below tests cov INSIDE the loop, and only a per-tap value can raise it early.\n *\n * IT DOES NOT MAKE THE EARLY-OUT FIRE AT 14 px, WHICH THE ROUND EXPECTED IT TO. A tap saturates to\n * exactly 1 only once its raw coverage reaches HB_GPU_SPREAD_INSIDE_HIGH, and at ppem 14 the\n * fixture's peak raw coverage is 0.42, which sharpens to 0.931 \u2014 still under\n * HB_GPU_SPREAD_SOLID. So a fragment at that size still walks the whole tap set, and the frame-cost\n * side effect that was predicted here IS NOT THERE. Above ppem 16 taps reached 1 before this change\n * as well, so nothing moved there either. Lowering HB_GPU_SPREAD_SOLID would collect it, and is\n * deliberately not done here: it is a cost decision with its own pixels to grade, on a rung where\n * the tap budget is a device ceiling.\n */\nconst float HB_GPU_SPREAD_INSIDE_LOW = 0.0;\nconst float HB_GPU_SPREAD_INSIDE_HIGH = 0.5;\n\n/*\n * One coverage tap, WITH NO DERIVATIVE IN IT \u2014 which is the whole reason this exists.\n *\n * It is _hb_gpu_slug (hb-gpu-fragment.glsl, 14.4.0) with ppem lifted into a parameter. The\n * library's own _hb_gpu_slug advertises itself as callable \"from non-uniform control flow\", and\n * for GLSL it is not: it calls hb_gpu_ppem, which calls fwidth. The disk below has a per-fragment\n * early-out, so every tap after that point IS non-uniform control flow, and a fwidth there is\n * undefined by GLSL ES 3.00.\n *\n * MIRRORED RATHER THAN AVOIDED so an outline tap and a fill fragment agree. Lifting ppem is exact\n * rather than an approximation: it is fwidth(v_texcoord) and the glyph's own scale, and fwidth of an\n * interpolated varying is constant across an affine quad, so its value at a tap equals its value at\n * the centre.\n *\n * THE MSAA HALF IS SWITCHABLE AND THE DEFAULT IS OFF \u2014 see\n * {@link HbGpuRendererOptions.spreadTapMsaa}, which carries the measurement. Note the macro is\n * HB_GPU_SPREAD_TAP_NO_MSAA and NOT the library's HB_GPU_NO_MSAA: that one guards _hb_gpu_slug,\n * i.e. the FILL, which this trade must not touch.\n *\n * The vendored wasm is digest-pinned (vendor/VENDOR.md, test/vendor.test.ts), so the source this\n * mirrors cannot move without a deliberate vendor bump.\n */\nfloat hb_gpu_spread_tap (vec2 rc, vec2 pixelsPerEm, float ppem, uint glyphLoc_)\n{\n  float c = _hb_gpu_slug_single (rc, pixelsPerEm, glyphLoc_);\n#ifndef HB_GPU_SPREAD_TAP_NO_MSAA\n  if (ppem < 16.0)\n  {\n    vec2 emsPerPixel = 1.0 / pixelsPerEm;\n    vec2 d = emsPerPixel * (1.0 / 3.0);\n    float msaa = 0.25 *\n      (_hb_gpu_slug_single (rc + vec2 (-d.x, -d.y), pixelsPerEm, glyphLoc_) +\n       _hb_gpu_slug_single (rc + vec2 ( d.x, -d.y), pixelsPerEm, glyphLoc_) +\n       _hb_gpu_slug_single (rc + vec2 (-d.x,  d.y), pixelsPerEm, glyphLoc_) +\n       _hb_gpu_slug_single (rc + vec2 ( d.x,  d.y), pixelsPerEm, glyphLoc_));\n    c = mix (c, msaa, smoothstep (16.0, 8.0, ppem));\n  }\n#endif\n  return c;\n}\n\nvoid main ()\n{\n  float cov = hb_gpu_draw (v_texcoord, v_glyphLoc);\n\n  /* UNIFORM CONTROL FLOW, AND IT HAS TO BE: the two derivative-taking calls inside are legal only\n   * because every fragment of a 2x2 derivative quad takes this branch together. u_spreadPx is a\n   * real uniform and v_spreadEm is flat (constant over a primitive, which is what a derivative\n   * quad belongs to), so it is uniform by construction rather than by luck. v_spreadEm is also a\n   * genuine guard: a NaN or zero a_emPerPos fails it and takes the single-tap path. */\n  if (u_spreadPx > 0.0 && v_spreadEm > 0.0)\n  {\n    vec2 pixelsPerEm = 1.0 / fwidth (v_texcoord);\n    float ppem = hb_gpu_ppem (v_texcoord, v_glyphLoc);\n    /* The spread in DEVICE pixels \u2014 fwidth is a screen-space derivative, so this already carries\n     * the model scale and the device-pixel ratio. It only ever picks tap counts; the tap OFFSETS\n     * are in em units and are exact. */\n    float radiusPx = v_spreadEm * max (pixelsPerEm.x, pixelsPerEm.y);\n\n    /* CONCENTRIC RINGS, NOT ONE, and that is not a refinement. A dilated fragment is covered iff\n     * SOME offset within the disk lands on ink; taps on a single ring of radius r can all overshoot\n     * a feature narrower than 2r, which punches holes through the outline exactly where a glyph is\n     * thin \u2014 a comma, a hairline serif, a full stop. Ring spacing is held near 2/3 px, so the RADIAL\n     * half of the covering is sub-pixel out to the clamp at HB_GPU_SPREAD_MAX_RINGS.\n     *\n     * THE RADII STAY EQUALLY SPACED, which is worth saying because equal AREA is the obvious\n     * alternative and it is worse here. Pushing the rings outward concentrates them where the taps\n     * are already densest, and combined with the budget split below it both doubles the outward bias\n     * of the whole tap set and halves the radial margin the small-feature case relies on \u2014 the one\n     * where a full stop smaller than the tap radius has to be found by an INNER ring. */\n    int rings = clamp (int (ceil (radiusPx * 1.5)), 1, HB_GPU_SPREAD_MAX_RINGS);\n    /* 1 + 2 + ... + rings, the denominator of the budget split below. */\n    int denom = rings * (rings + 1) / 2;\n\n    /* ONE FLAT LOOP OVER THE WHOLE BUDGET, AND THE OUTER RING GETS MOST OF IT.\n     *\n     * Every ring used to be capped at the same number of steps, which sounds neutral and is not: a\n     * ring's taps are spread over a circumference proportional to its radius, so an equal share puts\n     * the WIDEST arc gaps on the outermost ring \u2014 the only one that decides where the dilated\n     * boundary lands. At radius 12 that was 4.71 px of arc between the taps that draw the edge,\n     * against 1.18 px on ring 1, and the boundary followed the tap count: measured against a Godot\n     * 4.5.1 golden, 0.3099 px of wobble at exactly 16 cycles per revolution where the engine has\n     * 0.0164.\n     *\n     * So the budget is split in proportion to ring RADIUS, i.e. to circumference: ring k of rings\n     * may spend (MAX_TAPS * k + denom/2) / denom taps, which at four rings is 6 / 13 / 19 / 26 and\n     * sums to exactly MAX_TAPS. It sums to exactly MAX_TAPS at one, two and three rings as well\n     * (64; 21 + 43; 11 + 21 + 32), so the flat bound is never the thing that truncates a ring \u2014 it\n     * is a hedge against a driver that insists on unrolling, not a second policy. At radius 12 the\n     * outer arc is then 2.90 px rather than 4.71.\n     *\n     * The lower clamp of 6 steps is what keeps a SMALL radius honest, and it is the reason the cap\n     * enters as max (cap, 6) rather than as cap: ring 1's share at four rings is exactly 6, and a\n     * hexagon is the coarsest ring that still surrounds its centre.\n     *\n     * ONE TAP PER ITERATION, so HB_GPU_SPREAD_MAX_TAPS is simultaneously the loop bound and the\n     * fragment's worst-case cost \u2014 the two used to be 4 x 16 and 65 and had to be reasoned about\n     * separately. Dynamic bounds and breaks are legal ESSL 3.00; the GLSL ES 1.00 Appendix A\n     * restriction that forced the nested constant shape does not apply to version 300 es. */\n    int ring = 0;\n    int step = 0;\n    int steps = 0;\n    float ringEm = 0.0;\n    float phase = 0.0;\n    for (int i = 0; i < HB_GPU_SPREAD_MAX_TAPS; i++)\n    {\n      /* THE INTERIOR EARLY-OUT: a fragment already covered by its own centre tap is trivially\n       * within r of ink, and interior fragments are most of a glyph. */\n      if (cov >= HB_GPU_SPREAD_SOLID) break;\n      if (step >= steps)\n      {\n        ring += 1;\n        /* The other exit: the rings this radius actually asked for are done. */\n        if (ring > rings) break;\n        float t = float (ring) / float (rings);\n        ringEm = v_spreadEm * t;\n        int cap = (HB_GPU_SPREAD_MAX_TAPS * ring + denom / 2) / denom;\n        steps = clamp (int (ceil (HB_GPU_SPREAD_TAU * radiusPx * t)), 6, max (cap, 6));\n        /* THE GOLDEN ANGLE, so no two rings put their taps on the same radii \u2014 which would leave\n         * wedge-shaped gaps between the rings rather than a covering. A fixed fraction of a step\n         * would do that for one pair of ring counts and line up for another; 137.5 degrees per ring\n         * is the rotation with no small-integer commensurability with any of them. */\n        phase = 2.39996 * float (ring);\n        step = 0;\n      }\n      float angle = phase + HB_GPU_SPREAD_TAU * float (step) / float (steps);\n      vec2 at = v_texcoord + ringEm * vec2 (cos (angle), sin (angle));\n      /* MAX, NOT A SUM, AND THE MAX IS WHY THIS IS IN THE SHADER. The alternative a caller could\n       * build without it \u2014 draw the run N times at N offsets \u2014 composites N times, so a\n       * translucent outline is N overlapping translucent copies and reads far darker than one\n       * stroke. One fragment, one coverage, one blend.\n       *\n       * SHARPENED BEFORE THE MAX, not after: the max is over a set of INSIDE tests, and the union\n       * of disks it approximates is a binary shape. Sharpening the max instead would sharpen a\n       * number that had already been flattened to the peak coverage nearby, which is the value\n       * that is wrong. See HB_GPU_SPREAD_INSIDE_LOW. */\n      cov = max (cov, smoothstep (HB_GPU_SPREAD_INSIDE_LOW,\n                                  HB_GPU_SPREAD_INSIDE_HIGH,\n                                  hb_gpu_spread_tap (at, pixelsPerEm, ppem, v_glyphLoc)));\n      step += 1;\n    }\n  }\n\n  /* CONTRAST, ON THE FINAL COVERAGE \u2014 and STEM DARKENING ONLY WHEN THE DILATION DID NOT RUN.\n   *\n   * An outline's rim is NOT a coverage ramp with the same problem the fill's has, which is what\n   * this block assumed when it shipped. Stem darkening exists because a sub-pixel STEM lands at\n   * mid-grey under linear coverage where a browser puts it near the ink colour; the fix is an\n   * exponent that pushes the middle of the ramp toward the foreground. A dilated fragment's\n   * coverage is not that number. The taps above are an INSIDE test (HB_GPU_SPREAD_INSIDE_LOW\n   * sharpens each one before the max), so the dilated boundary is already very nearly binary \u2014 and\n   * the engine this mirrors applies no curve at all to its outline: Godot strokes the glyph and\n   * hands the result to FreeType's plain grayscale raster. Measured against that golden, the curve\n   * took a 14 px outline's rim from 0.662 px to 1.965 px of equivalent ramp, three times the width,\n   * where Godot's own is 0.851. That is a halo \u2014 fattening for dark ink, thinning for light \u2014 and\n   * it is the one thing in this shader that made an outline softer than the engine's.\n   *\n   * THE GATE IS THE DILATION BRANCH'S OWN CONDITION, CHARACTER FOR CHARACTER, so the two cannot\n   * disagree about which fragments dilated. A bare u_spreadPx > 0.0 would also strip the\n   * correction from a DEGENERATE run \u2014 one whose a_emPerPos is zero or NaN, which fails\n   * v_spreadEm > 0.0 and takes the single-tap path. Such a fragment is a fill in every way that\n   * reaches the framebuffer, and it should keep a fill's darkening rather than lose it to a uniform\n   * that ended up doing nothing.\n   *\n   * GAMMA IS NOT GATED. It is an explicit consumer knob, defaults to 1 (skipped entirely below),\n   * and is polarity- and size-blind by construction; a consumer that deliberately sets one is\n   * asking for a transfer curve on the text, and putting the fill and the outline of the same run\n   * on different curves would be a stranger thing than either choice.\n   *\n   * THE PPEM IS FETCHED IN UNIFORM CONTROL FLOW AND THE COVERAGE TEST IS NOT ALLOWED TO CONTAIN IT.\n   * hb_gpu_ppem calls fwidth, which GLSL ES 3.00 leaves undefined once the 2x2 derivative quad can\n   * disagree about whether to run it \u2014 and \"0.0 < cov < 1.0\" is precisely a per-fragment condition.\n   * u_stemDarken and u_spreadPx are real uniforms and v_spreadEm is flat, which is the same\n   * argument the dilation branch above makes for its own hb_gpu_ppem call; darken is that branch's\n   * predicate negated, so a quad coherent enough to run the dilation is exactly as coherent about\n   * skipping the darkening. Upstream's demo puts its fwidth inside the coverage test; that is a\n   * desktop-GLSL liberty this cannot take.\n   */\n  bool fillPass = !(u_spreadPx > 0.0 && v_spreadEm > 0.0);\n  bool darken = u_stemDarken > 0.0 && fillPass;\n\n  float darkenPpem = 0.0;\n  if (darken)\n    darkenPpem = hb_gpu_ppem (v_texcoord, v_glyphLoc);\n\n  /* EDGE ONLY, which is upstream's guard and is not merely an optimisation here. Both corrections\n   * fix 0 and 1, so the interior and the background cannot move whatever the exponents are \u2014 but\n   * pow (0.0, y) is UNDEFINED for y <= 0 in GLSL ES 3.00, and u_gamma is a number a consumer chose.\n   * Skipping cov == 0.0 is what makes a hostile gamma a picture that is wrong rather than a NaN\n   * alpha over the whole quad. No derivative is taken inside, so a non-uniform branch is legal. */\n  if (cov > 0.0 && cov < 1.0)\n  {\n    float adj = cov;\n    if (darken)\n    {\n      /* u_color is STRAIGHT, so this IS upstream's dot (c.rgb, 1/3) / c.a with the divide already\n       * done. A flat 1/3 rather than a Rec.709 luma on purpose: hb_gpu_stem_darken's exponent\n       * curve is calibrated against HarfBuzz's own definition of \"brightness\", and weighting the\n       * channels differently would silently retune somebody else's constants. */\n      adj = hb_gpu_stem_darken (adj, dot (u_color.rgb, vec3 (1.0 / 3.0)), darkenPpem);\n    }\n    if (u_gamma != 1.0)\n      adj = pow (adj, u_gamma);\n    cov = adj;\n  }\n\n  float a = u_color.a * cov;\n  fragColor = vec4 (u_color.rgb * a, a);\n}\n";
+/**
+ * A face registered with the renderer: the namespace every one of its glyph keys carries.
+ *
+ * THE ATLAS KEY IS `(face, glyph)` AND NOT `glyph`, AND THAT IS THE WHOLE POINT OF THIS TYPE.
+ * Glyph 42 of Noto Sans SC and glyph 42 of Roboto are unrelated outlines; an atlas keyed on the
+ * glyph id alone hands the second one the first one's texels and renders fluent, crisp, WRONG
+ * text — the one failure mode nothing downstream measures. That namespacing used to live in the
+ * perf-harness's key strings, one layer above a renderer that could not tell two faces apart.
+ *
+ * Registering also fixes the `upem`, so {@link HbGpuRenderer.upload} no longer takes one and a
+ * glyph cannot be uploaded under one face's scale and drawn at another's.
+ */
+interface HbGpuFace {
+  /** Dense index assigned at registration. Namespaces every key of this face. */
+  readonly id: number;
+  /** Whatever the embedder called it. Appears in failure messages, nowhere else. */
+  readonly label: string;
+  /** Units per em, taken from the registered font and never from a caller's argument. */
+  readonly upem: number;
+}
+/** Where one encoded glyph landed, and the box to draw it in. */
+interface GlyphSlot {
+  /**
+   * Numeric identity of the resident glyph. Optional so structural slots made by older callers
+   * remain accepted by the cold compatibility path in {@link HbGpuRenderer.push}.
+   */
+  faceId?: number;
+  glyphId?: number;
+  /**
+   * The allocator key — `<face id>/<glyph id>`, so a draw can find its allocation without a
+   * reverse lookup. Internal shape: read it for debugging, never construct one.
+   */
+  key: string;
+  /**
+   * Which ALLOCATION this slot describes, stamped by the allocator and never reused.
+   *
+   * THE ANSWER TO THE WORST BUG THIS PACKAGE HAD. The ring evicts, so a slot handed out an hour
+   * ago can name texels that some other glyph now owns. `push` used to draw it anyway, at the
+   * right size, in the right place, perfectly antialiased — a different glyph's outline, invisible
+   * to every check downstream. `push` now compares this against the live allocation and skips on a
+   * mismatch (see {@link AtlasStats.staleSkips}); a plain key comparison could not, because the
+   * key of a re-uploaded glyph is the same key.
+   */
+  generation: number;
+  /** Atlas texel index of the blob's first texel — the shader's `glyphLoc`. */
+  loc: number;
+  /** Units per em of the face these coordinates are in. */
+  upem: number;
+  /** Em-space ink box, y-UP, as `hb_gpu_draw_encode` reported it. */
+  minX: number;
+  minY: number;
+  maxX: number;
+  maxY: number;
+  /** Texels this blob occupies. */
+  texels: number;
+}
+interface AtlasStats {
+  /**
+   * What the live allocations actually occupy: texels x 8.
+   *
+   * The honest "how much glyph data is resident" number, and the one to compare against a baked
+   * atlas's occupied bytes.
+   */
+  liveBytes: number;
+  /**
+   * `width x height x 8` — the whole texture.
+   *
+   * THE NUMBER THAT SITS NEXT TO `hb-atlas`'s 1.45 MiB. A driver allocates the texture, not the
+   * used part of it, so this is what is actually held whatever the occupancy says. Reported
+   * separately from `liveBytes` because quoting only the smaller one is how a renderer appears to
+   * cost less than it does.
+   */
+  reservationBytes: number;
+  /** Live allocations, and the texels they hold. */
+  entries: number;
+  liveTexels: number;
+  capacityTexels: number;
+  /** Allocations overwritten by a wrapped cursor since creation. */
+  evictions: number;
+  /** Faces registered. Keys are namespaced by these — see {@link HbGpuFace}. */
+  faces: number;
+  /**
+   * Glyphs `push` declined to draw because their slot no longer matches a live allocation.
+   *
+   * NON-ZERO IS A REAL FINDING, not noise: it means the embedder is holding slots across an
+   * eviction (its atlas is too small for its working set, or it caches slots it should re-`upload`)
+   * and the frame is short of glyphs. Counted rather than thrown because `push` is the hot loop.
+   */
+  staleSkips: number;
+}
+interface BlobStats {
+  /** Distinct glyphs uploaded. */
+  glyphs: number;
+  /** Sum of every uploaded blob's length, in bytes. */
+  totalBytes: number;
+  /**
+   * THE PREDICTION UNDER TEST. `docs/text-rendering.md` records "~5.4 KB per Han glyph against
+   * ~1.4 KB for a 38x38 R8 atlas cell". This is the left-hand side of it, self-counted.
+   */
+  bytesPerGlyph: number;
+}
+/**
+ * The contrast correction the fragment stage applies to the coverage it computed.
+ *
+ * THE TWO FIELDS REACH DIFFERENT PASSES, which is the one thing to read before setting either:
+ * `gamma` is applied to every draw, `stemDarkening` only to an undilated one. The reason is under
+ * {@link HbGpuContrast.stemDarkening}.
+ *
+ * WHY IT EXISTS, AND WHY THE DEFAULT IS ON. Raw analytic coverage is the AREA of the pixel the
+ * outline covers, and compositing it linearly is not what a browser does: measured on one fixed
+ * crop of the word "Breakthrough" at 1600x900 / DPR 1.25, the hb-gpu path and the DOM path agree on
+ * peak darkness (51 vs 50), on mean luminance (120.5 vs 121.0) and on total ink (2736 vs 2744) —
+ * and DOM still puts **66% more pixels** in the deep-dark end (1285 below luma 80 against 775).
+ * That gap is entirely in the middle of the ramp: a sub-pixel stem lands mid-grey here and near the
+ * ink colour there, which reads as washed out at exactly the sizes a UI uses. Every shipping
+ * consumer wants the correction; the exception is a harness.
+ *
+ * BOTH FIELDS ARE REQUIRED rather than optional, which is deliberate. A half-specified
+ * `{ gamma: 1.2 }` would silently inherit a stem-darkening default the author never considered, and
+ * this is a knob whose whole purpose is that somebody thought about it. Use
+ * {@link HB_GPU_CONTRAST_DEFAULT} / {@link HB_GPU_CONTRAST_NONE} rather than writing the pair out.
+ */
+interface HbGpuContrast {
+  /**
+   * Exponent applied to the coverage. `1` is the identity and is the default.
+   *
+   * BELOW 1 IS DARKER (a coverage of 0.5 moves toward 1), above 1 lighter. It is polarity-BLIND —
+   * unlike `stemDarkening`, which reads the foreground — so a value that helps dark-on-light text
+   * hurts light-on-dark by the same amount. HarfBuzz's own demo flips it by theme
+   * (`demo-view.cc`: `dark_mode ? 1/2.2 : 2.2`) for that reason, and a renderer here draws both
+   * polarities in one frame and cannot. Hence 1: the size- and polarity-aware half of the
+   * correction is `stemDarkening`, and this is the manual override next to it.
+   *
+   * Non-finite or non-positive values are refused and reported (`"degenerate-contrast"`), because
+   * `pow` with such an exponent is a NaN alpha over the whole quad rather than a wrong picture.
+   */
+  gamma: number;
+  /**
+   * Run `hb_gpu_stem_darken` on the coverage OF A FILL. Default `true`.
+   *
+   * IT IS THE SIZE-AWARE AND POLARITY-AWARE HALF. The library's exponent is
+   * `mix (pow (2, brightness - 0.5), 1, smoothstep (8, 48, ppem))`, so it fattens dark text
+   * (brightness 0 -> exponent 0.707), thins light text (brightness 1 -> 1.414) and RAMPS ITSELF OFF
+   * by ppem 48, where a stem is wide enough that no pixel of it is partially covered anyway. The
+   * brightness comes from the per-instance colour and the ppem from `hb_gpu_ppem`, so it costs no
+   * per-frame decision.
+   *
+   * IT DOES NOT APPLY TO A DILATED RUN, whatever this flag says: a draw with a non-zero
+   * {@link HbGpuRenderer.setSpread} emits raw coverage. The correction exists because a sub-pixel
+   * STEM sits at mid-grey under linear coverage where a browser puts it near the ink colour, and a
+   * dilated fragment's coverage is not that number — the taps are an inside test, so the boundary
+   * is nearly binary before any curve touches it. More decisively, Godot's outline is a plain
+   * FreeType raster with no curve of its own, so an exponent on a dilated rim reads as a HALO
+   * against it: fattening for dark ink, thinning for light. Measured against the committed Godot
+   * golden, it took a 14 px outline's rim from 0.662 to 1.965 px of equivalent ramp where Godot's
+   * is 0.851 (`packages/hb-gpu/test/goldens/godot-outline-metrics.json`, `docs/text-rendering.md`).
+   *
+   * THE EDGE THAT LEAVES: a consumer drawing a spread run as the ONLY ink — an outline with no fill
+   * composited over it — now gets uncorrected coverage for that text and no way to ask for
+   * otherwise. That is the intended picture for a stroke and the wrong one for a glyph body, so a
+   * caller in that position should draw the fill it is standing in for. `gamma` is NOT gated and
+   * remains available for a deliberate transfer curve over both passes.
+   */
+  stemDarkening: boolean;
+}
+/** Stem darkening on, gamma neutral. What a renderer built without a `contrast` option gets. */
+declare const HB_GPU_CONTRAST_DEFAULT: HbGpuContrast;
+/**
+ * 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.
+ */
+declare const HB_GPU_CONTRAST_NONE: HbGpuContrast;
+interface HbGpuRendererOptions {
+  /**
+   * The context to draw in. NOT created here and never destroyed here.
+   *
+   * It must have been created with `premultipliedAlpha: true` — see this file's header. Nothing
+   * can check that from inside (`getContextAttributes` reports what was ASKED for, and the failure
+   * is a picture that is merely darker), so it is stated rather than validated.
+   */
+  gl: WebGL2RenderingContext;
+  /**
+   * The extent of OBJECT SPACE — the units {@link HbGpuRenderer.push} takes, y measured DOWN.
+   *
+   * This pair builds the design->clip projection and nothing else. On a standalone canvas it is
+   * the device-pixel size and equals the framebuffer pair below; on a DPR-scaled stage it is the
+   * scene's own coordinate extent (`packages/canvas/src/present.ts`'s `designWidth`), and the two
+   * pairs differ by the ratio.
+   */
+  designWidth: number;
+  designHeight: number;
+  /**
+   * The ACHIEVED drawing-buffer size, in DEVICE pixels. Defaults to the design pair.
+   *
+   * NOT THE SAME NUMBER AS THE DESIGN PAIR, and the default is only correct for a stage whose
+   * device-pixel ratio is 1. This pair is `u_viewport`, which is what `hb_gpu_dilate` measures half
+   * a SCREEN pixel against — see this file's header for what feeding it design units does.
+   *
+   * PASS `gl.drawingBufferWidth`, not the size you asked the canvas for. Setting `canvas.width`
+   * only REQUESTS an allocation and an implementation may hand back less, and a viewport that is
+   * wrong by a few pixels is a dilation that is wrong by a fraction of one — a rim of clipped
+   * antialiasing around every glyph rather than anything that looks like a size error.
+   */
+  framebufferWidth?: number;
+  framebufferHeight?: number;
+  /**
+   * Atlas capacity in TEXELS. Rounded up to a whole number of {@link HbGpuRenderer.atlasWidth}-wide
+   * rows.
+   *
+   * Default 256 rows = 1 Mi texels = 8 MiB, which holds ~1500 Han outlines at the ~5.4 KB the
+   * prediction expects. Sized in texels rather than bytes because that is the unit the shader
+   * indexes in and the unit the allocator wraps in.
+   */
+  atlasTexels?: number;
+  /**
+   * Give each DILATION TAP the same five-sample average `_hb_gpu_slug` gives a fill below ppem 16.
+   *
+   * **Default `false`, and that default is a measured trade rather than an oversight.**
+   *
+   * WHAT IT COSTS TO LEAVE ON. `hb_gpu_spread_tap` mirrors `_hb_gpu_slug`, so below ppem 16 one ring
+   * tap becomes FIVE `_hb_gpu_slug_single` evaluations — and a dilated fragment takes up to 65 taps.
+   * Measured on S9's `text-render` scenario (RTX 2060, 1280x800 at DPR 1, 40 outlined runs at 14 px,
+   * `outlinePx` 6): **12.27 Hz with it on, 70.47 Hz with it off**, 5.74x, and 8.05x at `outlinePx`
+   * 10. The font-size ladder isolates it — the same 3 px radius and the same tap set (47 steps when
+   * that was measured, 50 under the budget split that replaced the per-ring clamp) reads 17.44 Hz at
+   * `fontSize` 18 and 74.76 at 20, because 20 is where the ppem the shader computes crosses 16 and
+   * the branch stops firing. It is one branch, not the tap count: capping the rings and steps at
+   * 3x12 bought only 1.5x, and 2x8 bought 2.3x by punching holes through thin features.
+   *
+   * WHY IT IS DEFENSIBLE TO LEAVE OFF, which is a claim about pixels and is pinned by
+   * `test/glyphPixelXvfb.test.ts`'s low-ppem pair. The outline is a solid silhouette that a fill is
+   * then drawn on top of, so the only thing the taps decide is its OUTER rim; a max over ~47 taps is
+   * itself a smoothing operator; and the rim of a thick outline is the least legible place in a
+   * glyph. Measured at 14 px, rotated 10 degrees, spread 3, both programs on one GPU in one frame:
+   * the two differ on **267 pixels, RMS 33.4 levels of 255, worst 85** — and the one WITHOUT the
+   * MSAA is the one closer to an 8x dilated reference (rim RMS 77.9 against 85.1, ink 36102 against
+   * 30192 where the ideal grown shape is 58081). The extra smoothing was deepening a shortfall, not
+   * repairing one: `max` over coverage cannot exceed the peak coverage near a fragment, and at
+   * ppem 14 a Han glyph's strokes never reach 1, so the outline is a translucent mottle at ~60% of
+   * the ideal either way. That is the honest shape of this trade — not "5.74x for a slightly
+   * coarser rim" but "5.74x for a differently-wrong outline at a size where the outline is already
+   * wrong". Above ppem 16 it is free in both directions: the blend weight is
+   * `smoothstep (16, 8, ppem)`, which is exactly 0 there, so NO pixel of text at or above ppem 16
+   * can change — measured, by widening the gate to `ppem < 200` and reading a byte-identical frame.
+   *
+   * WHAT IT DOES NOT TOUCH, structurally. The FILL's coverage is `hb_gpu_draw` -> `_hb_gpu_slug`
+   * inside the vendored library, guarded by the library's own `HB_GPU_NO_MSAA`. This flag defines
+   * `HB_GPU_SPREAD_TAP_NO_MSAA`, a different name that only this file's function reads, so no
+   * setting of it can reach the fill. `spread 0` never calls the tap at all.
+   *
+   * Set `true` for very small outlined text where the rim matters more than the frame budget.
+   */
+  spreadTapMsaa?: boolean;
+  /**
+   * The contrast curve applied to the FINAL coverage. Defaults to {@link HB_GPU_CONTRAST_DEFAULT},
+   * which has stem darkening ON.
+   *
+   * PASS {@link HB_GPU_CONTRAST_NONE} IF YOU ARE MEASURING FIDELITY, and only then. See
+   * {@link HbGpuContrast} for the whole argument.
+   */
+  contrast?: HbGpuContrast;
+  /**
+   * Store model/colour/spread beside every glyph so adjacent runs may share one draw. Off by
+   * default: the established renderer keeps its 40-byte record and uniform state unchanged.
+   */
+  perInstanceRunState?: boolean;
+  /**
+   * Where a refusal goes.
+   *
+   * `createHbGpuRenderer` returns `null` rather than throwing, following `createCanvasStage`, so a
+   * consumer can fall back to a DOM text path. But a renderer that declined silently reports as a
+   * cheap one — in a perf arm literally so — so every `null` and every declined upload also comes
+   * through here with a reason a human can act on.
+   */
+  onError?(failure: HbGpuFailure): void;
+}
+interface HbGpuRenderer {
+  /** The borrowed context. Owned by the embedder; `dispose` does not touch it. */
+  readonly gl: WebGL2RenderingContext;
+  /**
+   * The atlas width this instance actually built — NOT necessarily {@link ATLAS_WIDTH}.
+   *
+   * WebGL2 guarantees only 2048, so a device can force a narrower texture. The shader gets this as
+   * `hb_gpu_atlas_width` and the row-wrap arithmetic uses it, so a non-4096 width is correct and
+   * merely costs more `texSubImage2D` calls per blob.
+   */
+  readonly atlasWidth: number;
+  /**
+   * True between {@link notifyContextLost} and a successful {@link rebuild}.
+   *
+   * While it is true every method here is a no-op that touches no GL: `upload` returns `null`,
+   * `push` skips, `end` reports a zero frame. Nothing polls `gl.isContextLost()` — that is a query
+   * in the hot path for an event the embedder already receives — so a consumer that does not wire
+   * `webglcontextlost` through to {@link notifyContextLost} will draw into dead objects forever,
+   * which is permanently blank text with no signal. That wiring is not optional.
+   */
+  readonly contextLost: boolean;
+  /**
+   * Register a face, taking its `upem`, and get the namespace its glyph keys carry.
+   *
+   * THE FONT IS RETAINED, and that is the memory decision this package makes. A context loss
+   * destroys the atlas texture, so {@link rebuild} has to be able to put the same texels back at
+   * the same offsets — and the two ways to do that are to keep a copy of every uploaded blob or to
+   * keep the encoder that produced them. This keeps the ENCODER: the embedder already holds the
+   * `HbGpuFont` (it cannot encode without one), so the retained reference costs zero additional
+   * bytes, where retaining blobs would hold a second resident copy of the glyph data forever —
+   * 1.3 MB on S9's 300-glyph Han pool — to make a once-in-a-session event faster. The cost is paid
+   * on restore instead: `rebuild` re-runs `hb_gpu_draw_encode` for every resident glyph (~180 ms
+   * for that same pool).
+   *
+   * Consequence, stated because it is a lifetime rule and not a preference: the font must outlive
+   * the renderer, or a rebuild silently drops that face's glyphs.
+   *
+   * `null` when the font's `upem` is not usable — see {@link HbGpuFailureReason} `"degenerate-upem"`.
+   */
+  registerFace(font: HbGpuFont, label?: string): HbGpuFace | null;
+  /**
+   * Upload one encoded glyph of `face`, or return the slot it already has.
+   *
+   * `null` for a glyph with no ink — a space encodes to a zero-length blob, which is a legitimate
+   * result and must not become a zero-texel allocation — and also for a blob this renderer
+   * declines (malformed, or larger than the whole atlas), which is reported through `onError`.
+   *
+   * THROWS in exactly one case; see {@link HbGpuRendererOptions.atlasTexels} and the in-use guard
+   * inside `allocate`.
+   */
+  upload(face: HbGpuFace, glyphId: number, glyph: EncodedGlyph): GlyphSlot | null;
+  /**
+   * The live slot for a glyph that is already resident, or `null` when it is not.
+   *
+   * THE CHEAP HALF OF {@link HbGpuRenderer.upload}, AND THE REASON AN EMBEDDER CAN KEEP HANDLES
+   * INSTEAD OF SLOTS. A retained draw list records a glyph as an id and has to turn it back into a
+   * `GlyphSlot` every frame; the only way to do that used to be `upload`, which needs an
+   * {@link EncodedGlyph} — and encoding a Han working set costs ~180 ms, so a per-frame encode is
+   * not a path anybody can take. This is a map lookup and a touch.
+   *
+   * `null` means "never uploaded, or evicted", and those are the same answer for a caller: encode
+   * and `upload` again. It is NOT an error and nothing is reported — a ring allocator evicting is
+   * the mechanism working.
+   *
+   * The returned slot is built by the same expression `upload` uses, so a resolved slot and a
+   * freshly uploaded one cannot differ; in particular it carries the CURRENT
+   * {@link GlyphSlot.generation}, which is what makes it safe to `push`.
+   */
+  resolve(face: HbGpuFace, glyphId: number): GlyphSlot | null;
+  /** Start a frame. */
+  begin(): void;
+  /**
+   * Queue one glyph, its em ORIGIN (the pen position, on the baseline) at object-space `(x, y)`,
+   * at `pixelsPerEm` object units per em.
+   *
+   * Object space is device pixels and y measures DOWN, matching every other renderer in the repo.
+   * Rotation is not here on purpose: it belongs in {@link setModel}, so that one matrix rotates the
+   * quad AND is seen by `hb_gpu_dilate`, which computes its half-pixel dilation in SCREEN space
+   * through that same matrix. A quad rotated on the CPU behind the shader's back would be dilated
+   * along the wrong axes.
+   *
+   * A slot whose allocation has been evicted is SKIPPED and counted — see {@link GlyphSlot.generation}.
+   */
+  push(slot: GlyphSlot, x: number, y: number, pixelsPerEm: number): void;
+  /** Object-space 2x3 (`[xx, xy, yx, yy, tx, ty]`), applied before the projection. */
+  setModel(model: ArrayLike<number>): void;
+  /** STRAIGHT rgba in 0..1. The fragment premultiplies it, once. */
+  setColor(r: number, g: number, b: number, a: number): void;
+  /**
+   * Grow every glyph of the next frame outward by `px` OBJECT units. `0` (the default) is the
+   * plain fill.
+   *
+   * WHAT AN OUTLINED LABEL IS: this run in the outline colour at `spread`, then the SAME run in the
+   * fill colour at spread 0, in that order. A centred `ctx.strokeText` of width `W` reaches `W / 2`
+   * outward, so a caller matching one passes `W / 2`; the arithmetic is the caller's, because only
+   * the caller knows whether its stroke is centred, inner or outer.
+   *
+   * A DILATION FILLS THE INTERIOR AND A CENTRED STROKE DOES NOT, AND THAT DIFFERENCE IS REAL. This
+   * paints the whole glyph plus a band of `spread` around it, where a stroke paints only a band
+   * straddling the contour. Under an OPAQUE fill the two are pixel-identical, because the fill
+   * covers every pixel they disagree about. Under a TRANSLUCENT fill they are not: the outline
+   * colour shows through the glyph's middle here and would not through a stroke. That is the honest
+   * limit of a coverage-max dilation and there is no distance field to do better with — see
+   * {@link FRAGMENT_MAIN}.
+   *
+   * OBJECT UNITS, BEFORE {@link HbGpuRenderer.setModel}, matching every other length `push` takes.
+   * A model that scales scales the outline with the text, which is what a caller rotating a label
+   * wants.
+   *
+   * IT PERSISTS, exactly like {@link HbGpuRenderer.setModel} and {@link HbGpuRenderer.setColor} —
+   * `begin` does not reset it. The failure that buys is worth stating: a caller that sets a spread
+   * for one run and does not clear it draws every LATER run fat, which looks like a font-weight bug
+   * rather than a missing call. Per-run callers should set it per run, which is what
+   * `packages/canvas`'s glyph pass does.
+   *
+   * A NON-ZERO SPREAD ALSO TURNS STEM DARKENING OFF for that run, whatever
+   * {@link HbGpuContrast.stemDarkening} says — Godot's outline carries no contrast curve, and one
+   * on a dilated rim reads as a halo. The reason is under that field; the pair "outline then fill"
+   * above is unaffected, because the fill run is the one that keeps the correction.
+   *
+   * COST. Bounded, but not free: a fragment that is neither solid ink nor near any evaluates up to
+   * 65 coverage taps (and five times that below ppem 16), and the quad it does so over grows by
+   * `spread` on every side. Beyond roughly 4 device pixels of radius the tap ceiling is reached —
+   * {@link HB_GPU_SPREAD_MAX_TAPS} — and the dilated rim starts to scallop: measured against a Godot
+   * 4.5.1 golden at radius 12, the 50% contour wobbles 0.17 px where the engine's wobbles 0.11. The
+   * cost does not grow past that point; only the scallop does. Negative and non-finite values are
+   * clamped to 0 rather than reported: this is a per-run hot-path setter with no error channel.
+   */
+  setSpread(px: number): void;
+  /**
+   * Re-state both sizes after the embedder resized its stage or its drawing buffer.
+   *
+   * Does NOT call `gl.viewport` — this renderer never touches it. It updates the design->clip
+   * projection (from the DESIGN pair) and the `u_viewport` the dilation is measured in (from the
+   * FRAMEBUFFER pair), both of which must describe the viewport the embedder will have set by the
+   * time `end` runs. The framebuffer pair defaults to the design pair, which is right only at a
+   * device-pixel ratio of 1 — see {@link HbGpuRendererOptions.framebufferWidth}.
+   */
+  setViewport(designWidth: number, designHeight: number, framebufferWidth?: number, framebufferHeight?: number): void;
+  /**
+   * Submit. Returns what the frame cost.
+   *
+   * WHAT THIS DOES NOT DO, because the context is borrowed: it does not set `gl.viewport` and it
+   * does not clear. Both were here while this file owned a stage, and both are actively wrong in a
+   * shared context — a clear inside a glyph pass erases everything the embedder's executor already
+   * drew, and a viewport call silently overrides a scissored or letterboxed pass.
+   *
+   * WHAT IT LEAVES DIRTY, exhaustively, so an embedder's restore code can be written against it.
+   * On a frame that drew anything (`instances > 0`):
+   *
+   *   - `BLEND` is ENABLED, `blendEquation` is `FUNC_ADD`, `blendFunc` is
+   *     `(ONE, ONE_MINUS_SRC_ALPHA)` — premultiplied MIX. Note `blendFunc`/`blendEquation`, not
+   *     the `*Separate` forms, so both the RGB and the alpha halves are set.
+   *   - The current program is this renderer's.
+   *   - `ARRAY_BUFFER` is bound to the instance buffer.
+   *   - `ACTIVE_TEXTURE` is `TEXTURE0` and `TEXTURE_BINDING_2D` on unit 0 is the atlas.
+   *   - `VERTEX_ARRAY_BINDING` is null (unbound, not restored to whatever was bound before —
+   *     WebGL2 has no cheap way to read it back).
+   *   - Uniforms of this renderer's program only — `u_viewProjection`, `u_viewport`, `u_gamma`,
+   *     `u_stemDarken`, `hb_gpu_atlas` and `hb_gpu_atlas_width`. Per-run model, colour and spread
+   *     are captured into each instance record; their setters still persist until replaced and
+   *     `begin` deliberately does not reset them (see {@link HbGpuRenderer.setSpread}).
+   *
+   * Untouched: viewport, scissor box and `SCISSOR_TEST`, clear colour, depth/stencil state,
+   * framebuffer bindings, the three unpack flags — `UNPACK_ALIGNMENT`, `UNPACK_FLIP_Y_WEBGL` and
+   * `UNPACK_PREMULTIPLY_ALPHA_WEBGL`, all saved and restored around every upload — and every
+   * texture unit but 0.
+   *
+   * On an empty frame it returns immediately and leaves ALL of the above untouched too, which is
+   * why an embedder must restore unconditionally rather than only when `instances > 0`.
+   */
+  end(): {
+    instances: number;
+    drawCalls: number;
+  };
+  /**
+   * The context is gone: drop every GL handle WITHOUT calling into GL to free it.
+   *
+   * Call this from `webglcontextlost` (`packages/canvas/src/present.ts` offers exactly that hook,
+   * and `preventDefault` on that event is what makes a restore possible at all). The allocation
+   * table survives — offsets, faces and glyph ids — because {@link rebuild} puts the same texels
+   * back at the same offsets, which is what keeps every {@link GlyphSlot} the embedder is holding
+   * valid across the loss.
+   */
+  notifyContextLost(): void;
+  /**
+   * The context is back: recreate the program, the buffers, the VAO and the texture, then re-encode
+   * and re-upload every resident glyph at the offset it already had.
+   *
+   * SAME OFFSETS, DELIBERATELY. Repacking would be simpler and would invalidate every slot the
+   * embedder holds — which the generation guard would then turn into a silently empty frame rather
+   * than garbage, but empty is still wrong. Re-materialising the atlas byte for byte means a
+   * restore needs no cooperation from the caller beyond this one call.
+   *
+   * Returns `false` (and reports) if the GL objects could not be rebuilt. A face whose font has
+   * been destroyed, or a glyph that no longer encodes to the same length, loses its allocation:
+   * those slots then fail the generation check and are skipped rather than drawn wrong.
+   */
+  rebuild(): boolean;
+  readonly atlas: AtlasStats;
+  readonly blobs: BlobStats;
+  /** Delete this renderer's GL objects. Does NOT touch the context or the canvas. */
+  dispose(): void;
+}
+declare function createHbGpuRenderer(module: HbGpu, options: HbGpuRendererOptions): HbGpuRenderer | null;
+//#endregion
+export { ATLAS_WIDTH, AtlasStats, BlobStats, FRAGMENT_MAIN, GlyphSlot, HB_GPU_CONTRAST_DEFAULT, HB_GPU_CONTRAST_NONE, HB_GPU_SPREAD_MAX_TAPS, HbGpuContrast, HbGpuFace, HbGpuRenderer, HbGpuRendererOptions, createHbGpuRenderer };
+//# sourceMappingURL=webgl.d.ts.map

package/dist/webgl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webgl.d.ts","names":[],"sources":["../src/webgl.ts"],"mappings":";;;;;AA+EA;;;;AAAwB;AAgExB;cAhEa,WAAA;;;AAgEsB;AA6dnC;;;;AAA0B;AA4T1B;;;;;;;;AAMe;AAIf;;;;cAnyBa,sBAAA;AAAA,cA6dA,aAAA;;;;;;;;;;;AAuWL;AAGR;UA9CiB,SAAA;;WAEN,EAAA;EAmDT;EAAA,SAjDS,KAAA;EA4DT;EAAA,SA1DS,IAAA;AAAA;;UAIM,SAAA;EAoEf;;AAAU;AAGZ;EAlEE,MAAA;EACA,OAAA;EAiEwB;;;;EA5DxB,GAAA;EAqEa;AAwBf;;;;AAyCe;AAIf;;;;EA/HE,UAAA;EA4IW;EA1IX,GAAA;;EAEA,IAAA;EA2IA;EAzIA,IAAA;EACA,IAAA;EACA,IAAA;EACA,IAAA;EAgOW;EA9NX,MAAA;AAAA;AAAA,UAGe,UAAA;EA2If;;;;;;EApIA,SAAA;EA4MA;;;;;;;;EAnMA,gBAAA;EA4Ne;EA1Nf,OAAA;EACA,UAAA;EACA,cAAA;EA+PmB;EA7PnB,SAAA;EAyQQ;EAvQR,KAAA;EA0QG;;;;;;;EAlQH,UAAA;AAAA;AAAA,UAGe,SAAA;EA2MF;EAzMb,MAAA;EA2NS;EAzNT,UAAA;EA4OmB;;;;EAvOnB,aAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;UAwBe,aAAA;EAmQK;;;;;;;;;;;;;EArPpB,KAAA;EAsWA;;;;;;;AAIO;AA+FT;;;;;;;;;;;;;;AAGgB;;;;EAjbd,aAAa;AAAA;;cAIF,uBAAA,EAAyB,aAGpC;;;;;;;;;cAUW,oBAAA,EAAsB,aAGjC;AAAA,UAEe,oBAAA;;;;;;;;EAQf,EAAA,EAAI,sBAAA;;;;;;;;;EASJ,WAAA;EACA,YAAA;;;;;;;;;;;;;EAaA,gBAAA;EACA,iBAAA;;;;;;;;;EASA,WAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAuCA,aAAA;;;;;;;;EAQA,QAAA,GAAW,aAAA;;;;;EAKX,mBAAA;;;;;;;;;EASA,OAAA,EAAS,OAAA,EAAS,YAAA;AAAA;AAAA,UAGH,aAAA;;WAEN,EAAA,EAAI,sBAAA;;;;;;;;WAQJ,UAAA;;;;;;;;;;WAUA,WAAA;;;;;;;;;;;;;;;;;;;EAmBT,YAAA,CAAa,IAAA,EAAM,SAAA,EAAW,KAAA,YAAiB,SAAA;;;;;;;;;;;EAW/C,MAAA,CACE,IAAA,EAAM,SAAA,EACN,OAAA,UACA,KAAA,EAAO,YAAA,GACN,SAAA;;;;;;;;;;;;;;;;;;EAkBH,OAAA,CAAQ,IAAA,EAAM,SAAA,EAAW,OAAA,WAAkB,SAAA;;EAE3C,KAAA;;;;;;;;;;;;;EAaA,IAAA,CAAK,IAAA,EAAM,SAAA,EAAW,CAAA,UAAW,CAAA,UAAW,WAAA;;EAE5C,QAAA,CAAS,KAAA,EAAO,SAAA;;EAEhB,QAAA,CAAS,CAAA,UAAW,CAAA,UAAW,CAAA,UAAW,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAyC1C,SAAA,CAAU,EAAA;;;;;;;;;;EAUV,WAAA,CACE,WAAA,UACA,YAAA,UACA,gBAAA,WACA,iBAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAkCF,GAAA;IAAS,SAAA;IAAmB,SAAA;EAAA;;;;;;;;;;EAU5B,iBAAA;;;;;;;;;;;;;;EAcA,OAAA;EAAA,SACS,KAAA,EAAO,UAAA;EAAA,SACP,KAAA,EAAO,SAAA;;EAEhB,OAAA;AAAA;AAAA,iBA+Fc,mBAAA,CACd,MAAA,EAAQ,KAAA,EACR,OAAA,EAAS,oBAAA,GACR,aAAA"}