@godot-scene-web/hb-gpu 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tomás Fox
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,305 @@
+//#region src/index.d.ts
+/**
+ * Every way this package can decline, as a stable string.
+ *
+ * A REASON CHANNEL EXISTS BECAUSE THE FUNCTIONS RETURN `null`. Construct-or-null is the repo's
+ * idiom (`createCanvasStage`) and the right one for a shipped renderer — a consumer that cannot
+ * have the GPU glyph path falls back to its DOM one. But a component that declined silently
+ * reports as a CHEAP one, in a perf table literally so, so every `null` is paired with one of
+ * these plus a sentence naming the failure mode.
+ *
+ * String union rather than an enum so a report can carry it verbatim and a `switch` over it is
+ * exhaustively checked.
+ */
+type HbGpuFailureReason = /** `_malloc` returned 0. The heap could not grow; the write would have gone to the null page. */"out-of-memory" /** Zero-length face bytes — usually a detached ArrayBuffer that was transferred elsewhere. */ | "empty-face" /** HarfBuzz would not take the bytes as a face, or the face's `upem` is unusable. */ | "face-rejected" /** `hb_gpu_draw_create_or_fail` returned null. */ | "encoder-unavailable" /** A `upem` that would make every glyph scale `Infinity` or `NaN`. */ | "degenerate-upem"
+/**
+ * A `contrast.gamma` that is not a finite positive number. Not fatal — the exponent falls back
+ * to 1 and the renderer builds.
+ *
+ * Refused rather than passed through because `pow (cov, gamma)` with a NaN or an infinity is a
+ * NaN alpha, and a NaN alpha through a premultiplied MIX blend is an undefined framebuffer over
+ * the glyph's whole quad on some drivers and a black box on others. Neither reads as "somebody
+ * typed a bad number into a renderer option".
+ */
+| "degenerate-contrast" /** The WebGL2 context was lost, or was already lost when handed over. */ | "context-lost" /** `gl.create*` returned null. */ | "gl-object" | "shader-compile" | "program-link" /** `MAX_TEXTURE_SIZE` is too small for an atlas at all. */ | "texture-size" /** `MAX_TEXTURE_SIZE` forced a narrower or shorter atlas than asked for. Not fatal. */ | "atlas-clamped" /** A blob whose length is not a whole number of texels. */ | "blob-malformed"
+/**
+ * `hb_feature_from_string` would not parse one of the feature strings handed to `shape`.
+ *
+ * Its own failure mode is the reason this is a refusal and not a warning: HarfBuzz zeroes the
+ * struct and returns false, and a zeroed `hb_feature_t` is tag 0 with value 0 over the whole
+ * run — which shapes, and shapes WITHOUT the feature the caller asked for. A typo in `"-liga"`
+ * would otherwise be a ligature quietly still applied.
+ */
+| "feature-malformed" /** One glyph larger than the entire atlas. */ | "blob-too-large" /** A face handle that this renderer never issued. */ | "face-unregistered" /** A context restore that could not put every resident glyph back. Not fatal. */ | "rebuild-incomplete";
+/** A refusal, with the reason machine-readable and the sentence written for a human. */
+interface HbGpuFailure {
+  reason: HbGpuFailureReason;
+  /** Always prefixed `hb-gpu: `, and always says what the failure LOOKS like, not just its name. */
+  message: string;
+}
+interface HbGpuOptions {
+  /** Where a refusal goes. See {@link HbGpuFailureReason}. */
+  onError?(failure: HbGpuFailure): void;
+}
+/** Values of `hb_gpu_shader_stage_t`. */
+declare const HB_GPU_SHADER_STAGE_VERTEX = 0;
+declare const HB_GPU_SHADER_STAGE_FRAGMENT = 1;
+/** `HB_GPU_SHADER_LANG_GLSL`. WebGL2 is the only backend this package has a pipeline for. */
+declare const HB_GPU_SHADER_LANG_GLSL = 1;
+/** Bytes per encoded texel: RGBA16I, and the unit the atlas allocator counts in. */
+declare const HB_GPU_TEXEL_BYTES = 8;
+/**
+ * A glyph's ink box, in FONT UNITS at the font's scale, y-UP — HarfBuzz's convention, unaltered.
+ *
+ * `height` IS NEGATIVE and `yBearing` is the ink's TOP. Restated here because it is the single most
+ * common way to get a glyph quad upside down, and because `hb_gpu_draw_encode` floors/ceils these
+ * to whole font units, so the box is always at least the ink and never less.
+ */
+interface HbGpuGlyphExtents {
+  xBearing: number;
+  yBearing: number;
+  width: number;
+  height: number;
+}
+/** One encoded glyph: the texel stream to upload, and the box to draw it in. */
+interface EncodedGlyph {
+  /** RGBA16I texels, little-endian, exactly as `hb_gpu_draw_encode` produced them. */
+  texels: Uint8Array;
+  extents: HbGpuGlyphExtents;
+}
+/**
+ * `hb_direction_t`, as the four names rather than the four integers.
+ *
+ * A STRING UNION AND NOT A NUMBER, because `hb_buffer_set_direction` has no error channel: hand it
+ * anything outside 4..7 and the buffer's direction is INVALID, `guess_segment_properties` then
+ * fills in whatever it likes, and the run comes out laid the wrong way with nothing said. The
+ * mapping is an ABI constant, kept here the way `HB_MEMORY_MODE_READONLY` is.
+ */
+type HbGpuDirection = "ltr" | "rtl" | "ttb" | "btt";
+/**
+ * What a caller can tell the shaper about a run.
+ *
+ * EVERY FIELD IS OPTIONAL AND THE DEFAULT IS `hb_buffer_guess_segment_properties`, which infers
+ * script from the code points and direction from the script. That is the right default and a poor
+ * guarantee: it cannot know that a Latin quotation inside an Arabic paragraph is still RTL, and it
+ * has no opinion at all about language. Anything set here is set BEFORE the guess, and the guess
+ * only fills what is still unset — so an explicit value always wins.
+ */
+interface HbGpuShapeOptions {
+  /** Overrides the direction the script implies. */
+  direction?: HbGpuDirection;
+  /** An ISO 15924 tag — `"Hans"`, `"Latn"`, `"Arab"`. Case is canonicalised by HarfBuzz. */
+  script?: string;
+  /**
+   * A BCP 47 tag — `"zh-Hans"`, `"en"`, `"tr"`.
+   *
+   * Left unset it stays unset: this build has `HB_NO_SETLOCALE`, so there is no ambient locale to
+   * fall back to and the font's `dflt` language system is used. Set it when the face has a
+   * language-specific feature the run needs (Turkish dotless i, Serbian Cyrillic italics).
+   */
+  language?: string;
+  /**
+   * OpenType features in `hb-shape`'s own syntax: `"kern"`, `"-liga"`, `"ss01"`, `"aalt[3:5]=2"`.
+   *
+   * Parsed by `hb_feature_from_string`, and a string it refuses fails the whole call with
+   * `"feature-malformed"` rather than being dropped — see that reason.
+   */
+  features?: readonly string[];
+}
+/**
+ * One glyph of a shaped run, in the font's own units, y-UP — HarfBuzz's output, unconverted.
+ *
+ * See {@link HbGpuFont.shape} for the pen arithmetic these five numbers go into; getting the
+ * offset/advance split or the y sign wrong produces text that looks plausible and is mis-spaced.
+ */
+interface HbGpuShapedGlyph {
+  /** Glyph id in this face. The same id `encode` takes. */
+  glyphId: number;
+  /**
+   * Where this glyph came from in `text`, as a UTF-16 code-unit index — i.e. an index you can
+   * hand straight to `String.prototype.slice`, because the text goes in through
+   * `hb_buffer_add_utf16` and a JS string already is UTF-16.
+   *
+   * Not one per glyph and not monotonic in general: several glyphs share a cluster when one
+   * character became many, and many characters share one when a ligature ate them.
+   */
+  cluster: number;
+  /** How far the pen moves AFTER this glyph. */
+  xAdvance: number;
+  yAdvance: number;
+  /** Added to the pen for THIS glyph only, and never accumulated. */
+  xOffset: number;
+  yOffset: number;
+}
+interface HbGpuFont {
+  /** Units per em of the face — the scale outlines and extents are expressed in. */
+  readonly upem: number;
+  /** Glyph id for a code point, or 0 (`.notdef`) when the face has no cmap entry. */
+  glyphFor(codepoint: number): number;
+  /**
+   * Shape a run: text in, positioned glyph ids out.
+   *
+   * UNITS ARE THE FONT'S OWN AND NOT PIXELS, which is the sentence to read twice. `createFont`
+   * calls `hb_font_set_scale(font, upem, upem)` — see there for why — so every number that comes
+   * back is in font units at that scale, y is UP, and nothing has been converted. Same contract as
+   * {@link HbGpuGlyphExtents}, for the same reason: this package cannot know the caller's pixel
+   * size, and a half-applied convention is worse than none.
+   *
+   * THE PEN ARITHMETIC, WHICH IS THE PART THAT GOES SUBTLY WRONG. With `toPx = fontSizePx / upem`,
+   * a horizontal run is laid out:
+   *
+   * ```ts
+   * let pen = 0;
+   * for (const glyph of run) {
+   *   const xPx = (pen + glyph.xOffset) * toPx; // offset positions THIS glyph...
+   *   const yPx = -glyph.yOffset * toPx; //         ...and y flips, because canvases are y-DOWN
+   *   pen += glyph.xAdvance; //                     ...and only the advance moves the pen
+   * }
+   * ```
+   *
+   * The offset does not accumulate and the advance is applied AFTER the glyph. That is
+   * byte-for-byte what `perf-harness/src/scenarios/text-hb.ts` runs over npm `harfbuzzjs`'s
+   * output, whose pen positions are in turn proven identical to the independently written
+   * `hb-atlas` arm's — so matching it is what makes a run shaped here land exactly where every
+   * other arm in that round puts it. `test/shape.test.ts` asserts the two agree, glyph for glyph.
+   *
+   * `[]` FOR EMPTY TEXT AND `null` FOR A FAILURE, which are different answers to different
+   * questions. An empty run is legal; a run that could not be shaped is not, and it would
+   * otherwise render as a page with some of its text quietly missing.
+   *
+   * An array of objects rather than a flat typed array: shaping is a startup cost in every
+   * consumer here (each run is shaped once and baked), each field is read exactly once on the way
+   * into a pen position, and a per-glyph object is field-for-field what npm `harfbuzzjs` hands
+   * back — which is what makes the cross-check, and any port off it, a direct comparison rather
+   * than a re-derivation.
+   */
+  shape(text: string, options?: HbGpuShapeOptions): HbGpuShapedGlyph[] | null;
+  /**
+   * Encode one glyph. `null` when the encoder failed; a zero-length `texels` when the glyph has no
+   * ink (a space), which is a different thing and must not be uploaded.
+   */
+  encode(glyphId: number): EncodedGlyph | null;
+  destroy(): void;
+}
+interface HbGpu {
+  /**
+   * Bytes of wasm heap this module currently holds.
+   *
+   * `HEAPU8.byteLength` rather than an instrumented allocator: it reports what the heap has
+   * actually grown to, font copy and encoder scratch included, which is the number a consumer
+   * weighs against the arm's other costs.
+   *
+   * IT IS A CEILING, NOT A HIGH-WATER MARK, AND `build.sh` HAD TO BE CHANGED TO MAKE IT USEFUL.
+   * A wasm heap is only ever as small as its initial reservation, so this reads whatever
+   * `-sINITIAL_MEMORY` asked for until something exceeds it. At emscripten's default it read
+   * 16.19 MiB for an 826 KB face — about 8x the truth. The build asks for 2 MiB, re-measured when
+   * shaping landed: both S9 fixture faces, 2080 shaped runs and 340 encoded outlines high-water at
+   * 1.125 MiB and never reach the reservation. See `build.sh` for the whole ladder.
+   *
+   * AND IT IS NOW ONE NUMBER RATHER THAN TWO. A caller that shapes here has no second wasm heap to
+   * add to it; the arrangement this replaces held every face in both.
+   */
+  readonly heapBytes: number;
+  /**
+   * HarfBuzz's own GLSL for one stage: the shared library half plus the draw-renderer half,
+   * concatenated in the order `demo-shader.cc` uses. No `main()` — see this file's header.
+   */
+  shaderLibrary(stage: number): string;
+  /**
+   * Copy a face into the wasm heap and open an encoder over it, or `null`.
+   *
+   * `null` RATHER THAN A THROW, and the throw it replaces leaked: the old code allocated the face
+   * copy, created a blob, a face and a font, and then threw when the encoder came back null —
+   * losing all four for the life of the module. Every failure path below unwinds in the reverse
+   * order `destroy` uses. The reason reaches {@link HbGpuOptions.onError}.
+   */
+  createFont(bytes: Uint8Array): HbGpuFont | null;
+  destroy(): void;
+}
+/**
+ * The subset of emscripten's module object this package uses.
+ *
+ * Hand-written rather than generated: `-sEXPORTED_FUNCTIONS=@hb-gpu.symbols` already fixes the
+ * list, and a type that restates it is a second place the two can disagree — loudly, at the call
+ * site, which is where a missing export should be noticed.
+ */
+interface HbGpuWasmExports {
+  HEAPU8: Uint8Array;
+  HEAP32: Int32Array;
+  /** The view `hb_buffer_add_utf16`'s text is written through. See `build.sh`. */
+  HEAPU16: Uint16Array;
+  UTF8ToString(pointer: number): string;
+  _malloc(bytes: number): number;
+  _free(pointer: number): void;
+  _hb_blob_create(data: number, length: number, mode: number, userData: number, destroy: number): number;
+  _hb_blob_get_data(blob: number, lengthOut: number): number;
+  _hb_blob_get_length(blob: number): number;
+  _hb_blob_destroy(blob: number): void;
+  _hb_face_create(blob: number, index: number): number;
+  _hb_face_destroy(face: number): void;
+  _hb_face_get_upem(face: number): number;
+  _hb_font_create(face: number): number;
+  _hb_font_destroy(font: number): void;
+  _hb_font_set_scale(font: number, xScale: number, yScale: number): void;
+  _hb_font_get_nominal_glyph(font: number, codepoint: number, glyphOut: number): number;
+  _hb_shape(font: number, buffer: number, features: number, featureCount: number): void;
+  _hb_buffer_create(): number;
+  _hb_buffer_destroy(buffer: number): void;
+  _hb_buffer_allocation_successful(buffer: number): number;
+  _hb_buffer_clear_contents(buffer: number): void;
+  _hb_buffer_add_utf16(buffer: number, text: number, textLength: number, itemOffset: number, itemLength: number): void;
+  _hb_buffer_guess_segment_properties(buffer: number): void;
+  _hb_buffer_set_direction(buffer: number, direction: number): void;
+  _hb_buffer_set_script(buffer: number, script: number): void;
+  _hb_buffer_set_language(buffer: number, language: number): void;
+  _hb_language_from_string(text: number, length: number): number;
+  _hb_script_from_string(text: number, length: number): number;
+  _hb_feature_from_string(text: number, length: number, featureOut: number): number;
+  _hb_buffer_get_length(buffer: number): number;
+  _hb_buffer_get_glyph_infos(buffer: number, lengthOut: number): number;
+  _hb_buffer_get_glyph_positions(buffer: number, lengthOut: number): number;
+  _hb_gpu_draw_create_or_fail(): number;
+  _hb_gpu_draw_destroy(draw: number): void;
+  _hb_gpu_draw_set_scale(draw: number, xScale: number, yScale: number): void;
+  _hb_gpu_draw_glyph_or_fail(draw: number, font: number, glyph: number): number;
+  _hb_gpu_draw_encode(draw: number, extentsOut: number): number;
+  _hb_gpu_draw_clear(draw: number): void;
+  _hb_gpu_draw_reset(draw: number): void;
+  _hb_gpu_draw_recycle_blob(draw: number, blob: number): void;
+  _hb_gpu_shader_source(stage: number, lang: number): number;
+  _hb_gpu_draw_shader_source(stage: number, lang: number): number;
+}
+/** The default export of `dist/hb-gpu.mjs`, under `-sMODULARIZE=1 -sEXPORT_ES6=1`. */
+type HbGpuModuleFactory = (options: {
+  wasmBinary: ArrayBuffer | Uint8Array;
+}) => Promise<HbGpuWasmExports>;
+/**
+ * Instantiate the module.
+ *
+ * The FACTORY is a parameter rather than an import, and deliberately: `dist/hb-gpu.mjs` is a build
+ * output of `build.sh` (docker, emscripten, minutes) that `dist/` gitignores, so a static import
+ * here would make this package fail to typecheck on a fresh checkout and fail to build in CI. The
+ * caller imports the glue — it is the caller that knows whether the build has been run.
+ */
+declare function createHbGpu(factory: HbGpuModuleFactory, wasmBinary: ArrayBuffer | Uint8Array, options?: HbGpuOptions): Promise<HbGpu>;
+/**
+ * Total and per-glyph encoded bytes for a set of glyphs.
+ *
+ * THE PREDICTION UNDER TEST, made directly measurable. `docs/text-rendering.md` records it as
+ * "~5.4 KB per Han glyph against ~1.4 KB for a 38x38 R8 atlas cell", and that comparison decides
+ * the VRAM half of whether this arm is worth shipping — so it should be one call, on the real
+ * fixture face, rather than something reconstructed from a frame counter.
+ *
+ * DISTINCT glyph ids, because that is what the atlas pays for too: a Han run draws 12 glyphs and an
+ * atlas stores as many outlines as the pool has distinct members.
+ */
+declare function measureBlobBytes(font: HbGpuFont, glyphIds: Iterable<number>): {
+  glyphs: number;
+  totalBytes: number;
+  bytesPerGlyph: number;
+  minBytes: number;
+  maxBytes: number;
+};
+//#endregion
+export { EncodedGlyph, HB_GPU_SHADER_LANG_GLSL, HB_GPU_SHADER_STAGE_FRAGMENT, HB_GPU_SHADER_STAGE_VERTEX, HB_GPU_TEXEL_BYTES, HbGpu, HbGpuDirection, HbGpuFailure, HbGpuFailureReason, HbGpuFont, HbGpuGlyphExtents, HbGpuModuleFactory, HbGpuOptions, HbGpuShapeOptions, HbGpuShapedGlyph, HbGpuWasmExports, createHbGpu, measureBlobBytes };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,243 @@
+//#region src/index.ts
+/** Values of `hb_gpu_shader_stage_t`. */
+const HB_GPU_SHADER_STAGE_VERTEX = 0;
+const HB_GPU_SHADER_STAGE_FRAGMENT = 1;
+/** `HB_GPU_SHADER_LANG_GLSL`. WebGL2 is the only backend this package has a pipeline for. */
+const HB_GPU_SHADER_LANG_GLSL = 1;
+/** `HB_MEMORY_MODE_READONLY`: the blob points at our allocation and never writes to it. */
+const HB_MEMORY_MODE_READONLY = 1;
+/** Bytes per encoded texel: RGBA16I, and the unit the atlas allocator counts in. */
+const HB_GPU_TEXEL_BYTES = 8;
+/** `hb_direction_t`: HB_DIRECTION_LTR is 4 and the rest follow. */
+const HB_DIRECTION = {
+	ltr: 4,
+	rtl: 5,
+	ttb: 6,
+	btt: 7
+};
+/** `sizeof (hb_glyph_extents_t)`: four `hb_position_t`, which is `int32_t`. */
+const EXTENTS_BYTES = 16;
+/**
+* `sizeof (hb_glyph_info_t)` and `sizeof (hb_glyph_position_t)` on wasm32. Both 20, and the fact
+* that they are EQUAL is a coincidence of layout, not a rule — they are named separately so that a
+* future HarfBuzz that grows one of them cannot silently shift the other's reads.
+*
+* `hb_glyph_info_t`  = codepoint, mask, cluster, var1, var2   (5 x uint32)
+* `hb_glyph_position_t` = x_advance, y_advance, x_offset, y_offset, var (5 x int32)
+*/
+const GLYPH_INFO_BYTES = 20;
+const GLYPH_POSITION_BYTES = 20;
+/** `sizeof (hb_feature_t)`: tag, value, start, end. */
+const FEATURE_BYTES = 16;
+/** UTF-8 for the tag and feature strings. ASCII in practice; this is the correct encoder anyway. */
+const utf8 = new TextEncoder();
+/**
+* Instantiate the module.
+*
+* The FACTORY is a parameter rather than an import, and deliberately: `dist/hb-gpu.mjs` is a build
+* output of `build.sh` (docker, emscripten, minutes) that `dist/` gitignores, so a static import
+* here would make this package fail to typecheck on a fresh checkout and fail to build in CI. The
+* caller imports the glue — it is the caller that knows whether the build has been run.
+*/
+async function createHbGpu(factory, wasmBinary, options = {}) {
+	const wasm = await factory({ wasmBinary });
+	const fonts = /* @__PURE__ */ new Set();
+	const fail = (reason, message) => {
+		options.onError?.({
+			reason,
+			message: `hb-gpu: ${message}`
+		});
+		return null;
+	};
+	return {
+		get heapBytes() {
+			return wasm.HEAPU8.byteLength;
+		},
+		shaderLibrary(stage) {
+			const shared = wasm._hb_gpu_shader_source(stage, 1);
+			const draw = wasm._hb_gpu_draw_shader_source(stage, 1);
+			return (shared ? wasm.UTF8ToString(shared) : "") + (draw ? wasm.UTF8ToString(draw) : "");
+		},
+		createFont(bytes) {
+			if (bytes.byteLength === 0) return fail("empty-face", "createFont was given zero face bytes — a transferred or detached ArrayBuffer looks exactly like this, and the face would encode every glyph to nothing");
+			const dataPointer = wasm._malloc(bytes.byteLength);
+			if (!dataPointer) return fail("out-of-memory", `_malloc(${bytes.byteLength}) returned 0 — the wasm heap could not grow, and writing the face at address 0 would have corrupted the null page`);
+			wasm.HEAPU8.set(bytes, dataPointer);
+			let blob = 0;
+			let face = 0;
+			let font = 0;
+			let draw = 0;
+			let scratch = 0;
+			let buffer = 0;
+			const unwind = (reason, message) => {
+				if (buffer) wasm._hb_buffer_destroy(buffer);
+				if (draw) wasm._hb_gpu_draw_destroy(draw);
+				if (scratch) wasm._free(scratch);
+				if (font) wasm._hb_font_destroy(font);
+				if (face) wasm._hb_face_destroy(face);
+				if (blob) wasm._hb_blob_destroy(blob);
+				wasm._free(dataPointer);
+				return fail(reason, message);
+			};
+			blob = wasm._hb_blob_create(dataPointer, bytes.byteLength, HB_MEMORY_MODE_READONLY, 0, 0);
+			if (!blob || wasm._hb_blob_get_length(blob) !== bytes.byteLength) return unwind("face-rejected", `hb_blob_create returned a ${blob ? wasm._hb_blob_get_length(blob) : 0}-byte blob for ${bytes.byteLength} bytes of face — HarfBuzz would not take the allocation`);
+			face = wasm._hb_face_create(blob, 0);
+			if (!face) return unwind("face-rejected", "hb_face_create returned null");
+			const upem = wasm._hb_face_get_upem(face);
+			if (!Number.isInteger(upem) || upem <= 0 || upem > 16384) return unwind("face-rejected", `the face reports upem ${upem} — every glyph scaled by that is Infinity or NaN, which draws nothing and reports no error`);
+			font = wasm._hb_font_create(face);
+			if (!font) return unwind("face-rejected", "hb_font_create returned null");
+			wasm._hb_font_set_scale(font, upem, upem);
+			draw = wasm._hb_gpu_draw_create_or_fail();
+			if (!draw) return unwind("encoder-unavailable", "hb_gpu_draw_create_or_fail returned null — this face has no encoder, and every glyph of it would be missing from the frame");
+			wasm._hb_gpu_draw_set_scale(draw, upem, upem);
+			scratch = wasm._malloc(EXTENTS_BYTES);
+			if (!scratch) return unwind("out-of-memory", `_malloc(${EXTENTS_BYTES}) for the extents scratch returned 0 — reading glyph ids out of address 0 would hand back whatever the null page holds`);
+			buffer = wasm._hb_buffer_create();
+			if (!buffer || !wasm._hb_buffer_allocation_successful(buffer)) return unwind("out-of-memory", "hb_buffer_create handed back the immortal empty buffer — the heap could not allocate one, and every run shaped into it would come back with no glyphs at all");
+			let alive = true;
+			const self = {
+				upem,
+				glyphFor(codepoint) {
+					return wasm._hb_font_get_nominal_glyph(font, codepoint, scratch) ? wasm.HEAP32[scratch >> 2] >>> 0 : 0;
+				},
+				shape(text, options = {}) {
+					wasm._hb_buffer_clear_contents(buffer);
+					if (text.length === 0) return [];
+					const featureStrings = options.features ?? [];
+					const featuresAt = text.length * 2 + 3 & -4;
+					const strings = [];
+					let end = featuresAt + featureStrings.length * FEATURE_BYTES;
+					const place = (value) => {
+						const bytes = utf8.encode(value);
+						strings.push({
+							bytes,
+							at: end
+						});
+						const placed = {
+							at: end,
+							length: bytes.length
+						};
+						end += bytes.length;
+						return placed;
+					};
+					const script = options.script ? place(options.script) : null;
+					const language = options.language ? place(options.language) : null;
+					const features = featureStrings.map(place);
+					const block = wasm._malloc(end);
+					if (!block) return fail("out-of-memory", `_malloc(${end}) for a ${text.length}-code-unit run returned 0 — the wasm heap could not grow, and shaping out of address 0 would read the null page as text`);
+					const units = new Uint16Array(text.length);
+					for (let i = 0; i < text.length; i += 1) units[i] = text.charCodeAt(i);
+					wasm.HEAPU16.set(units, block >> 1);
+					for (const string of strings) wasm.HEAPU8.set(string.bytes, block + string.at);
+					for (let i = 0; i < features.length; i += 1) {
+						const at = block + featuresAt + i * FEATURE_BYTES;
+						if (!wasm._hb_feature_from_string(block + features[i].at, features[i].length, at)) {
+							wasm._free(block);
+							return fail("feature-malformed", `hb_feature_from_string refused "${featureStrings[i]}" — shaping on would silently lay the run out without the feature, so the run is refused instead`);
+						}
+					}
+					wasm._hb_buffer_add_utf16(buffer, block, text.length, 0, text.length);
+					if (options.direction) wasm._hb_buffer_set_direction(buffer, HB_DIRECTION[options.direction]);
+					if (script) wasm._hb_buffer_set_script(buffer, wasm._hb_script_from_string(block + script.at, script.length));
+					if (language) wasm._hb_buffer_set_language(buffer, wasm._hb_language_from_string(block + language.at, language.length));
+					wasm._hb_buffer_guess_segment_properties(buffer);
+					wasm._hb_shape(font, buffer, features.length ? block + featuresAt : 0, features.length);
+					wasm._free(block);
+					if (!wasm._hb_buffer_allocation_successful(buffer)) return fail("out-of-memory", `shaping a ${text.length}-code-unit run exhausted the wasm heap — the buffer came back empty, which is indistinguishable from a run with no glyphs and would render as missing text`);
+					const count = wasm._hb_buffer_get_length(buffer);
+					const infos = wasm._hb_buffer_get_glyph_infos(buffer, 0);
+					const positions = wasm._hb_buffer_get_glyph_positions(buffer, 0);
+					const heap = wasm.HEAP32;
+					const run = [];
+					for (let i = 0; i < count; i += 1) {
+						const info = infos + i * GLYPH_INFO_BYTES >> 2;
+						const position = positions + i * GLYPH_POSITION_BYTES >> 2;
+						run.push({
+							glyphId: heap[info] >>> 0,
+							cluster: heap[info + 2] >>> 0,
+							xAdvance: heap[position],
+							yAdvance: heap[position + 1],
+							xOffset: heap[position + 2],
+							yOffset: heap[position + 3]
+						});
+					}
+					return run;
+				},
+				encode(glyphId) {
+					wasm._hb_gpu_draw_clear(draw);
+					if (!wasm._hb_gpu_draw_glyph_or_fail(draw, font, glyphId)) return null;
+					const blobPointer = wasm._hb_gpu_draw_encode(draw, scratch);
+					if (!blobPointer) return null;
+					const extents = {
+						xBearing: wasm.HEAP32[scratch >> 2],
+						yBearing: wasm.HEAP32[(scratch >> 2) + 1],
+						width: wasm.HEAP32[(scratch >> 2) + 2],
+						height: wasm.HEAP32[(scratch >> 2) + 3]
+					};
+					const length = wasm._hb_blob_get_length(blobPointer);
+					const data = wasm._hb_blob_get_data(blobPointer, 0);
+					const texels = wasm.HEAPU8.slice(data, data + length);
+					wasm._hb_gpu_draw_recycle_blob(draw, blobPointer);
+					return {
+						texels,
+						extents
+					};
+				},
+				destroy() {
+					if (!alive) return;
+					alive = false;
+					fonts.delete(self);
+					wasm._hb_buffer_destroy(buffer);
+					wasm._hb_gpu_draw_destroy(draw);
+					wasm._free(scratch);
+					wasm._hb_font_destroy(font);
+					wasm._hb_face_destroy(face);
+					wasm._hb_blob_destroy(blob);
+					wasm._free(dataPointer);
+				}
+			};
+			fonts.add(self);
+			return self;
+		},
+		destroy() {
+			for (const font of [...fonts]) font.destroy();
+		}
+	};
+}
+/**
+* Total and per-glyph encoded bytes for a set of glyphs.
+*
+* THE PREDICTION UNDER TEST, made directly measurable. `docs/text-rendering.md` records it as
+* "~5.4 KB per Han glyph against ~1.4 KB for a 38x38 R8 atlas cell", and that comparison decides
+* the VRAM half of whether this arm is worth shipping — so it should be one call, on the real
+* fixture face, rather than something reconstructed from a frame counter.
+*
+* DISTINCT glyph ids, because that is what the atlas pays for too: a Han run draws 12 glyphs and an
+* atlas stores as many outlines as the pool has distinct members.
+*/
+function measureBlobBytes(font, glyphIds) {
+	let glyphs = 0;
+	let totalBytes = 0;
+	let minBytes = Number.POSITIVE_INFINITY;
+	let maxBytes = 0;
+	for (const id of new Set(glyphIds)) {
+		const encoded = font.encode(id);
+		if (!encoded || encoded.texels.length === 0) continue;
+		glyphs += 1;
+		totalBytes += encoded.texels.length;
+		minBytes = Math.min(minBytes, encoded.texels.length);
+		maxBytes = Math.max(maxBytes, encoded.texels.length);
+	}
+	return {
+		glyphs,
+		totalBytes,
+		bytesPerGlyph: glyphs > 0 ? totalBytes / glyphs : 0,
+		minBytes: glyphs > 0 ? minBytes : 0,
+		maxBytes
+	};
+}
+//#endregion
+export { HB_GPU_SHADER_LANG_GLSL, HB_GPU_SHADER_STAGE_FRAGMENT, HB_GPU_SHADER_STAGE_VERTEX, HB_GPU_TEXEL_BYTES, createHbGpu, measureBlobBytes };
+
+//# sourceMappingURL=index.js.map