harfbuzzjs 1.0.0-beta.1 → 1.0.0

package/dist/index.mjs

@@ -37,7 +37,7 @@ function hb_untag(tag) {
 }
 function utf8_ptr_to_string(ptr, length) {
 	let end;
-	if (length === void 0) end = Module.HEAPU8.indexOf(0, ptr);
+	if (length == void 0) end = Module.HEAPU8.indexOf(0, ptr);
 	else end = ptr + length;
 	return utf8Decoder.decode(Module.HEAPU8.subarray(ptr, end));
 }
@@ -355,7 +355,7 @@ var Face = class {
 	* Get the name IDs of the specified feature.
 	* @param table The table to query, either "GSUB" or "GPOS".
 	* @param featureIndex The index of the feature to query.
-	* @returns An object with name IDs, or null if not found.
+	* @returns An object with name IDs, or undefined if not found.
 	*/
 	getFeatureNameIds(table, featureIndex) {
 		const sp = Module.stackSave();
@@ -366,20 +366,17 @@ var Face = class {
 		const numNamedParametersPtr = Module.stackAlloc(4);
 		const firstParameterIdPtr = Module.stackAlloc(4);
 		const found = exports.hb_ot_layout_feature_get_name_ids(this.ptr, tableTag, featureIndex, labelIdPtr, tooltipIdPtr, sampleIdPtr, numNamedParametersPtr, firstParameterIdPtr);
-		let names = null;
+		let names;
 		if (found) {
 			const uiLabelNameId = Module.HEAPU32[labelIdPtr / 4];
 			const uiTooltipTextNameId = Module.HEAPU32[tooltipIdPtr / 4];
 			const sampleTextNameId = Module.HEAPU32[sampleIdPtr / 4];
 			const numNamedParameters = Module.HEAPU32[numNamedParametersPtr / 4];
 			const firstParameterId = Module.HEAPU32[firstParameterIdPtr / 4];
-			const paramUiLabelNameIds = Array.from({ length: numNamedParameters }, (_, i) => firstParameterId + i);
-			names = {
-				uiLabelNameId: uiLabelNameId == HB_OT_NAME_ID_INVALID ? null : uiLabelNameId,
-				uiTooltipTextNameId: uiTooltipTextNameId == HB_OT_NAME_ID_INVALID ? null : uiTooltipTextNameId,
-				sampleTextNameId: sampleTextNameId == HB_OT_NAME_ID_INVALID ? null : sampleTextNameId,
-				paramUiLabelNameIds
-			};
+			names = { paramUiLabelNameIds: Array.from({ length: numNamedParameters }, (_, i) => firstParameterId + i) };
+			if (uiLabelNameId != HB_OT_NAME_ID_INVALID) names.uiLabelNameId = uiLabelNameId;
+			if (uiTooltipTextNameId != HB_OT_NAME_ID_INVALID) names.uiTooltipTextNameId = uiTooltipTextNameId;
+			if (sampleTextNameId != HB_OT_NAME_ID_INVALID) names.sampleTextNameId = sampleTextNameId;
 		}
 		Module.stackRestore(sp);
 		return names;
@@ -395,15 +392,7 @@ var Face = class {
 */
 var Font = class Font {
 	constructor(arg) {
-		this.drawPtrs = {
-			drawFuncsPtr: null,
-			moveToPtr: null,
-			lineToPtr: null,
-			cubicToPtr: null,
-			quadToPtr: null,
-			closePathPtr: null,
-			pathBuffer: ""
-		};
+		this.drawPtrs = { pathBuffer: "" };
 		if (typeof arg === "number") this.ptr = exports.hb_font_reference(arg);
 		else this.ptr = exports.hb_font_create(arg.ptr);
 		const ptr = this.ptr;
@@ -531,13 +520,13 @@ var Font = class Font {
 	/**
 	* Return glyph horizontal origin.
 	* @param glyphId ID of the requested glyph in the font.
-	* @returns [x, y] origin coordinates, or null if not available.
+	* @returns [x, y] origin coordinates, or undefined if not available.
 	*/
 	glyphHOrigin(glyphId) {
 		const sp = Module.stackSave();
 		const xPtr = Module.stackAlloc(4);
 		const yPtr = Module.stackAlloc(4);
-		let origin = null;
+		let origin;
 		if (exports.hb_font_get_glyph_h_origin(this.ptr, glyphId, xPtr, yPtr)) origin = [Module.HEAP32[xPtr / 4], Module.HEAP32[yPtr / 4]];
 		Module.stackRestore(sp);
 		return origin;
@@ -545,13 +534,13 @@ var Font = class Font {
 	/**
 	* Return glyph vertical origin.
 	* @param glyphId ID of the requested glyph in the font.
-	* @returns [x, y] origin coordinates, or null if not available.
+	* @returns [x, y] origin coordinates, or undefined if not available.
 	*/
 	glyphVOrigin(glyphId) {
 		const sp = Module.stackSave();
 		const xPtr = Module.stackAlloc(4);
 		const yPtr = Module.stackAlloc(4);
-		let origin = null;
+		let origin;
 		if (exports.hb_font_get_glyph_v_origin(this.ptr, glyphId, xPtr, yPtr)) origin = [Module.HEAP32[xPtr / 4], Module.HEAP32[yPtr / 4]];
 		Module.stackRestore(sp);
 		return origin;
@@ -559,12 +548,12 @@ var Font = class Font {
 	/**
 	* Return glyph extents.
 	* @param glyphId ID of the requested glyph in the font.
-	* @returns An object with xBearing, yBearing, width, and height, or null.
+	* @returns An object with xBearing, yBearing, width, and height, or undefined.
 	*/
 	glyphExtents(glyphId) {
 		const sp = Module.stackSave();
 		const extentsPtr = Module.stackAlloc(16);
-		let extents = null;
+		let extents;
 		if (exports.hb_font_get_glyph_extents(this.ptr, glyphId, extentsPtr)) extents = {
 			xBearing: Module.HEAP32[extentsPtr / 4],
 			yBearing: Module.HEAP32[extentsPtr / 4 + 1],
@@ -575,15 +564,71 @@ var Font = class Font {
 		return extents;
 	}
 	/**
+	* Fetches the glyph ID for a Unicode code point in the specified
+	* font, with an optional variation selector.
+	*
+	* If `variationSelector` is 0, it is equivalent to
+	* {@link Font.nominalGlyph}; otherwise it is equivalent to
+	* {@link Font.variationGlyph}.
+	*
+	* @param unicode The Unicode code point to query.
+	* @param variationSelector A variation-selector code point.
+	* @returns The glyph ID, or undefined if not found.
+	*/
+	glyph(unicode, variationSelector = 0) {
+		const sp = Module.stackSave();
+		const glyphIdPtr = Module.stackAlloc(4);
+		let glyphId;
+		if (exports.hb_font_get_glyph(this.ptr, unicode, variationSelector, glyphIdPtr)) glyphId = Module.HEAPU32[glyphIdPtr / 4];
+		Module.stackRestore(sp);
+		return glyphId;
+	}
+	/**
+	* Fetches the nominal glyph ID for a Unicode code point in the
+	* specified font.
+	*
+	* This version of the function should not be used to fetch glyph IDs
+	* for code points modified by variation selectors. For variation-selector
+	* support, use {@link Font.variationGlyph} or {@link Font.glyph}.
+	*
+	* @param unicode The Unicode code point to query.
+	* @returns The glyph ID, or undefined if not found.
+	*/
+	nominalGlyph(unicode) {
+		const sp = Module.stackSave();
+		const glyphIdPtr = Module.stackAlloc(4);
+		let glyphId;
+		if (exports.hb_font_get_nominal_glyph(this.ptr, unicode, glyphIdPtr)) glyphId = Module.HEAPU32[glyphIdPtr / 4];
+		Module.stackRestore(sp);
+		return glyphId;
+	}
+	/**
+	* Fetches the glyph ID for a Unicode code point when followed by
+	* by the specified variation-selector code point, in the specified
+	* font.
+	*
+	* @param unicode The Unicode code point to query.
+	* @param variationSelector The variation-selector code point to query.
+	* @returns The glyph ID, or undefined if not found.
+	*/
+	variationGlyph(unicode, variationSelector) {
+		const sp = Module.stackSave();
+		const glyphIdPtr = Module.stackAlloc(4);
+		let glyphId;
+		if (exports.hb_font_get_variation_glyph(this.ptr, unicode, variationSelector, glyphIdPtr)) glyphId = Module.HEAPU32[glyphIdPtr / 4];
+		Module.stackRestore(sp);
+		return glyphId;
+	}
+	/**
 	* Return glyph ID from name.
 	* @param name Name of the requested glyph in the font.
-	* @returns The glyph ID, or null if not found.
+	* @returns The glyph ID, or undefined if not found.
 	*/
 	glyphFromName(name) {
 		const sp = Module.stackSave();
 		const glyphIdPtr = Module.stackAlloc(4);
 		const namePtr = string_to_utf8_ptr(name);
-		let glyphId = null;
+		let glyphId;
 		if (exports.hb_font_get_glyph_from_name(this.ptr, namePtr.ptr, namePtr.length, glyphIdPtr)) glyphId = Module.HEAPU32[glyphIdPtr / 4];
 		namePtr.free();
 		Module.stackRestore(sp);
@@ -614,18 +659,22 @@ var Font = class Font {
 		exports.hb_font_set_scale(this.ptr, xScale, yScale);
 	}
 	/**
-	* Set the font's variations.
-	* @param variations Dictionary of variations to set.
+	* Applies a list of font-variation settings to a font.
+	*
+	* Note that this overrides all existing variations set on the font.
+	* Axes not included in `variations` will be effectively set to their
+	* default values.
+	*
+	* @param variations Array of variation settings to apply.
 	*/
 	setVariations(variations) {
-		const entries = Object.entries(variations);
-		const vars = exports.malloc(8 * entries.length);
-		entries.forEach(([tag, value], i) => {
-			Module.HEAPU32[vars / 4 + i * 2 + 0] = hb_tag(tag);
-			Module.HEAPF32[vars / 4 + i * 2 + 1] = value;
+		const sp = Module.stackSave();
+		const vars = Module.stackAlloc(8 * variations.length);
+		variations.forEach((variation, i) => {
+			variation.writeTo(vars + i * 8);
 		});
-		exports.hb_font_set_variations(this.ptr, vars, entries.length);
-		exports.free(vars);
+		exports.hb_font_set_variations(this.ptr, vars, variations.length);
+		Module.stackRestore(sp);
 	}
 	/** Set the font's font functions. */
 	setFuncs(fontFuncs) {
@@ -648,7 +697,7 @@ var FontFuncs = class {
 	/**
 	* Set the font's glyph extents function.
 	* @param func The callback receives a Font and glyph ID. It should return
-	* an object with xBearing, yBearing, width, and height, or null on failure.
+	* an object with xBearing, yBearing, width, and height, or undefined on failure.
 	*/
 	setGlyphExtentsFunc(func) {
 		const funcPtr = Module.addFunction((fontPtr, font_data, glyph, extentsPtr, user_data) => {
@@ -667,7 +716,7 @@ var FontFuncs = class {
 	/**
 	* Set the font's glyph from name function.
 	* @param func The callback receives a Font and glyph name. It should return
-	* the glyph ID, or null on failure.
+	* the glyph ID, or undefined on failure.
 	*/
 	setGlyphFromNameFunc(func) {
 		const funcPtr = Module.addFunction((fontPtr, font_data, namePtr, len, glyphPtr, user_data) => {
@@ -705,7 +754,7 @@ var FontFuncs = class {
 	/**
 	* Set the font's glyph horizontal origin function.
 	* @param func The callback receives a Font and glyph ID. It should return
-	* the [x, y] horizontal origin of the glyph, or null on failure.
+	* the [x, y] horizontal origin of the glyph, or undefined on failure.
 	*/
 	setGlyphHOriginFunc(func) {
 		const funcPtr = Module.addFunction((fontPtr, font_data, glyph, xPtr, yPtr, user_data) => {
@@ -722,7 +771,7 @@ var FontFuncs = class {
 	/**
 	* Set the font's glyph vertical origin function.
 	* @param func The callback receives a Font and glyph ID. It should return
-	* the [x, y] vertical origin of the glyph, or null on failure.
+	* the [x, y] vertical origin of the glyph, or undefined on failure.
 	*/
 	setGlyphVOriginFunc(func) {
 		const funcPtr = Module.addFunction((fontPtr, font_data, glyph, xPtr, yPtr, user_data) => {
@@ -750,7 +799,7 @@ var FontFuncs = class {
 	/**
 	* Set the font's glyph name function.
 	* @param func The callback receives a Font and glyph ID. It should return
-	* the name of the glyph, or null on failure.
+	* the name of the glyph, or undefined on failure.
 	*/
 	setGlyphNameFunc(func) {
 		const utf8Encoder = new TextEncoder();
@@ -767,7 +816,7 @@ var FontFuncs = class {
 	/**
 	* Set the font's nominal glyph function.
 	* @param func The callback receives a Font and unicode code point. It should
-	* return the nominal glyph of the unicode, or null on failure.
+	* return the nominal glyph of the unicode, or undefined on failure.
 	*/
 	setNominalGlyphFunc(func) {
 		const funcPtr = Module.addFunction((fontPtr, font_data, unicode, glyphPtr, user_data) => {
@@ -783,7 +832,7 @@ var FontFuncs = class {
 	/**
 	* Set the font's variation glyph function.
 	* @param func The callback receives a Font, unicode code point, and variation
-	* selector. It should return the variation glyph, or null on failure.
+	* selector. It should return the variation glyph, or undefined on failure.
 	*/
 	setVariationGlyphFunc(func) {
 		const funcPtr = Module.addFunction((fontPtr, font_data, unicode, variationSelector, glyphPtr, user_data) => {
@@ -799,7 +848,7 @@ var FontFuncs = class {
 	/**
 	* Set the font's horizontal extents function.
 	* @param func The callback receives a Font. It should return an object with
-	* ascender, descender, and lineGap, or null on failure.
+	* ascender, descender, and lineGap, or undefined on failure.
 	*/
 	setFontHExtentsFunc(func) {
 		const funcPtr = Module.addFunction((fontPtr, font_data, extentsPtr, user_data) => {
@@ -817,7 +866,7 @@ var FontFuncs = class {
 	/**
 	* Set the font's vertical extents function.
 	* @param func The callback receives a Font. It should return an object with
-	* ascender, descender, and lineGap, or null on failure.
+	* ascender, descender, and lineGap, or undefined on failure.
 	*/
 	setFontVExtentsFunc(func) {
 		const funcPtr = Module.addFunction((fontPtr, font_data, extentsPtr, user_data) => {
@@ -869,6 +918,13 @@ const Direction = {
 	TTB: 6,
 	BTT: 7
 };
+const ClusterLevel = {
+	MONOTONE_GRAPHEMES: 0,
+	MONOTONE_CHARACTERS: 1,
+	CHARACTERS: 2,
+	GRAPHEMES: 3,
+	DEFAULT: 0
+};
 const BufferSerializeFormat = {
 	INVALID: 0,
 	TEXT: hb_tag("TEXT"),
@@ -880,34 +936,50 @@ const BufferSerializeFormat = {
 * output glyphs and their information after shaping.
 */
 var Buffer = class Buffer {
+	/**
+	* @param existingPtr @internal Wrap an existing buffer pointer.
+	*/
 	constructor(existingPtr) {
-		if (existingPtr !== void 0) this.ptr = exports.hb_buffer_reference(existingPtr);
+		if (existingPtr != void 0) this.ptr = exports.hb_buffer_reference(existingPtr);
 		else this.ptr = exports.hb_buffer_create();
 		track(this, exports.hb_buffer_destroy);
 	}
 	/**
+	* Appends a character with the Unicode value of `codePoint` to the buffer,
+	* and gives it the initial cluster value of `cluster`. Clusters can be any
+	* thing the client wants, they are usually used to refer to the index of the
+	* character in the input text stream and are output in the `cluster` field
+	* of {@link GlyphInfo}.
+	*
+	* This function does not check the validity of `codePoint`, it is up to the
+	* caller to ensure it is a valid Unicode code point.
+	* @param codePoint A Unicode code point.
+	* @param cluster The cluster value of `codePoint`.
+	*/
+	add(codePoint, cluster) {
+		exports.hb_buffer_add(this.ptr, codePoint, cluster);
+	}
+	/**
 	* Add text to the buffer.
 	* @param text Text to be added to the buffer.
 	* @param itemOffset The offset of the first character to add to the buffer.
-	* @param itemLength The number of characters to add to the buffer, or null for the end of text.
+	* @param itemLength The number of characters to add to the buffer, or omit for the end of text.
 	*/
-	addText(text, itemOffset = 0, itemLength = null) {
+	addText(text, itemOffset = 0, itemLength) {
 		const str = string_to_utf16_ptr(text);
-		if (itemLength == null) itemLength = str.length;
-		exports.hb_buffer_add_utf16(this.ptr, str.ptr, str.length, itemOffset, itemLength);
+		exports.hb_buffer_add_utf16(this.ptr, str.ptr, str.length, itemOffset, itemLength ?? str.length);
 		str.free();
 	}
 	/**
 	* Add code points to the buffer.
 	* @param codePoints Array of code points to be added to the buffer.
 	* @param itemOffset The offset of the first code point to add to the buffer.
-	* @param itemLength The number of code points to add to the buffer, or null for the end of the array.
+	* @param itemLength The number of code points to add to the buffer, or omit for the end of the array.
 	*/
-	addCodePoints(codePoints, itemOffset = 0, itemLength = null) {
+	addCodePoints(codePoints, itemOffset = 0, itemLength) {
 		const codePointsPtr = exports.malloc(codePoints.length * 4);
 		Module.HEAPU32.subarray(codePointsPtr / 4, codePointsPtr / 4 + codePoints.length).set(codePoints);
-		if (itemLength == null) itemLength = codePoints.length;
-		exports.hb_buffer_add_codepoints(this.ptr, codePointsPtr, codePoints.length, itemOffset, itemLength);
+		exports.hb_buffer_add_codepoints(this.ptr, codePointsPtr, codePoints.length, itemOffset, itemLength ?? codePoints.length);
 		exports.free(codePointsPtr);
 	}
 	/**
@@ -954,7 +1026,7 @@ var Buffer = class Buffer {
 	* Set the HarfBuzz clustering level.
 	*
 	* Affects the cluster values returned from shaping.
-	* @param level Clustering level. See the HarfBuzz manual chapter on Clusters.
+	* @param level A {@link ClusterLevel} value. See the HarfBuzz manual chapter on Clusters.
 	*/
 	setClusterLevel(level) {
 		exports.hb_buffer_set_cluster_level(this.ptr, level);
@@ -996,12 +1068,13 @@ var Buffer = class Buffer {
 	* @returns An array of {@link GlyphInfo} objects.
 	*/
 	getGlyphInfos() {
-		const infosPtr32 = exports.hb_buffer_get_glyph_infos(this.ptr, 0) / 4;
-		const infosArray = Module.HEAPU32.subarray(infosPtr32, infosPtr32 + this.getLength() * 5);
+		const infosPtr = exports.hb_buffer_get_glyph_infos(this.ptr, 0);
+		const infosArray = Module.HEAPU32.subarray(infosPtr / 4, infosPtr / 4 + this.getLength() * 5);
 		const infos = [];
 		for (let i = 0; i < infosArray.length; i += 5) infos.push({
 			codepoint: infosArray[i],
-			cluster: infosArray[i + 2]
+			cluster: infosArray[i + 2],
+			flags: exports.hb_glyph_info_get_glyph_flags(infosPtr + i * 4)
 		});
 		return infos;
 	}
@@ -1030,15 +1103,16 @@ var Buffer = class Buffer {
 	* properties from getGlyphInfos and getGlyphPositions combined.
 	*/
 	getGlyphInfosAndPositions() {
-		const infosPtr32 = exports.hb_buffer_get_glyph_infos(this.ptr, 0) / 4;
-		const infosArray = Module.HEAPU32.subarray(infosPtr32, infosPtr32 + this.getLength() * 5);
+		const infosPtr = exports.hb_buffer_get_glyph_infos(this.ptr, 0);
+		const infosArray = Module.HEAPU32.subarray(infosPtr / 4, infosPtr / 4 + this.getLength() * 5);
 		const positionsPtr32 = exports.hb_buffer_get_glyph_positions(this.ptr, 0) / 4;
-		const positionsArray = positionsPtr32 ? Module.HEAP32.subarray(positionsPtr32, positionsPtr32 + this.getLength() * 5) : null;
+		const positionsArray = positionsPtr32 ? Module.HEAP32.subarray(positionsPtr32, positionsPtr32 + this.getLength() * 5) : void 0;
 		const out = [];
 		for (let i = 0; i < infosArray.length; i += 5) {
 			const info = {
 				codepoint: infosArray[i],
-				cluster: infosArray[i + 2]
+				cluster: infosArray[i + 2],
+				flags: exports.hb_glyph_info_get_glyph_flags(infosPtr + i * 4)
 			};
 			for (const [name, idx] of [
 				["mask", 1],
@@ -1080,15 +1154,16 @@ var Buffer = class Buffer {
 	}
 	/**
 	* Serialize the buffer contents to a string.
-	* @param font The font to use for serialization.
-	* @param start The starting index of the glyphs to serialize.
-	* @param end The ending index of the glyphs to serialize.
-	* @param format The {@link BufferSerializeFormat} to serialize the buffer contents to.
-	* @param flags A combination of {@link BufferSerializeFlag} values (OR them together).
-	*
+	* @param options Serialization options:
+	*  - `font`: the font to use for serialization;
+	*  - `start`: the starting index of the glyphs (default `0`);
+	*  - `end`: the ending index of the glyphs (default end of buffer);
+	*  - `format`: a {@link BufferSerializeFormat} value (default `TEXT`);
+	*  - `flags`: a combination of {@link BufferSerializeFlag} values (default `0`).
 	* @returns The serialized buffer contents.
 	*/
-	serialize(font, start = 0, end, format = BufferSerializeFormat.TEXT, flags = 0) {
+	serialize(options = {}) {
+		let { font, start = 0, end, format = BufferSerializeFormat.TEXT, flags = 0 } = options;
 		const sp = Module.stackSave();
 		const endPos = end ?? this.getLength();
 		const bufLen = 32 * 1024;
@@ -1113,13 +1188,161 @@ var Buffer = class Buffer {
 	getContentType() {
 		return exports.hb_buffer_get_content_type(this.ptr);
 	}
+};
+//#endregion
+//#region src/feature.ts
+/**
+* A {@link https://harfbuzz.github.io/harfbuzz-hb-common.html#hb-feature-t | HarfBuzz feature}.
+*
+* The structure that holds information about requested feature application.
+* The feature will be applied with the given value to all glyphs which are in
+* clusters between {@link Feature.start} (inclusive) and {@link Feature.end}
+* (exclusive). Setting `start` to `0` and `end` to `0xffffffff` specifies that
+* the feature always applies to the entire buffer.
+*/
+var Feature = class Feature {
+	static {
+		this.GLOBAL_START = 0;
+	}
+	static {
+		this.GLOBAL_END = 4294967295;
+	}
+	constructor(tag, value = 1, start = Feature.GLOBAL_START, end = Feature.GLOBAL_END) {
+		this.tag = tag;
+		this.value = value;
+		this.start = start;
+		this.end = end;
+	}
 	/**
-	* Return the buffer contents as a JSON object.
-	* @returns An array of {@link JsonGlyph} objects.
+	* Parses a string into a Feature.
+	*
+	* The format for specifying feature strings follows. All valid CSS
+	* font-feature-settings values other than `normal` and the global values are
+	* also accepted, though not documented below. CSS string escapes are not
+	* supported.
+	*
+	* The range indices refer to the positions between Unicode characters. The
+	* position before the first character is always 0.
+	*
+	* The format is Python-esque. Here is how it all works:
+	*
+	* | Syntax        | Value | Start | End | Meaning                          |
+	* | ------------- | ----- | ----- | --- | -------------------------------- |
+	* | `kern`        | 1     | 0     | ∞   | Turn feature on                  |
+	* | `+kern`       | 1     | 0     | ∞   | Turn feature on                  |
+	* | `-kern`       | 0     | 0     | ∞   | Turn feature off                 |
+	* | `kern=0`      | 0     | 0     | ∞   | Turn feature off                 |
+	* | `kern=1`      | 1     | 0     | ∞   | Turn feature on                  |
+	* | `aalt=2`      | 2     | 0     | ∞   | Choose 2nd alternate             |
+	* | `kern[]`      | 1     | 0     | ∞   | Turn feature on                  |
+	* | `kern[:]`     | 1     | 0     | ∞   | Turn feature on                  |
+	* | `kern[5:]`    | 1     | 5     | ∞   | Turn feature on, partial         |
+	* | `kern[:5]`    | 1     | 0     | 5   | Turn feature on, partial         |
+	* | `kern[3:5]`   | 1     | 3     | 5   | Turn feature on, range           |
+	* | `kern[3]`     | 1     | 3     | 3+1 | Turn feature on, single char     |
+	* | `aalt[3:5]=2` | 2     | 3     | 5   | Turn 2nd alternate on for range  |
+	*
+	* @param str The string to parse.
+	* @returns A Feature, or undefined if the string is not a valid feature.
 	*/
-	json() {
-		const buf = this.serialize(null, 0, null, BufferSerializeFormat.JSON, BufferSerializeFlag.NO_GLYPH_NAMES | BufferSerializeFlag.GLYPH_FLAGS);
-		return JSON.parse(buf);
+	static fromString(str) {
+		const sp = Module.stackSave();
+		const featurePtr = Module.stackAlloc(16);
+		const strPtr = string_to_ascii_ptr(str);
+		let feature;
+		if (exports.hb_feature_from_string(strPtr.ptr, -1, featurePtr)) feature = new Feature(hb_untag(Module.HEAPU32[featurePtr / 4]), Module.HEAPU32[featurePtr / 4 + 1], Module.HEAPU32[featurePtr / 4 + 2], Module.HEAPU32[featurePtr / 4 + 3]);
+		strPtr.free();
+		Module.stackRestore(sp);
+		return feature;
+	}
+	/**
+	* Converts the feature to a string in the format understood by
+	* {@link Feature.fromString}.
+	*
+	* Note that the feature value will be omitted if it is `1`, but the string
+	* won't include any whitespace.
+	*
+	* @returns The feature string.
+	*/
+	toString() {
+		const sp = Module.stackSave();
+		const featurePtr = Module.stackAlloc(16);
+		this.writeTo(featurePtr);
+		const bufLen = 128;
+		const bufPtr = Module.stackAlloc(bufLen);
+		exports.hb_feature_to_string(featurePtr, bufPtr, bufLen);
+		const result = utf8_ptr_to_string(bufPtr);
+		Module.stackRestore(sp);
+		return result;
+	}
+	/** @internal Write this feature into the given hb_feature_t pointer. */
+	writeTo(ptr) {
+		Module.HEAPU32[ptr / 4] = hb_tag(this.tag);
+		Module.HEAPU32[ptr / 4 + 1] = this.value;
+		Module.HEAPU32[ptr / 4 + 2] = this.start;
+		Module.HEAPU32[ptr / 4 + 3] = this.end;
+	}
+};
+//#endregion
+//#region src/variation.ts
+/**
+* A {@link https://harfbuzz.github.io/harfbuzz-hb-common.html#hb-variation-t | HarfBuzz variation}.
+*
+* Data type for holding variation data. Registered OpenType variation-axis
+* tags are listed in
+* {@link https://docs.microsoft.com/en-us/typography/opentype/spec/dvaraxisreg | OpenType Axis Tag Registry}.
+*/
+var Variation = class Variation {
+	constructor(tag, value = 0) {
+		this.tag = tag;
+		this.value = value;
+	}
+	/**
+	* Parses a string into a Variation.
+	*
+	* The format for specifying variation settings follows. All valid CSS
+	* font-variation-settings values other than `normal` and `inherited` are
+	* also accepted, though, not documented below.
+	*
+	* The format is a tag, optionally followed by an equals sign, followed by a
+	* number. For example `wght=500`, or `slnt=-7.5`.
+	*
+	* @param str The string to parse.
+	* @returns A Variation, or undefined if the string is not a valid variation.
+	*/
+	static fromString(str) {
+		const sp = Module.stackSave();
+		const variationPtr = Module.stackAlloc(8);
+		const strPtr = string_to_ascii_ptr(str);
+		let variation;
+		if (exports.hb_variation_from_string(strPtr.ptr, -1, variationPtr)) variation = new Variation(hb_untag(Module.HEAPU32[variationPtr / 4]), Module.HEAPF32[variationPtr / 4 + 1]);
+		strPtr.free();
+		Module.stackRestore(sp);
+		return variation;
+	}
+	/**
+	* Converts the variation to a string in the format understood by
+	* {@link Variation.fromString}.
+	*
+	* Note that the string won't include any whitespace.
+	*
+	* @returns The variation string.
+	*/
+	toString() {
+		const sp = Module.stackSave();
+		const variationPtr = Module.stackAlloc(8);
+		this.writeTo(variationPtr);
+		const bufLen = 128;
+		const bufPtr = Module.stackAlloc(bufLen);
+		exports.hb_variation_to_string(variationPtr, bufPtr, bufLen);
+		const result = utf8_ptr_to_string(bufPtr);
+		Module.stackRestore(sp);
+		return result;
+	}
+	/** @internal Write this variation into the given hb_variation_t pointer. */
+	writeTo(ptr) {
+		Module.HEAPU32[ptr / 4] = hb_tag(this.tag);
+		Module.HEAPF32[ptr / 4 + 1] = this.value;
 	}
 };
 //#endregion
@@ -1138,22 +1361,20 @@ const TracePhase = {
 * @param font The Font to shape with.
 * @param buffer The Buffer containing text to shape, suitably prepared
 *   (text added, segment properties set).
-* @param features A string of comma-separated OpenType features to apply.
+* @param features An array of {@link Feature} values to apply.
 */
 function shape(font, buffer, features) {
+	const featuresLen = features?.length ?? 0;
+	const sp = Module.stackSave();
 	let featuresPtr = 0;
-	let featuresLen = 0;
-	if (features) {
-		const featureList = features.split(",");
-		featuresPtr = exports.malloc(16 * featureList.length);
-		featureList.forEach((feature) => {
-			const str = string_to_ascii_ptr(feature);
-			if (exports.hb_feature_from_string(str.ptr, -1, featuresPtr + featuresLen * 16)) featuresLen++;
-			str.free();
+	if (featuresLen) {
+		featuresPtr = Module.stackAlloc(16 * featuresLen);
+		features.forEach((feature, i) => {
+			feature.writeTo(featuresPtr + i * 16);
 		});
 	}
 	exports.hb_shape(font.ptr, buffer.ptr, featuresPtr, featuresLen);
-	if (featuresPtr) exports.free(featuresPtr);
+	Module.stackRestore(sp);
 }
 /**
 * Shape a buffer with a given font, returning a JSON trace of the shaping process.
@@ -1163,7 +1384,7 @@ function shape(font, buffer, features) {
 *
 * @param font The Font to shape with.
 * @param buffer The Buffer containing text to shape, suitably prepared.
-* @param features A string of comma-separated OpenType features to apply.
+* @param features An array of {@link Feature} values to apply.
 * @param stop_at A lookup ID at which to terminate shaping.
 * @param stop_phase The {@link TracePhase} at which to stop shaping.
 * @returns An array of trace entries, each with a message, serialized glyphs, and phase info.
@@ -1178,7 +1399,11 @@ function shapeWithTrace(font, buffer, features, stop_at, stop_phase) {
 		if (currentPhase != stop_phase) stopping = false;
 		if (stop_phase != TracePhase.DONT_STOP && currentPhase == stop_phase && message.startsWith("end lookup " + stop_at)) stopping = true;
 		if (stopping) return false;
-		const traceBuf = buffer.serialize(font, 0, null, BufferSerializeFormat.JSON, BufferSerializeFlag.NO_GLYPH_NAMES);
+		const traceBuf = buffer.serialize({
+			font,
+			format: BufferSerializeFormat.JSON,
+			flags: BufferSerializeFlag.NO_GLYPH_NAMES
+		});
 		trace.push({
 			m: message,
 			t: JSON.parse(traceBuf),
@@ -1234,4 +1459,4 @@ function otTagToLanguage(tag) {
 //#region src/index.ts
 init(await createHarfBuzz());
 //#endregion
-export { Blob, Buffer, BufferContentType, BufferFlag, BufferSerializeFlag, BufferSerializeFormat, Direction, Face, Font, FontFuncs, GlyphClass, GlyphFlag, TracePhase, otTagToLanguage, otTagToScript, shape, shapeWithTrace, version, versionString };
+export { Blob, Buffer, BufferContentType, BufferFlag, BufferSerializeFlag, BufferSerializeFormat, ClusterLevel, Direction, Face, Feature, Font, FontFuncs, GlyphClass, GlyphFlag, TracePhase, Variation, otTagToLanguage, otTagToScript, shape, shapeWithTrace, version, versionString };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "harfbuzzjs",
-  "version": "1.0.0-beta.1",
+  "version": "1.0.0",
   "description": "Minimal version of HarfBuzz for JavaScript use",
   "type": "module",
   "main": "dist/index.mjs",