# packages/text/src/index.ts This is the source snapshot used to build these API details. [View this revision on GitHub](https://github.com/benlesh/pibbl/blob/272a94aaf62e0bd6ad8726a4c607a76a9ec44ca1/packages/text/src/index.ts#L16). [Back to reference](/reference/functions/text-geometry/)
1 import { activeProfile } from "./lib/profiling.js";
2 import { validateFontContainer } from "./lib/font-container.js";
3 import { fontBytes } from "./lib/font-bytes.js";
4 import { getEngine, type Engine } from "./lib/engine.js";
5 import { PathGeometry } from "@pibbl/core";
6 import { inkBounds, type InkBounds } from "./lib/bounds.js";
7 export type { InkBounds } from "./lib/bounds.js";
8 
9 /**
10  * An explicitly owned native font loaded for text shaping. Dispose it when no more geometry will be
11  * created from it; disposal is idempotent.
12  *
13  * @see {@link loadOutlineFont}
14  * @see {@link createTextGeometry}
15  */
16 export interface OutlineFont extends Disposable {
17   /**
18    * Releases the native font owner; repeated calls are harmless and later shaping with this font
19    * fails. See {@link OutlineFont}.
20    */
21   dispose(): void;
22 }
23 /**
24  * Cancellation and monochrome-fallback policy used when loading an outline font.
25  *
26  * @see {@link loadOutlineFont}
27  */
28 export interface OutlineFontOptions {
29   /** Abort signal for font loading and validation. See {@link OutlineFontOptions}. */
30   signal?: AbortSignal;
31   /**
32    * Allows supported monochrome outlines when the font includes color glyph data. See
33    * {@link OutlineFontOptions}.
34    */
35   monochromeFallback?: boolean;
36 }
37 /**
38  * Font size, shaping direction, OpenType features, and work limits for one text run.
39  *
40  * @see {@link createTextGeometry}
41  */
42 export interface TextGeometryOptions {
43   /** Positive finite output font size in logical units. See {@link TextGeometryOptions}. */
44   fontSize: number;
45   /** Upper bound on the number of output path segments. See {@link TextGeometryOptions}. */
46   maxSegments?: number;
47   /**
48    * Whether an absent glyph fails shaping or uses the font's .notdef glyph. See
49    * {@link TextGeometryOptions}.
50    */
51   missingGlyphs?: "error" | "notdef";
52   /**
53    * Explicit left-to-right or right-to-left shaping direction; omitted direction is inferred. See
54    * {@link TextGeometryOptions}.
55    */
56   direction?: "ltr" | "rtl";
57   /**
58    * Four-character OpenType script tag overriding script inference. See
59    * {@link TextGeometryOptions}.
60    */
61   script?: string;
62   /**
63    * Language tag used for shaping; distinct interned tags are bounded by the engine. See
64    * {@link TextGeometryOptions}.
65    */
66   language?: string;
67   /** OpenType feature overrides keyed by four-character tags. See {@link TextGeometryOptions}. */
68   features?: Readonly<Record<string, boolean>>;
69 }
70 /**
71  * Shaped glyph identity, UTF-16 source cluster, outline segment range, and scaled placement metrics.
72  *
73  * @see {@link TextGeometryResult}
74  */
75 export interface TextGlyph {
76   /** Font-specific identifier of the shaped glyph. See {@link TextGlyph}. */
77   readonly glyphId: number;
78   /** UTF-16 offset of the source cluster associated with this glyph. See {@link TextGlyph}. */
79   readonly cluster: number;
80   /** Index of the glyph's first segment in the returned geometry. See {@link TextGlyph}. */
81   readonly segmentStart: number;
82   /** Number of outline segments belonging to this glyph. See {@link TextGlyph}. */
83   readonly segmentCount: number;
84   /**
85    * Horizontal coordinate or displacement in the containing coordinate system. See
86    * {@link TextGlyph}.
87    */
88   readonly x: number;
89   /**
90    * Vertical coordinate or displacement in the containing coordinate system. See {@link TextGlyph}
91    * .
92    */
93   readonly y: number;
94   /** Horizontal pen advance in scaled logical units. See {@link TextGlyph}. */
95   readonly xAdvance: number;
96   /** Vertical pen advance in Canvas-oriented logical units. See {@link TextGlyph}. */
97   readonly yAdvance: number;
98 }
99 /**
100  * Independent path geometry, optional ink bounds, advances, and glyph metadata for a shaped text run.
101  *
102  * @see {@link PathGeometry}
103  * @see {@link InkBounds}
104  * @see {@link TextGlyph}
105  * @see {@link createTextGeometry}
106  */
107 export interface TextGeometryResult {
108   /**
109    * Independent mutable outline geometry in Canvas-oriented output coordinates. See
110    * {@link PathGeometry}.
111    */
112   readonly geometry: PathGeometry;
113   /** Bounds of visible outlines, or null when the run has no ink. See {@link InkBounds}. */
114   readonly inkBounds: Readonly<InkBounds> | null;
115   /**
116    * Final pen displacement, including glyph advances even when no ink is drawn. See
117    * {@link TextGeometryResult}.
118    */
119   readonly advance: Readonly<{
120     /**
121      * Horizontal coordinate or displacement in the containing coordinate system. See
122      * {@link TextGeometryResult}.
123      */
124     x: number;
125     /**
126      * Vertical coordinate or displacement in the containing coordinate system. See
127      * {@link TextGeometryResult}.
128      */
129     y: number;
130   }>;
131   /**
132    * Ordered shaped-glyph metadata corresponding to the returned outline segments. See
133    * {@link TextGlyph}.
134    */
135   readonly glyphs: readonly TextGlyph[];
136 }
137 // HarfBuzz interns languages until module teardown. Bound that shared lifetime
138 // separately from font ownership; canonical case avoids duplicate reservations.
139 const internedLanguages = new Set<string>();
140 const owners = new WeakMap<
141   OutlineFont,
142   { engine: Engine; handle: number; upem: number }
143 >();
144 /**
145  * Loads and validates font bytes from a URL or buffer and returns an explicitly disposable font.
146  * Rejects on cancellation, unsupported font data, or allocation failure.
147  *
148  * @param source - Font URL to fetch, or in-memory font bytes to copy into the shaping engine.
149  * @param options - Cancellation signal and explicit monochrome fallback policy. See
150  * {@link OutlineFontOptions} .
151  * @returns A promise for an owned font; dispose it when no further shaping will use it. See
152  * {@link OutlineFont} .
153  *
154  * @see {@link OutlineFontOptions}
155  * @see {@link OutlineFont}
156  */
157 export async function loadOutlineFont(
158   source: string | URL | ArrayBuffer | Uint8Array,
159   options: OutlineFontOptions = {},
160 ): Promise<OutlineFont> {
161   const { signal, monochromeFallback } = options;
162   if (
163     monochromeFallback !== undefined &&
164     typeof monochromeFallback !== "boolean"
165   )
166     throw new TypeError("monochromeFallback must be boolean.");
167   signal?.throwIfAborted();
168   const controller = new AbortController();
169   const abort = () => controller.abort(signal?.reason);
170   signal?.addEventListener("abort", abort, { once: true });
171   let engine: Engine, bytes: Uint8Array;
172   try {
173     [engine, bytes] = await Promise.all([
174       getEngine(),
175       fontBytes(source, controller.signal),
176     ]);
177   } catch (error) {
178     controller.abort(error);
179     throw error;
180   } finally {
181     signal?.removeEventListener("abort", abort);
182   }
183   signal?.throwIfAborted();
184   validateFontContainer(bytes, monochromeFallback ?? false);
185   const pointer = engine._malloc(bytes.byteLength);
186   if (!pointer) throw new Error("Font allocation failed.");
187   let handle: number;
188   try {
189     engine.HEAPU8.set(bytes, pointer);
190     handle = engine._pibbl_font_create(pointer, bytes.length);
191   } finally {
192     engine._free(pointer);
193   }
194   if (!handle)
195     throw new Error("Invalid font or native font allocation failed.");
196   const font: OutlineFont = {
197     dispose() {
198       const state = owners.get(font);
199       if (!state) return;
200       owners.delete(font);
201       state.engine._pibbl_font_release(state.handle);
202     },
203     [Symbol.dispose]() {
204       font.dispose();
205     },
206   };
207   owners.set(font, { engine, handle, upem: engine._pibbl_font_upem(handle) });
208   return font;
209 }
210 /**
211  * Synchronously shapes a single text run into independent Canvas-oriented outlines. The font must
212  * be live, fontSize positive and finite, and text must not contain line breaks or tabs.
213  *
214  * @param font - Live font returned by loadOutlineFont; it must not have been disposed. See
215  * {@link OutlineFont} .
216  * @param text - Text to shape as one run.
217  * @param options - Font size, shaping overrides, missing-glyph policy, and work limits. See
218  * {@link TextGeometryOptions} .
219  * @returns Independent mutable path geometry plus glyph placements, ink bounds, and advances; the
220  * result remains usable after font disposal. See {@link TextGeometryResult} .
221  *
222  * @see {@link OutlineFont}
223  * @see {@link TextGeometryOptions}
224  * @see {@link TextGeometryResult}
225  */
226 export function createTextGeometry(
227   font: OutlineFont,
228   text: string,
229   options: TextGeometryOptions,
230 ): TextGeometryResult {
231   const profile = activeProfile;
232   let phaseStart = profile ? performance.now() : 0;
233   const owner = owners.get(font);
234   if (!owner) throw new Error("Font is disposed or is not an OutlineFont.");
235   if (
236     typeof text !== "string" ||
237     text.length > 100000 ||
238     /[\r\n\t]/u.test(text)
239   )
240     throw new TypeError(
241       "Expected a single text run of at most 100000 UTF-16 units.",
242     );
243   if (!Number.isFinite(options.fontSize) || options.fontSize <= 0)
244     throw new RangeError("fontSize must be finite and positive.");
245   if (
246     options.missingGlyphs !== undefined &&
247     options.missingGlyphs !== "error" &&
248     options.missingGlyphs !== "notdef"
249   )
250     throw new TypeError("missingGlyphs must be error or notdef.");
251   const limit = options.maxSegments ?? 1000000;
252   if (!Number.isInteger(limit) || limit < 1 || limit > 1000000)
253     throw new RangeError("maxSegments must be an integer from 1 to 1000000.");
254   const tag = (value: string) => {
255     if (!/^[ -~]{4}$/u.test(value))
256       throw new TypeError("OpenType tags must contain four ASCII characters.");
257     return (
258       ((value.charCodeAt(0) << 24) |
259         (value.charCodeAt(1) << 16) |
260         (value.charCodeAt(2) << 8) |
261         value.charCodeAt(3)) >>>
262       0
263     );
264   };
265   if (
266     options.direction !== undefined &&
267     options.direction !== "ltr" &&
268     options.direction !== "rtl"
269   )
270     throw new TypeError("Expected ltr or rtl direction.");
271   const script = options.script === undefined ? 0 : tag(options.script);
272   if (
273     options.language !== undefined &&
274     !/^[A-Za-z0-9-]{1,63}$/u.test(options.language)
275   )
276     throw new TypeError("Invalid language tag.");
277   const languageTag = options.language?.toLowerCase();
278   if (
279     languageTag !== undefined &&
280     !internedLanguages.has(languageTag) &&
281     internedLanguages.size >= 256
282   )
283     throw new RangeError(
284       "At most 256 distinct language tags may be used per text engine instance.",
285     );
286   const language =
287     languageTag === undefined
288       ? new Uint8Array(0)
289       : new TextEncoder().encode(languageTag + "\0");
290   const features = Object.entries(options.features ?? {});
291   if (features.length > 64)
292     throw new RangeError(
293       "At most 64 OpenType feature overrides are supported.",
294     );
295   const featureData = new Uint32Array(features.length * 4);
296   features.forEach(([name, enabled], index) => {
297     if (typeof enabled !== "boolean")
298       throw new TypeError("Feature overrides must be boolean.");
299     featureData.set([tag(name), Number(enabled), 0, 0xffffffff], index * 4);
300   });
301   const { engine, handle, upem } = owner;
302   const textBytes = Math.max(4, Math.ceil((text.length * 2) / 4) * 4);
303   const pointer = engine._malloc(
304     textBytes + featureData.byteLength + language.length,
305   );
306   if (!pointer) throw new Error("Text allocation failed.");
307   let result: number;
308   try {
309     const units = new Uint16Array(engine.HEAPU8.buffer, pointer, text.length);
310     for (let i = 0; i < text.length; i++) units[i] = text.charCodeAt(i);
311     engine.HEAPU8.set(new Uint8Array(featureData.buffer), pointer + textBytes);
312     engine.HEAPU8.set(language, pointer + textBytes + featureData.byteLength);
313     if (languageTag !== undefined) internedLanguages.add(languageTag);
314     if (profile) {
315       profile.inputMs = performance.now() - phaseStart;
316       engine._pibbl_profile_enabled(1);
317     }
318     result = engine._pibbl_shape(
319       handle,
320       pointer,
321       text.length,
322       limit,
323       options.direction === "ltr" ? 1 : options.direction === "rtl" ? 2 : 0,
324       script,
325       language.length ? pointer + textBytes + featureData.byteLength : 0,
326       pointer + textBytes,
327       features.length,
328       options.missingGlyphs === "notdef" ? 1 : 0,
329     );
330   } finally {
331     if (profile) {
332       profile.nativeSetupMs = engine._pibbl_profile_time(0);
333       profile.shapingMs = engine._pibbl_profile_time(1);
334       profile.outlineMs = engine._pibbl_profile_time(2);
335       engine._pibbl_profile_enabled(0);
336     }
337     engine._free(pointer);
338   }
339   if (!result)
340     throw new Error(
341       [
342         "Text conversion failed.",
343         "Font is missing a required glyph.",
344         "Text exceeded the outline work or output segment limit.",
345         "Native shaping allocation failed.",
346         "Font glyph has no valid supported outline.",
347       ][engine._pibbl_error()] ?? "Text conversion failed.",
348     );
349   try {
350     if (profile) phaseStart = performance.now();
351     const lengths = [0, 1, 2, 3].map((field) =>
352       engine._pibbl_result_length(result, field),
353     );
354     const offsets = [0, 1, 2, 3].map((field) =>
355       engine._pibbl_result_data(result, field),
356     );
357     const memory = engine.HEAPU8.buffer;
358     const commands = new Uint8Array(memory, offsets[0], lengths[0]);
359     const coords = new Float64Array(memory, offsets[1], lengths[1]);
360     const ids = new Uint32Array(memory, offsets[2], lengths[2]);
361     const positions = new Float64Array(memory, offsets[3], lengths[3]);
362     if (profile) {
363       profile.bufferViewsMs = performance.now() - phaseStart;
364       phaseStart = performance.now();
365     }
366     const scale = options.fontSize / upem;
367     const geometry = new PathGeometry();
368     let index = 0;
369     const coordinate = () => {
370       const value = coords[index] * scale * (index++ & 1 ? -1 : 1);
371       if (!Number.isFinite(value))
372         throw new RangeError("Nonfinite outline coordinate.");
373       return value;
374     };
375     for (const command of commands) {
376       switch (command) {
377         case 0:
378           geometry.moveTo(coordinate(), coordinate());
379           break;
380         case 1:
381           geometry.lineTo(coordinate(), coordinate());
382           break;
383         case 2:
384           geometry.quadraticCurveTo(
385             coordinate(),
386             coordinate(),
387             coordinate(),
388             coordinate(),
389           );
390           break;
391         case 3:
392           geometry.bezierCurveTo(
393             coordinate(),
394             coordinate(),
395             coordinate(),
396             coordinate(),
397             coordinate(),
398             coordinate(),
399           );
400           break;
401         case 4:
402           geometry.closePath();
403           break;
404         default:
405           throw new Error("Invalid outline command.");
406       }
407     }
408     if (
409       index !== coords.length ||
410       ids.length % 4 ||
411       positions.length !== ids.length
412     )
413       throw new Error("Invalid native result.");
414     const finite = (value: number) => {
415       if (!Number.isFinite(value))
416         throw new RangeError("Nonfinite text metric.");
417       return value === 0 ? 0 : value;
418     };
419     const glyphs: TextGlyph[] = [];
420     let segmentEnd = 0;
421     for (let i = 0; i < ids.length; i += 4) {
422       if (
423         ids[i + 1] >= text.length ||
424         ids[i + 2] !== segmentEnd ||
425         ids[i + 3] > commands.length - segmentEnd
426       ) {
427         throw new Error("Invalid native glyph metadata.");
428       }
429       segmentEnd += ids[i + 3];
430       glyphs.push(
431         Object.freeze({
432           glyphId: ids[i],
433           cluster: ids[i + 1],
434           segmentStart: ids[i + 2],
435           segmentCount: ids[i + 3],
436           x: finite(positions[i] * scale),
437           y: finite(-positions[i + 1] * scale),
438           xAdvance: finite(positions[i + 2] * scale),
439           yAdvance: finite(-positions[i + 3] * scale),
440         }),
441       );
442     }
443     if (segmentEnd !== commands.length)
444       throw new Error("Invalid native glyph segment coverage.");
445     if (profile) {
446       profile.materializationMs = performance.now() - phaseStart;
447       phaseStart = performance.now();
448     }
449     const bounds = inkBounds(geometry);
450     if (profile) profile.boundsMs = performance.now() - phaseStart;
451     return Object.freeze({
452       geometry,
453       inkBounds: bounds,
454       glyphs: Object.freeze(glyphs),
455       advance: Object.freeze({
456         x: finite(engine._pibbl_result_advance(result, 0) * scale),
457         y: finite(-engine._pibbl_result_advance(result, 1) * scale),
458       }),
459     });
460   } finally {
461     engine._pibbl_result_release(result);
462   }
463 }
464
## Documentation version Documentation built with @pibbl/core 0.0.2, revision 272a94a. ALPHA — NOT FOR PRODUCTION USE.