text-shaper 0.1.2 → 0.1.3

package/dist/raster/lcd-filter.d.ts

@@ -35,10 +35,25 @@ export declare enum LcdMode {
  * 1. Render at 3x horizontal resolution
  * 2. Apply FIR filter to reduce color fringing
  * 3. Output RGB values per pixel
+ *
+ * @param path Glyph path to rasterize
+ * @param width Width in pixels
+ * @param height Height in pixels
+ * @param scale Scale factor from font units to pixels
+ * @param offsetX X offset in pixels
+ * @param offsetY Y offset in pixels
+ * @param mode LCD subpixel mode (RGB, BGR, RGB_V, BGR_V)
+ * @param filterWeights FIR filter coefficients for reducing color fringing
+ * @returns Bitmap with LCD subpixel data (3 bytes per pixel)
  */
 export declare function rasterizeLcd(path: GlyphPath, width: number, height: number, scale: number, offsetX: number, offsetY: number, mode?: LcdMode, filterWeights?: number[]): Bitmap;
 /**
  * Convert LCD bitmap to RGBA for display
  * Uses gamma-corrected blending against a background color
+ *
+ * @param lcd LCD bitmap to convert
+ * @param bgColor Background color as RGB (0-255 each)
+ * @param fgColor Foreground color as RGB (0-255 each)
+ * @returns RGBA pixel array (4 bytes per pixel)
  */
 export declare function lcdToRGBA(lcd: Bitmap, bgColor?: [number, number, number], fgColor?: [number, number, number]): Uint8Array;

package/dist/raster/msdf.d.ts

@@ -29,27 +29,36 @@ export interface Point {
  */
 export type EdgeColor = 0 | 1 | 2;
 /**
- * An edge with color assignment
+ * Bounding box for edge culling
  */
-export type MsdfEdge = {
+interface EdgeBounds {
+    minX: number;
+    maxX: number;
+    minY: number;
+    maxY: number;
+}
+/**
+ * An edge with color assignment and bounding box
+ */
+export type MsdfEdge = ({
     type: "line";
     p0: Point;
     p1: Point;
     color: EdgeColor;
-} | {
+} & EdgeBounds) | ({
     type: "quadratic";
     p0: Point;
     p1: Point;
     p2: Point;
     color: EdgeColor;
-} | {
+} & EdgeBounds) | ({
     type: "cubic";
     p0: Point;
     p1: Point;
     p2: Point;
     p3: Point;
     color: EdgeColor;
-};
+} & EdgeBounds);
 /**
  * Signed distance result with parameter t
  */
@@ -123,3 +132,4 @@ export declare function msdfAtlasToRGB(atlas: GlyphAtlas): Uint8Array;
  * Export MSDF atlas as RGBA texture data
  */
 export declare function msdfAtlasToRGBA(atlas: GlyphAtlas): Uint8Array;
+export {};

package/dist/raster/outline-decompose.d.ts

@@ -22,28 +22,28 @@ export interface ValidationResult {
 }
 /**
  * Validate a GlyphPath before rasterization (like FreeType's outline validation)
- *
- * Checks:
- * - Path is not null/undefined
- * - Commands array exists
- * - Path is not empty (unless allowEmpty is true)
- * - Command structure is valid
- * - Contours are properly closed (start with M, end with Z)
+ * Checks: path existence, command structure validity, and proper contour closure
+ * @param path Glyph path to validate
+ * @param allowEmpty Whether empty paths are considered valid (default: true)
+ * @returns Validation result with error code and optional message
  */
 export declare function validateOutline(path: GlyphPath | null | undefined, allowEmpty?: boolean): ValidationResult;
 /**
  * Convert a GlyphPath to rasterizer commands
- *
- * @param raster - The rasterizer instance
- * @param path - Path commands to decompose
- * @param scale - Scale factor (font units to pixels)
- * @param offsetX - X offset in pixels
- * @param offsetY - Y offset in pixels
- * @param flipY - Flip Y axis (font coords are Y-up)
+ * @param raster The rasterizer instance to receive commands
+ * @param path Path commands to decompose
+ * @param scale Scale factor (font units to pixels)
+ * @param offsetX X offset in pixels (default: 0)
+ * @param offsetY Y offset in pixels (default: 0)
+ * @param flipY Flip Y axis - font coords are Y-up, bitmap is Y-down (default: true)
  */
 export declare function decomposePath(raster: GrayRaster, path: GlyphPath, scale: number, offsetX?: number, offsetY?: number, flipY?: boolean): void;
 /**
  * Calculate bounding box of path in pixel coordinates
+ * @param path Glyph path to measure
+ * @param scale Scale factor (font units to pixels)
+ * @param flipY Flip Y axis for bitmap coordinates (default: true)
+ * @returns Bounding box in pixel coordinates, or null if path has no bounds
  */
 export declare function getPathBounds(path: GlyphPath, scale: number, flipY?: boolean): {
     minX: number;
@@ -53,9 +53,8 @@ export declare function getPathBounds(path: GlyphPath, scale: number, flipY?: bo
 } | null;
 /**
  * Get fill rule from outline flags (like FreeType's FT_OUTLINE_EVEN_ODD_FILL check)
- *
  * @param path Path with optional flags
- * @param defaultRule Default fill rule if flags not set
- * @returns Fill rule to use
+ * @param defaultRule Default fill rule if flags not set (default: NonZero)
+ * @returns Fill rule to use for rendering
  */
 export declare function getFillRuleFromFlags(path: GlyphPath | null | undefined, defaultRule?: FillRule): FillRule;

package/dist/raster/rasterize.d.ts

@@ -7,10 +7,18 @@ import type { GlyphId } from "../types.ts";
 import { type Bitmap, PixelMode, type RasterizedGlyph, type RasterizeOptions } from "./types.ts";
 /**
  * Rasterize a glyph path to a bitmap
+ * @param path Glyph path to rasterize
+ * @param options Rasterization options including dimensions, scale, and pixel mode
+ * @returns Rendered bitmap of the glyph
  */
 export declare function rasterizePath(path: GlyphPath, options: RasterizeOptions): Bitmap;
 /**
  * Rasterize a glyph from a font
+ * @param font Font containing the glyph
+ * @param glyphId ID of the glyph to rasterize
+ * @param fontSize Font size in pixels
+ * @param options Optional rendering settings (pixel mode, padding, hinting)
+ * @returns Rasterized glyph with bitmap and bearing information, or null if glyph is empty
  */
 export declare function rasterizeGlyph(font: Font, glyphId: GlyphId, fontSize: number, options?: {
     pixelMode?: PixelMode;
@@ -20,6 +28,11 @@ export declare function rasterizeGlyph(font: Font, glyphId: GlyphId, fontSize: n
 }): RasterizedGlyph | null;
 /**
  * Rasterize text string using shaped glyphs
+ * @param font Font to use for rendering
+ * @param text Text string to rasterize
+ * @param fontSize Font size in pixels
+ * @param options Optional rendering settings (pixel mode, padding)
+ * @returns Bitmap containing rendered text, or null if no glyphs
  */
 export declare function rasterizeText(font: Font, text: string, fontSize: number, options?: {
     pixelMode?: PixelMode;
@@ -27,17 +40,21 @@ export declare function rasterizeText(font: Font, text: string, fontSize: number
 }): Bitmap | null;
 /**
  * Export bitmap to raw RGBA pixels (for WebGL textures, etc.)
+ * @param bitmap Source bitmap to convert
+ * @returns RGBA pixel array (4 bytes per pixel)
  */
 export declare function bitmapToRGBA(bitmap: Bitmap): Uint8Array;
 /**
  * Export bitmap to grayscale array
+ * @param bitmap Source bitmap to convert
+ * @returns Grayscale pixel array (1 byte per pixel)
  */
 export declare function bitmapToGray(bitmap: Bitmap): Uint8Array;
 export { type BBox, evaluateCubic, evaluateQuadratic, getCubicExtrema, getExactBounds, getQuadraticExtrema, } from "./bbox.ts";
-export { blendBitmap, convertBitmap, copyBitmap, emboldenBitmap, resizeBitmap, } from "./bitmap-utils.ts";
+export { blendBitmap, convertBitmap, copyBitmap, emboldenBitmap, resizeBitmap, resizeBitmapBilinear, } from "./bitmap-utils.ts";
 export { blurBitmap, boxBlur, createGaussianKernel, gaussianBlur, } from "./blur.ts";
 export { type ColorStop, createGradientBitmap, type Gradient, interpolateGradient, type LinearGradient, type RadialGradient, rasterizePathWithGradient, } from "./gradient.ts";
 export { renderSdf, type SdfOptions } from "./sdf.ts";
 export { type LineCap, type LineJoin, type StrokerOptions, strokePath, } from "./stroker.ts";
 export { condensePath, emboldenPath, obliquePath, transformPath, } from "./synth.ts";
-export { type Bitmap, clearBitmap, createBitmap, FillRule, PixelMode, type RasterizedGlyph, type RasterizeOptions, type Span, } from "./types.ts";
+export { type Bitmap, clearBitmap, createBitmap, createBottomUpBitmap, FillRule, PixelMode, type RasterizedGlyph, type RasterizeOptions, type Span, } from "./types.ts";

package/dist/raster/sdf.d.ts

@@ -33,5 +33,8 @@ export interface SdfOptions {
 }
 /**
  * Render a glyph path as a signed distance field
+ * @param path Glyph path to render
+ * @param options SDF rendering options (dimensions, scale, spread)
+ * @returns Grayscale bitmap with signed distance field (128 = on edge, 255 = inside, 0 = outside)
  */
 export declare function renderSdf(path: GlyphPath, options: SdfOptions): Bitmap;

package/dist/raster/stroker.d.ts

@@ -25,5 +25,8 @@ export interface StrokerOptions {
 }
 /**
  * Stroke a glyph path, producing a new path that represents the stroked outline
+ * @param path Input glyph path to stroke
+ * @param options Stroke parameters (width, cap style, join style, miter limit)
+ * @returns New path representing the stroked outline that can be filled
  */
 export declare function strokePath(path: GlyphPath, options: StrokerOptions): GlyphPath;

package/dist/raster/types.d.ts

@@ -177,15 +177,24 @@ export interface MsdfAtlasOptions {
 }
 /**
  * Create an empty bitmap
+ * @param width Width in pixels
+ * @param height Height in pixels
+ * @param pixelMode Pixel format (default: Gray)
+ * @returns Empty bitmap with the specified dimensions and format
  */
 export declare function createBitmap(width: number, height: number, pixelMode?: PixelMode): Bitmap;
 /**
  * Clear a bitmap to zero
+ * @param bitmap Bitmap to clear
  */
 export declare function clearBitmap(bitmap: Bitmap): void;
 /**
  * Create a bottom-up bitmap (negative pitch)
  * Bottom-up bitmaps have row 0 at the bottom of the image,
  * which matches some graphics APIs (e.g., Windows DIB, OpenGL textures)
+ * @param width Width in pixels
+ * @param height Height in pixels
+ * @param pixelMode Pixel format (default: Gray)
+ * @returns Bottom-up bitmap with row 0 at the bottom
  */
 export declare function createBottomUpBitmap(width: number, height: number, pixelMode?: PixelMode): Bitmap;

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";