text-shaper 0.1.1 → 0.1.3

package/dist/render/path.d.ts

@@ -2,6 +2,7 @@ import type { GlyphBuffer } from "../buffer/glyph-buffer.ts";
 import type { Font } from "../font/font.ts";
 import type { Contour } from "../font/tables/glyf.ts";
 import type { GlyphId } from "../types.ts";
+import { type Matrix2D, type Matrix3x3 } from "./outline-transform.ts";
 /**
  * Path command types for glyph rendering
  */
@@ -63,11 +64,12 @@ export interface GlyphPath {
  */
 export declare function contourToPath(contour: Contour): PathCommand[];
 /**
- * Get path commands for a glyph
+ * Get cached glyph path, computing and caching if not already cached
  */
 export declare function getGlyphPath(font: Font, glyphId: GlyphId): GlyphPath | null;
 /**
  * Convert path commands to SVG path data string
+ * Uses Math.round for ~40% faster string generation
  */
 export declare function pathToSVG(path: GlyphPath, options?: {
     flipY?: boolean;
@@ -125,6 +127,10 @@ export declare function renderShapedText(ctx: CanvasRenderingContext2D, font: Fo
     strokeWidth?: number;
     lineCap?: CanvasLineCap;
     lineJoin?: CanvasLineJoin;
+    /** 2D affine matrix to apply to glyph coordinates */
+    matrix?: Matrix2D;
+    /** 3D perspective matrix to apply to glyph coordinates (takes precedence over matrix) */
+    matrix3D?: Matrix3x3;
 }): void;
 /**
  * Generate SVG for shaped text
@@ -136,6 +142,12 @@ export declare function shapedTextToSVG(font: Font, glyphs: ShapedGlyph[], optio
     strokeWidth?: number;
     lineCap?: "butt" | "round" | "square";
     lineJoin?: "miter" | "round" | "bevel";
+    /** 2D affine matrix to apply to glyph coordinates */
+    matrix?: Matrix2D;
+    /** 3D perspective matrix to apply to glyph coordinates (takes precedence over matrix) */
+    matrix3D?: Matrix3x3;
+    /** If true, use native SVG transform attribute instead of transforming path data (2D only) */
+    useNativeTransform?: boolean;
 }): string;
 /**
  * Convert GlyphBuffer output to ShapedGlyph array
@@ -182,3 +194,46 @@ export declare function createPath2D(path: GlyphPath, options?: {
     offsetX?: number;
     offsetY?: number;
 }): Path2D;
+/**
+ * Render path to canvas with 2D affine matrix transformation applied to coordinates
+ * The matrix transforms each point before drawing
+ */
+export declare function pathToCanvasWithMatrix(ctx: CanvasRenderingContext2D | Path2D, path: GlyphPath, matrix: Matrix2D, options?: {
+    flipY?: boolean;
+}): void;
+/**
+ * Convert path to SVG with 2D affine matrix transformation applied to coordinates
+ */
+export declare function pathToSVGWithMatrix(path: GlyphPath, matrix: Matrix2D, options?: {
+    flipY?: boolean;
+}): string;
+/**
+ * Render path to canvas with 3D perspective matrix transformation
+ * Uses homogeneous coordinates for perspective projection
+ */
+export declare function pathToCanvasWithMatrix3D(ctx: CanvasRenderingContext2D | Path2D, path: GlyphPath, matrix: Matrix3x3, options?: {
+    flipY?: boolean;
+}): void;
+/**
+ * Convert path to SVG with 3D perspective matrix transformation
+ * Uses homogeneous coordinates for perspective projection
+ */
+export declare function pathToSVGWithMatrix3D(path: GlyphPath, matrix: Matrix3x3, options?: {
+    flipY?: boolean;
+}): string;
+/**
+ * Apply 2D affine matrix to canvas context using native transform
+ * Use ctx.save() before and ctx.restore() after to preserve context state
+ */
+export declare function applyMatrixToContext(ctx: CanvasRenderingContext2D, matrix: Matrix2D): void;
+/**
+ * Convert 2D affine matrix to SVG transform attribute string
+ * Returns a string like "matrix(a, b, c, d, tx, ty)"
+ */
+export declare function matrixToSVGTransform(matrix: Matrix2D): string;
+/**
+ * Direct SVG serialization with transform applied in single pass
+ * Avoids creating intermediate PathCommand arrays
+ * Uses Math.round for ~40% faster string generation
+ */
+export declare function pathToSVGDirect(path: GlyphPath, scale: number, offsetX: number, offsetY: number): string;

package/dist/shaper/complex/arabic.d.ts

@@ -56,5 +56,6 @@ export declare function analyzeJoining(infos: GlyphInfo[]): JoiningAction[];
 export declare function getFeatureForAction(action: JoiningAction): string | null;
 /**
  * Set the feature mask for each glyph based on joining analysis
+ * Inlined for performance - avoids intermediate array allocation
  */
 export declare function setupArabicMasks(infos: GlyphInfo[]): void;

package/dist/shaper/shape-plan.d.ts

@@ -7,21 +7,24 @@ export interface ShapeFeature {
     tag: Tag;
     enabled: boolean;
 }
+/** Lookup entry with index */
+export interface LookupEntry<T> {
+    index: number;
+    lookup: T;
+}
 /** Collected lookups for shaping */
 export interface ShapePlan {
     script: Tag;
     language: Tag | null;
     direction: "ltr" | "rtl";
     /** GSUB lookups to apply, in order */
-    gsubLookups: Array<{
-        index: number;
-        lookup: AnyGsubLookup;
-    }>;
+    gsubLookups: LookupEntry<AnyGsubLookup>[];
     /** GPOS lookups to apply, in order */
-    gposLookups: Array<{
-        index: number;
-        lookup: AnyGposLookup;
-    }>;
+    gposLookups: LookupEntry<AnyGposLookup>[];
+    /** Fast O(1) lookup by index for nested GSUB lookups */
+    gsubLookupMap: Map<number, LookupEntry<AnyGsubLookup>>;
+    /** Fast O(1) lookup by index for nested GPOS lookups */
+    gposLookupMap: Map<number, LookupEntry<AnyGposLookup>>;
 }
 /** Get or create a cached shape plan */
 export declare function getOrCreateShapePlan(font: Font, script: string, language: string | null, direction: "ltr" | "rtl", userFeatures?: ShapeFeature[], axisCoords?: number[] | null): ShapePlan;

package/dist/shaper/shaper.d.ts

@@ -3,16 +3,74 @@ import type { UnicodeBuffer } from "../buffer/unicode-buffer.ts";
 import { Face } from "../font/face.ts";
 import type { Font } from "../font/font.ts";
 import { type ShapeFeature } from "./shape-plan.ts";
+/**
+ * Options for controlling text shaping behavior.
+ */
 export interface ShapeOptions {
+    /** ISO 15924 script tag (e.g., "arab", "deva", "latn"). Defaults to buffer.script or "latn" */
     script?: string;
+    /** BCP 47 language tag (e.g., "en", "ar-SA", "hi-IN"). Defaults to buffer.language or null */
     language?: string | null;
+    /** Text direction: "ltr" (left-to-right) or "rtl" (right-to-left). Defaults to "ltr" */
     direction?: "ltr" | "rtl";
+    /** Array of OpenType features to apply (e.g., [{tag: "liga", value: 1}, {tag: "kern", value: 0}]) */
     features?: ShapeFeature[];
 }
-/** Font or Face - accepted by shape function */
+/**
+ * Union type accepting either Font or Face instances.
+ * Use Face for variable fonts to provide axis coordinates for feature variations.
+ * Use Font for static fonts or when default axis values are acceptable.
+ */
 export type FontLike = Font | Face;
 /**
- * Shape text using OpenType features.
- * Accepts Font or Face (for variable fonts).
+ * Return a GlyphBuffer to the pool for reuse.
+ * Call this when done with a buffer from shape() to reduce allocations.
+ * The pool has a maximum size, so buffers beyond that limit will be discarded.
+ *
+ * @param buffer - The GlyphBuffer to return to the pool
+ */
+export declare function releaseBuffer(buffer: GlyphBuffer): void;
+/**
+ * Shape text using OpenType features and complex script processing.
+ *
+ * Text shaping is the process of converting Unicode text into positioned glyphs for rendering.
+ * This involves:
+ * - Mapping characters to glyphs via the font's cmap table
+ * - Applying OpenType GSUB substitutions (ligatures, contextual forms, etc.)
+ * - Positioning glyphs via GPOS or fallback kerning/mark positioning
+ * - Complex script analysis (Arabic joining, Indic reordering, etc.)
+ * - Applying OpenType features (liga, kern, calt, etc.)
+ *
+ * The function returns a pooled GlyphBuffer for efficiency. Call releaseBuffer() when done
+ * to return it to the pool for reuse.
+ *
+ * @param fontLike - Font or Face instance (Face for variable fonts with axis coordinates)
+ * @param buffer - UnicodeBuffer containing the input text and metadata (script, language, direction)
+ * @param options - Optional shaping parameters
+ * @param options.script - ISO 15924 script tag (e.g., "arab", "deva"), defaults to buffer.script or "latn"
+ * @param options.language - BCP 47 language tag (e.g., "en", "ar-SA"), defaults to buffer.language or null
+ * @param options.direction - Text direction "ltr" or "rtl", defaults to "ltr"
+ * @param options.features - Array of OpenType features to enable/disable (e.g., [{tag: "liga", value: 1}])
+ * @returns GlyphBuffer containing shaped glyphs with positions and metadata
  */
 export declare function shape(fontLike: FontLike, buffer: UnicodeBuffer, options?: ShapeOptions): GlyphBuffer;
+/**
+ * Shape text into an existing GlyphBuffer (zero-allocation hot path).
+ *
+ * This is a performance-optimized version of shape() that reuses an existing GlyphBuffer
+ * instead of allocating a new one. Use this for maximum performance when shaping repeatedly,
+ * such as in animation loops or batch text processing.
+ *
+ * The provided GlyphBuffer will be reset and filled with the shaped output. This avoids
+ * allocations from the buffer pool and gives you full control over buffer lifecycle.
+ *
+ * @param fontLike - Font or Face instance (Face for variable fonts with axis coordinates)
+ * @param buffer - UnicodeBuffer containing the input text and metadata (script, language, direction)
+ * @param glyphBuffer - Existing GlyphBuffer to fill with shaped output (will be reset)
+ * @param options - Optional shaping parameters
+ * @param options.script - ISO 15924 script tag (e.g., "arab", "deva"), defaults to buffer.script or "latn"
+ * @param options.language - BCP 47 language tag (e.g., "en", "ar-SA"), defaults to buffer.language or null
+ * @param options.direction - Text direction "ltr" or "rtl", defaults to "ltr"
+ * @param options.features - Array of OpenType features to enable/disable (e.g., [{tag: "liga", value: 1}])
+ */
+export declare function shapeInto(fontLike: FontLike, buffer: UnicodeBuffer, glyphBuffer: GlyphBuffer, options?: ShapeOptions): void;

package/dist/unicode/bidi/brackets.d.ts

@@ -2,6 +2,21 @@
  * Bidi bracket pair functions
  * Port of bidi-js brackets.js
  */
+/**
+ * Get the closing bracket character for an opening bracket
+ * @param char Opening bracket character
+ * @returns Corresponding closing bracket character, or null if not an opening bracket
+ */
 export declare function openingToClosingBracket(char: string): string | null;
+/**
+ * Get the opening bracket character for a closing bracket
+ * @param char Closing bracket character
+ * @returns Corresponding opening bracket character, or null if not a closing bracket
+ */
 export declare function closingToOpeningBracket(char: string): string | null;
+/**
+ * Get the canonical bracket character for a bracket
+ * @param char Bracket character
+ * @returns Canonical form of the bracket character, or null if not applicable
+ */
 export declare function getCanonicalBracket(char: string): string | null;

package/dist/unicode/bidi/char-types.d.ts

@@ -11,9 +11,13 @@ export declare const BN_LIKE_TYPES: number;
 export declare const TRAILING_TYPES: number;
 /**
  * Get the bidi character type for a character
+ * @param char Character to check
+ * @returns Bidi character type as a bitmask
  */
 export declare function getBidiCharType(char: string): number;
 /**
  * Get the name of a bidi character type
+ * @param char Character to check
+ * @returns Bidi character type name (e.g., "L", "R", "EN", "AN", etc.)
  */
 export declare function getBidiCharTypeName(char: string): string;

package/dist/unicode/bidi/embedding-levels.d.ts

@@ -14,5 +14,8 @@ export interface EmbeddingLevelsResult {
  * This function applies the Bidirectional Algorithm to a string, returning the resolved embedding levels
  * in a single Uint8Array plus a list of objects holding each paragraph's start and end indices and resolved
  * base embedding level.
+ * @param string Text string to process
+ * @param baseDirection Base text direction: "ltr", "rtl", or "auto"
+ * @returns Object containing embedding levels array and paragraph information
  */
 export declare function getEmbeddingLevels(string: string, baseDirection?: "ltr" | "rtl" | "auto"): EmbeddingLevelsResult;

package/dist/unicode/bidi/mirroring.d.ts

@@ -2,9 +2,19 @@
  * Bidi character mirroring
  * Port of bidi-js mirroring.js
  */
+/**
+ * Get the mirrored version of a character for BiDi display
+ * @param char Character to mirror
+ * @returns Mirrored character, or null if character has no mirror
+ */
 export declare function getMirroredCharacter(char: string): string | null;
 /**
  * Given a string and its resolved embedding levels, build a map of indices to replacement chars
  * for any characters in right-to-left segments that have defined mirrored characters.
+ * @param string Text string to process
+ * @param embeddingLevels Resolved embedding levels from getEmbeddingLevels
+ * @param start Start index (defaults to 0)
+ * @param end End index (defaults to string length - 1)
+ * @returns Map of character indices to their mirrored replacements
  */
 export declare function getMirroredCharactersMap(string: string, embeddingLevels: Uint8Array, start?: number, end?: number): Map<number, string>;

package/dist/unicode/bidi/reordering.d.ts

@@ -6,13 +6,28 @@ import type { EmbeddingLevelsResult } from "./embedding-levels.ts";
 /**
  * Given a start and end denoting a single line within a string, and a set of precalculated
  * bidi embedding levels, produce a list of segments whose ordering should be flipped, in sequence.
+ * @param string Text string to process
+ * @param embeddingLevelsResult Result from getEmbeddingLevels
+ * @param start Start index (defaults to 0)
+ * @param end End index (defaults to string length - 1)
+ * @returns Array of segment ranges [start, end] to be reversed
  */
 export declare function getReorderSegments(string: string, embeddingLevelsResult: EmbeddingLevelsResult, start?: number, end?: number): Array<[number, number]>;
 /**
  * Get the reordered string with bidi segments reversed
+ * @param string Text string to reorder
+ * @param embedLevelsResult Result from getEmbeddingLevels
+ * @param start Start index (defaults to 0)
+ * @param end End index (defaults to string length - 1)
+ * @returns Reordered string with BiDi applied
  */
 export declare function getReorderedString(string: string, embedLevelsResult: EmbeddingLevelsResult, start?: number, end?: number): string;
 /**
  * Get an array with character indices in their new bidi order
+ * @param string Text string to process
+ * @param embedLevelsResult Result from getEmbeddingLevels
+ * @param start Start index (defaults to 0)
+ * @param end End index (defaults to string length - 1)
+ * @returns Array mapping new positions to original character indices
  */
 export declare function getReorderedIndices(string: string, embedLevelsResult: EmbeddingLevelsResult, start?: number, end?: number): number[];

package/dist/unicode/normalize.d.ts

@@ -15,22 +15,45 @@ export declare enum NormalizationMode {
 /**
  * Canonical Combining Class (ccc) for combining marks
  * Based on Unicode 15.0
+ *
+ * Optimized with early-exit for common non-combining ranges:
+ * - Basic Latin (0000-007F)
+ * - Latin-1 Supplement (0080-00FF)
+ * - Latin Extended-A/B (0100-024F)
+ * - IPA Extensions (0250-02AF)
+ * - Spacing Modifier Letters (02B0-02FF) - most are spacing
+ * - Greek and Coptic (0370-03FF) - base chars only
+ * - Cyrillic (0400-04FF)
+ * - Cyrillic Supplement (0500-052F)
+ * - CJK ranges (3000+)
+ * - Hangul (AC00-D7AF)
+ * @param cp Unicode codepoint to check
+ * @returns Canonical combining class (0 for non-combining characters, 1-255 for combining marks)
  */
 export declare function getCombiningClass(cp: number): number;
 /**
  * Reorder combining marks according to canonical combining class
+ * @param infos Array of glyph information objects (modified in place)
  */
 export declare function reorderMarks(infos: GlyphInfo[]): void;
 /**
  * Decompose a codepoint if it has a canonical decomposition
+ * @param cp Unicode codepoint to decompose
+ * @returns Array of decomposed codepoints, or null if character has no decomposition
  */
 export declare function decompose(cp: number): number[] | null;
 /**
  * Try to compose a base character with a combining mark
  * Returns the composed character or null if no composition exists
+ * @param base Base character codepoint
+ * @param combining Combining mark codepoint
+ * @returns Composed character codepoint, or null if no composition exists
  */
 export declare function tryCompose(base: number, combining: number): number | null;
 /**
  * Apply normalization to glyph infos
+ * @param infos Array of glyph information objects
+ * @param mode Normalization mode (None, Decompose, Compose, or Auto)
+ * @returns Normalized array of glyph information objects
  */
 export declare function normalize(infos: GlyphInfo[], mode: NormalizationMode): GlyphInfo[];

package/dist/unicode/script.d.ts

@@ -173,19 +173,28 @@ export declare enum Script {
 }
 /**
  * Get script for a codepoint using binary search
+ * @param cp Unicode codepoint to check
+ * @returns The script for the given codepoint
  */
 export declare function getScript(cp: number): Script;
 /**
  * Get script for a string (returns the dominant non-Common/Inherited script)
+ * @param text Text string to analyze
+ * @returns The dominant script found in the text (most frequent non-Common/Inherited script)
  */
 export declare function detectScript(text: string): Script;
 /**
  * Get all scripts present in text
+ * @param text Text string to analyze
+ * @returns Array of all scripts found in the text
  */
 export declare function getScripts(text: string): Script[];
 /**
  * Check if text contains only characters from a specific script
  * (Common and Inherited are allowed)
+ * @param text Text string to check
+ * @param script Script to check against
+ * @returns True if text contains only characters from the specified script (plus Common/Inherited)
  */
 export declare function isScript(text: string, script: Script): boolean;
 /**
@@ -199,17 +208,25 @@ export interface ScriptRun {
 }
 /**
  * Split text into script runs
+ * @param text Text string to split
+ * @returns Array of script runs, where each run is a contiguous sequence of characters with the same script
  */
 export declare function getScriptRuns(text: string): ScriptRun[];
 /**
  * Get OpenType script tag for a Unicode script
+ * @param script Unicode script to convert
+ * @returns OpenType script tag (4-character string like "latn", "arab", etc.)
  */
 export declare function getScriptTag(script: Script): string;
 /**
  * Check if a script requires complex shaping
+ * @param script Script to check
+ * @returns True if the script requires complex shaping (e.g., Arabic, Devanagari, Thai)
  */
 export declare function isComplexScript(script: Script): boolean;
 /**
  * Get script direction (LTR or RTL)
+ * @param script Script to check
+ * @returns Direction of the script: "ltr" for left-to-right or "rtl" for right-to-left
  */
 export declare function getScriptDirection(script: Script): "ltr" | "rtl";

package/dist/unicode/segmentation.d.ts

@@ -50,10 +50,14 @@ export declare enum WordBreakProperty {
 }
 /**
  * Get grapheme break property for codepoint
+ * @param cp Unicode codepoint to check
+ * @returns Grapheme break property for the codepoint
  */
 export declare function getGraphemeBreakProperty(cp: number): GraphemeBreakProperty;
 /**
  * Get word break property for codepoint
+ * @param cp Unicode codepoint to check
+ * @returns Word break property for the codepoint
  */
 export declare function getWordBreakProperty(cp: number): WordBreakProperty;
 /**
@@ -67,6 +71,8 @@ export interface GraphemeBoundaries {
 }
 /**
  * Find grapheme cluster boundaries in codepoints
+ * @param codepoints Array of Unicode codepoints
+ * @returns Object containing boundary positions and grapheme break properties
  */
 export declare function findGraphemeBoundaries(codepoints: number[]): GraphemeBoundaries;
 /**
@@ -80,25 +86,37 @@ export interface WordBoundaries {
 }
 /**
  * Find word boundaries in codepoints
+ * @param codepoints Array of Unicode codepoints
+ * @returns Object containing boundary positions and word break properties
  */
 export declare function findWordBoundaries(codepoints: number[]): WordBoundaries;
 /**
  * Split text into grapheme clusters
+ * @param text Text string to split
+ * @returns Array of grapheme cluster strings
  */
 export declare function splitGraphemes(text: string): string[];
 /**
  * Split text into words
+ * @param text Text string to split
+ * @returns Array of word strings (whitespace-only segments are filtered out)
  */
 export declare function splitWords(text: string): string[];
 /**
  * Count grapheme clusters in text
+ * @param text Text string to analyze
+ * @returns Number of grapheme clusters in the text
  */
 export declare function countGraphemes(text: string): number;
 /**
  * Analyze grapheme boundaries for glyph infos
+ * @param infos Array of glyph information objects
+ * @returns Object containing boundary positions and grapheme break properties
  */
 export declare function analyzeGraphemesForGlyphs(infos: GlyphInfo[]): GraphemeBoundaries;
 /**
  * Analyze word boundaries for glyph infos
+ * @param infos Array of glyph information objects
+ * @returns Object containing boundary positions and word break properties
  */
 export declare function analyzeWordsForGlyphs(infos: GlyphInfo[]): WordBoundaries;

package/package.json

@@ -1,11 +1,15 @@
 {
   "name": "text-shaper",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "devDependencies": {
     "@biomejs/biome": "2.3.8",
     "@types/bun": "latest",
+    "@types/opentype.js": "^1.3.8",
+    "freetype2": "^2.1.0",
+    "harfbuzzjs": "^0.4.13",
+    "opentype.js": "^1.3.4",
     "vitepress": "^2.0.0-alpha.15",
     "vitepress-plugin-llms": "^1.9.3"
   },
@@ -43,6 +47,8 @@
   ],
   "license": "MIT",
   "scripts": {
+    "postinstall": "node scripts/patch-pkg-prebuilds.js",
+    "bench": "bun test ./bench/ --timeout 120000",
     "build": "bun build ./src/index.ts --outdir ./dist --target browser --minify --sourcemap=linked",
     "build:prod": "bun build ./src/index.ts --outdir ./dist --target browser --production --sourcemap=external",
     "build:analyze": "bun build ./src/index.ts --outdir ./dist --target browser --minify --metafile=./dist/meta.json",
@@ -56,5 +62,8 @@
     "docs:preview": "vitepress preview docs"
   },
   "type": "module",
-  "types": "./dist/index.d.ts"
-}
+  "types": "./dist/index.d.ts",
+  "trustedDependencies": [
+    "freetype2"
+  ]
+}