text-shaper 0.1.1 → 0.1.3

package/README.md

@@ -185,3 +185,4 @@ fpgm, prep, cvt, gasp
 ## License
 
 [MIT](LICENSE)
+

package/dist/aat/state-machine.d.ts

@@ -12,23 +12,35 @@ export interface StateMachineContext {
     stack: number[];
 }
 /**
- * Get class for a glyph
+ * Get the class value for a glyph from the class table
+ * @param classTable - The class lookup table
+ * @param glyphId - The glyph ID to look up
+ * @returns The class value, or CLASS_OUT_OF_BOUNDS if the glyph is not in the table
  */
 export declare function getGlyphClass(classTable: ClassTable, glyphId: GlyphId): number;
 /**
- * Process rearrangement subtable
- * Reorders glyphs based on state machine
+ * Process rearrangement subtable to reorder glyphs based on state machine rules
+ * @param subtable - The rearrangement subtable containing state machine and rules
+ * @param infos - Array of glyph infos to be reordered in place
  */
 export declare function processRearrangement(subtable: MorxRearrangementSubtable, infos: GlyphInfo[]): void;
 /**
- * Process contextual substitution subtable
+ * Process contextual substitution subtable to replace glyphs based on context
+ * @param subtable - The contextual subtable containing state machine and substitution tables
+ * @param infos - Array of glyph infos to be modified in place with contextual substitutions
  */
 export declare function processContextual(subtable: MorxContextualSubtable, infos: GlyphInfo[]): void;
 /**
- * Process ligature subtable
+ * Process ligature subtable to combine multiple glyphs into ligatures
+ * @param subtable - The ligature subtable containing state machine, actions, and component tables
+ * @param infos - Array of glyph infos to process
+ * @returns New array of glyph infos with ligatures applied and component glyphs removed
  */
 export declare function processLigature(subtable: MorxLigatureSubtable, infos: GlyphInfo[]): GlyphInfo[];
 /**
- * Process insertion subtable
+ * Process insertion subtable to insert additional glyphs before or after existing glyphs
+ * @param subtable - The insertion subtable containing state machine and insertion glyph table
+ * @param infos - Array of glyph infos to process
+ * @returns New array of glyph infos with inserted glyphs added at specified positions
  */
 export declare function processInsertion(subtable: MorxInsertionSubtable, infos: GlyphInfo[]): GlyphInfo[];

package/dist/buffer/glyph-buffer.d.ts

@@ -1,3 +1,4 @@
+import type { Font } from "../font/font.ts";
 import { Direction, type GlyphId, type GlyphInfo, type GlyphPosition } from "../types.ts";
 /**
  * Output buffer containing shaped glyphs.
@@ -14,10 +15,29 @@ export declare class GlyphBuffer {
     infos: GlyphInfo[];
     /** Glyph position array */
     positions: GlyphPosition[];
-    /** Create buffer with pre-allocated capacity */
+    /** Deleted glyph markers for deferred removal */
+    private _deleted;
+    /** Count of deleted glyphs pending compaction */
+    private _deletedCount;
+    /** Pre-allocated info pool for reuse */
+    private _infoPool;
+    /** Pre-allocated position pool for reuse */
+    private _posPool;
+    /** Create buffer with pre-allocated capacity (lazy object creation) */
     static withCapacity(capacity: number): GlyphBuffer;
+    /** Hint for initial capacity (used for lazy allocation) */
+    private _capacity;
     /** Number of glyphs */
     get length(): number;
+    /** Reset buffer for reuse - reuses existing object pool */
+    reset(): void;
+    /** Initialize from codepoints, reusing pooled objects when possible */
+    initFromCodepoints(codepoints: ArrayLike<number>, clusters: ArrayLike<number>, getGlyphId: (codepoint: number) => number): void;
+    /**
+     * Initialize from codepoints with direct font access (no closure).
+     * This is faster than initFromCodepoints for hot paths.
+     */
+    initFromCodepointsWithFont(codepoints: ArrayLike<number>, clusters: ArrayLike<number>, font: Font): void;
     /** Initialize from glyph infos (positions zeroed) */
     initFromInfos(infos: GlyphInfo[]): void;
     /** Set advance width for a glyph */
@@ -30,6 +50,20 @@ export declare class GlyphBuffer {
     insertGlyph(index: number, info: GlyphInfo, position: GlyphPosition): void;
     /** Remove glyphs in range [start, end) */
     removeRange(start: number, end: number): void;
+    /**
+     * Mark a glyph for deferred deletion. Much faster than removeRange for
+     * multiple deletions - call compact() once at end of GSUB phase.
+     */
+    markDeleted(index: number): void;
+    /** Check if a glyph is marked for deletion */
+    isDeleted(index: number): boolean;
+    /** Returns true if there are pending deletions */
+    hasPendingDeletions(): boolean;
+    /**
+     * Compact buffer by removing all marked-for-deletion glyphs in a single O(n) pass.
+     * Call this after GSUB phase.
+     */
+    compact(): void;
     /** Merge clusters from start to end (inclusive) */
     mergeClusters(start: number, end: number): void;
     /** Reverse glyph order (for RTL) */

package/dist/buffer/unicode-buffer.d.ts

@@ -19,6 +19,8 @@ export declare class UnicodeBuffer {
     postContext: number[];
     /** Add a string to the buffer */
     addStr(text: string, startCluster?: number): this;
+    /** Append to existing buffer (slower path) */
+    private _addStrAppend;
     /** Add codepoints directly */
     addCodepoints(codepoints: number[], startCluster?: number): this;
     /** Add a single codepoint */

package/dist/fluent/bitmap-builder.d.ts

@@ -0,0 +1,146 @@
+/**
+ * BitmapBuilder: Fluent builder for raster bitmap operations
+ *
+ * All operations are eager (applied immediately) and return new builder instances
+ */
+import { type Gradient } from "../raster/gradient.ts";
+import { type Bitmap, PixelMode, type RasterizedGlyph } from "../raster/types.ts";
+/**
+ * BitmapBuilder provides a fluent interface for bitmap manipulations
+ */
+export declare class BitmapBuilder {
+    private readonly _bitmap;
+    private readonly _bearingX;
+    private readonly _bearingY;
+    private constructor();
+    /**
+     * Create from existing bitmap
+     */
+    static fromBitmap(bitmap: Bitmap): BitmapBuilder;
+    /**
+     * Create from existing bitmap with bearing info
+     */
+    static fromBitmapWithBearing(bitmap: Bitmap, bearingX: number, bearingY: number): BitmapBuilder;
+    /**
+     * Create from rasterized glyph result
+     */
+    static fromRasterizedGlyph(glyph: RasterizedGlyph): BitmapBuilder;
+    /**
+     * Create empty bitmap
+     */
+    static create(width: number, height: number, pixelMode?: PixelMode): BitmapBuilder;
+    /**
+     * Create gradient bitmap
+     */
+    static fromGradient(width: number, height: number, gradient: Gradient): BitmapBuilder;
+    /**
+     * Gaussian blur
+     */
+    blur(radius: number): BitmapBuilder;
+    /**
+     * Box blur (faster, less smooth)
+     */
+    boxBlur(radius: number): BitmapBuilder;
+    /**
+     * Cascade blur (fast for large radii, O(1) per pixel)
+     */
+    cascadeBlur(radiusX: number, radiusY?: number): BitmapBuilder;
+    /**
+     * Adaptive blur (auto-selects best algorithm based on radius)
+     */
+    adaptiveBlur(radiusX: number, radiusY?: number): BitmapBuilder;
+    /**
+     * Fast Gaussian blur using cascade algorithm
+     * Recommended for large radii (> 3 pixels)
+     */
+    fastBlur(radius: number): BitmapBuilder;
+    /**
+     * Embolden (dilate) bitmap
+     */
+    embolden(xStrength: number, yStrength?: number): BitmapBuilder;
+    /**
+     * Shift bitmap position
+     */
+    shift(dx: number, dy: number): BitmapBuilder;
+    /**
+     * Resize with nearest-neighbor interpolation
+     */
+    resize(width: number, height: number): BitmapBuilder;
+    /**
+     * Resize with bilinear interpolation (smoother, better for downsampling)
+     */
+    resizeBilinear(width: number, height: number): BitmapBuilder;
+    /**
+     * Pad bitmap with empty space
+     */
+    pad(left: number, top: number, right: number, bottom: number): BitmapBuilder;
+    pad(all: number): BitmapBuilder;
+    /**
+     * Alpha blend another bitmap onto this one at position
+     */
+    blend(other: BitmapBuilder | Bitmap, x: number, y: number, opacity?: number): BitmapBuilder;
+    /**
+     * Composite another bitmap using Porter-Duff "over" operation
+     */
+    composite(other: BitmapBuilder | Bitmap, x?: number, y?: number): BitmapBuilder;
+    /**
+     * Additive blend: result = clamp(this + other, 0, 255)
+     */
+    add(other: BitmapBuilder | Bitmap, x?: number, y?: number): BitmapBuilder;
+    /**
+     * Subtractive blend: result = clamp(this - other, 0, 255)
+     */
+    subtract(other: BitmapBuilder | Bitmap, x?: number, y?: number): BitmapBuilder;
+    /**
+     * Multiplicative blend: result = (this * other) / 255
+     */
+    multiply(other: BitmapBuilder | Bitmap, x?: number, y?: number): BitmapBuilder;
+    /**
+     * Maximum blend: result = max(this, other)
+     */
+    max(other: BitmapBuilder | Bitmap, x?: number, y?: number): BitmapBuilder;
+    /**
+     * Convert to different pixel mode
+     */
+    convert(targetMode: PixelMode): BitmapBuilder;
+    /**
+     * Get RGBA pixel array (for canvas ImageData, WebGL textures)
+     */
+    toRGBA(): Uint8Array;
+    /**
+     * Get grayscale array
+     */
+    toGray(): Uint8Array;
+    /**
+     * Get raw bitmap (cloned)
+     */
+    toBitmap(): Bitmap;
+    /**
+     * Get bitmap with bearing info
+     */
+    toRasterizedGlyph(): RasterizedGlyph;
+    /**
+     * Clone this builder
+     */
+    clone(): BitmapBuilder;
+    /**
+     * Get bitmap width
+     */
+    get width(): number;
+    /**
+     * Get bitmap height (rows)
+     */
+    get height(): number;
+    /**
+     * Get pixel mode
+     */
+    get pixelMode(): PixelMode;
+    /**
+     * Get horizontal bearing
+     */
+    get bearingX(): number;
+    /**
+     * Get vertical bearing
+     */
+    get bearingY(): number;
+}

package/dist/fluent/index.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Fluent API for transform and rendering operations
+ *
+ * Provides two styles of composition:
+ * 1. Builder pattern: glyph(font, id).scale(2).blur(5).toRGBA()
+ * 2. Pipe pattern: pipe(path, scale(2), rasterize(...), blur(5), toRGBA)
+ */
+import type { Font } from "../font/font.ts";
+import { atlasToAlpha, atlasToRGBA, buildAsciiAtlas, buildAtlas, buildStringAtlas, getGlyphUV } from "../raster/atlas.ts";
+import { buildMsdfAsciiAtlas, buildMsdfAtlas, buildMsdfStringAtlas, msdfAtlasToRGB, msdfAtlasToRGBA } from "../raster/msdf.ts";
+import { rasterizeGlyph, rasterizeText } from "../raster/rasterize.ts";
+import type { AtlasOptions, Bitmap, GlyphAtlas, MsdfAtlasOptions } from "../raster/types.ts";
+import type { GlyphPath } from "../render/path.ts";
+import { renderShapedText, renderShapedTextWithVariation, shapedTextToSVG, shapedTextToSVGWithVariation } from "../render/path.ts";
+import type { GlyphId } from "../types.ts";
+import { BitmapBuilder } from "./bitmap-builder.ts";
+import { PathBuilder } from "./path-builder.ts";
+export { BitmapBuilder } from "./bitmap-builder.ts";
+export { PathBuilder } from "./path-builder.ts";
+export type { AutoRasterOptions, CanvasOptions, RasterOptions, SVGElementOptions, SVGOptions, TransformState, } from "./types.ts";
+/**
+ * Create PathBuilder from a font glyph
+ *
+ * @example
+ * ```typescript
+ * const rgba = glyph(font, glyphId)
+ *   ?.scale(2)
+ *   .rotateDeg(15)
+ *   .rasterizeAuto({ padding: 2 })
+ *   .blur(5)
+ *   .toRGBA();
+ * ```
+ */
+export declare function glyph(font: Font, glyphId: GlyphId): PathBuilder | null;
+/**
+ * Create PathBuilder from a character in a font
+ *
+ * @example
+ * ```typescript
+ * const rgba = char(font, "A")
+ *   ?.scale(2)
+ *   .rasterizeAuto()
+ *   .toRGBA();
+ * ```
+ */
+export declare function char(font: Font, character: string): PathBuilder | null;
+/**
+ * Create PathBuilder from a font glyph with variable font coordinates
+ *
+ * @example
+ * ```typescript
+ * const rgba = glyphVar(font, glyphId, [400, 100])  // weight=400, width=100
+ *   ?.scale(2)
+ *   .rasterizeAuto()
+ *   .toRGBA();
+ * ```
+ */
+export declare function glyphVar(font: Font, glyphId: GlyphId, axisCoords: number[]): PathBuilder | null;
+/**
+ * Wrap an existing GlyphPath in a PathBuilder
+ *
+ * @example
+ * ```typescript
+ * const existingPath = getGlyphPath(font, glyphId);
+ * const rgba = path(existingPath)
+ *   .scale(2)
+ *   .rasterizeAuto()
+ *   .toRGBA();
+ * ```
+ */
+export declare function path(p: GlyphPath): PathBuilder;
+/**
+ * Wrap an existing Bitmap in a BitmapBuilder
+ *
+ * @example
+ * ```typescript
+ * const existingBitmap = rasterizePath(path, options);
+ * const rgba = bitmap(existingBitmap)
+ *   .blur(5)
+ *   .toRGBA();
+ * ```
+ */
+export declare function bitmap(b: Bitmap): BitmapBuilder;
+/**
+ * Combine multiple PathBuilders into one
+ *
+ * @example
+ * ```typescript
+ * const h = glyph(font, hGlyphId)?.translate(0, 0);
+ * const i = glyph(font, iGlyphId)?.translate(100, 0);
+ * if (h && i) {
+ *   const combined = combine(h, i).scale(2).rasterizeAuto().toRGBA();
+ * }
+ * ```
+ */
+export declare function combine(...paths: PathBuilder[]): PathBuilder;
+export { adaptiveBlur, blur, boxBlur, cascadeBlur, clone, combinePaths, condensePath, convert, copy, embolden, emboldenPath, fastBlur, fromGlyph, italic, matrix, obliquePath, pad, perspective, pipe, rasterize, rasterizeAuto, rasterizeWithGradient, renderMsdf, renderSdf, resize, resizeBilinear, rotate, rotateDeg, scale, shear, shift, strokeAsymmetric, strokeAsymmetricCombined, strokePath, toGray, toRGBA, toSVG, translate, } from "./pipe.ts";
+export { buildAtlas, buildAsciiAtlas, buildStringAtlas, atlasToRGBA, atlasToAlpha, getGlyphUV, };
+export { buildMsdfAtlas, buildMsdfAsciiAtlas, buildMsdfStringAtlas, msdfAtlasToRGB, msdfAtlasToRGBA, };
+export { rasterizeGlyph, rasterizeText };
+export { renderShapedText, shapedTextToSVG, renderShapedTextWithVariation, shapedTextToSVGWithVariation, };
+export type { AtlasOptions, GlyphAtlas, MsdfAtlasOptions };

package/dist/fluent/path-builder.d.ts

@@ -0,0 +1,230 @@
+/**
+ * PathBuilder: Fluent builder for vector path operations
+ *
+ * Transforms are lazy by default - accumulated as matrix until rasterization or .apply()
+ */
+import type { Font } from "../font/font.ts";
+import { type AsymmetricStrokeOptions } from "../raster/asymmetric-stroke.ts";
+import type { Gradient } from "../raster/gradient.ts";
+import { type MsdfOptions } from "../raster/msdf.ts";
+import { type SdfOptions } from "../raster/sdf.ts";
+import { type LineCap, type LineJoin, type StrokerOptions } from "../raster/stroker.ts";
+import { type Matrix2D, type Matrix3x3 } from "../render/outline-transform.ts";
+import { type GlyphPath } from "../render/path.ts";
+import type { GlyphId } from "../types.ts";
+import { BitmapBuilder } from "./bitmap-builder.ts";
+import type { AutoRasterOptions, CanvasOptions, RasterOptions, SVGElementOptions, SVGOptions } from "./types.ts";
+/**
+ * PathBuilder provides a fluent interface for path transformations and rendering
+ */
+export declare class PathBuilder {
+    private readonly _path;
+    private readonly _transform;
+    private readonly _font;
+    private constructor();
+    /**
+     * Create PathBuilder from a font glyph
+     */
+    static fromGlyph(font: Font, glyphId: GlyphId): PathBuilder | null;
+    /**
+     * Create PathBuilder from a font glyph with variable font coordinates
+     */
+    static fromGlyphWithVariation(font: Font, glyphId: GlyphId, axisCoords: number[]): PathBuilder | null;
+    /**
+     * Create PathBuilder from an existing GlyphPath
+     */
+    static fromPath(path: GlyphPath): PathBuilder;
+    /**
+     * Combine multiple PathBuilders into one
+     */
+    static combine(...builders: PathBuilder[]): PathBuilder;
+    /**
+     * Scale uniformly or non-uniformly
+     */
+    scale(sx: number, sy?: number): PathBuilder;
+    /**
+     * Translate by offset
+     */
+    translate(dx: number, dy: number): PathBuilder;
+    /**
+     * Rotate by angle in radians around origin
+     */
+    rotate(angle: number): PathBuilder;
+    /**
+     * Rotate by angle in degrees around origin
+     */
+    rotateDeg(angleDeg: number): PathBuilder;
+    /**
+     * Shear/skew transformation
+     */
+    shear(shearX: number, shearY: number): PathBuilder;
+    /**
+     * Apply italic slant (angle in degrees, typically 12-15 for italic)
+     */
+    italic(angleDeg: number): PathBuilder;
+    /**
+     * Apply custom 2D affine matrix
+     */
+    matrix(m: Matrix2D): PathBuilder;
+    /**
+     * Reset transform to identity
+     */
+    resetTransform(): PathBuilder;
+    /**
+     * Apply 3x3 perspective matrix
+     */
+    perspective(m: Matrix3x3): PathBuilder;
+    /**
+     * Create perspective with vanishing point
+     */
+    perspectiveVanish(vanishingPointX: number, vanishingPointY: number, strength: number): PathBuilder;
+    /**
+     * Force application of pending transforms
+     * Returns new PathBuilder with transforms applied and reset
+     */
+    apply(): PathBuilder;
+    /**
+     * Synthetic bold/embolden
+     */
+    embolden(strength: number): PathBuilder;
+    /**
+     * Horizontal condensing (factor < 1) or expansion (factor > 1)
+     */
+    condense(factor: number): PathBuilder;
+    /**
+     * Oblique/slant transformation
+     */
+    oblique(slant: number): PathBuilder;
+    /**
+     * Convert to stroked outline
+     */
+    stroke(options: StrokerOptions): PathBuilder;
+    stroke(width: number, cap?: LineCap, join?: LineJoin): PathBuilder;
+    /**
+     * Asymmetric stroke with independent X/Y border widths
+     * Returns outer and inner paths
+     */
+    strokeAsymmetric(options: AsymmetricStrokeOptions): {
+        outer: PathBuilder;
+        inner: PathBuilder;
+    };
+    /**
+     * Asymmetric stroke combined (both inner and outer as single fillable path)
+     */
+    strokeAsymmetricCombined(options: AsymmetricStrokeOptions): PathBuilder;
+    /**
+     * Get control box (bounding box of control points)
+     * Note: Returns bounds AFTER applying transforms
+     */
+    controlBox(): {
+        xMin: number;
+        yMin: number;
+        xMax: number;
+        yMax: number;
+    };
+    /**
+     * Get tight bounds (exact bounds considering curve extrema)
+     * Note: Returns bounds AFTER applying transforms
+     */
+    tightBounds(): {
+        xMin: number;
+        yMin: number;
+        xMax: number;
+        yMax: number;
+    };
+    /**
+     * Get the accumulated 2D transform matrix
+     */
+    getTransformMatrix(): Matrix2D;
+    /**
+     * Get the accumulated 3D transform matrix (if any)
+     */
+    getTransformMatrix3D(): Matrix3x3 | null;
+    /**
+     * Rasterize to bitmap with explicit size
+     */
+    rasterize(options: RasterOptions): BitmapBuilder;
+    /**
+     * Rasterize with auto-computed size from bounds
+     */
+    rasterizeAuto(options?: AutoRasterOptions): BitmapBuilder;
+    /**
+     * Rasterize with gradient fill
+     */
+    rasterizeWithGradient(gradient: Gradient, options: RasterOptions): BitmapBuilder;
+    /**
+     * Render as Signed Distance Field (SDF)
+     * Useful for GPU text rendering at any scale
+     */
+    toSdf(options: SdfOptions): BitmapBuilder;
+    /**
+     * Render as SDF with auto-computed size from bounds
+     */
+    toSdfAuto(options?: {
+        padding?: number;
+        scale?: number;
+        spread?: number;
+        flipY?: boolean;
+    }): BitmapBuilder;
+    /**
+     * Render as Multi-channel Signed Distance Field (MSDF)
+     * Better quality than SDF for sharp corners
+     */
+    toMsdf(options: MsdfOptions): BitmapBuilder;
+    /**
+     * Render as MSDF with auto-computed size from bounds
+     */
+    toMsdfAuto(options?: {
+        padding?: number;
+        scale?: number;
+        spread?: number;
+        flipY?: boolean;
+    }): BitmapBuilder;
+    /**
+     * Convert to SVG path data string
+     */
+    toSVG(options?: SVGOptions): string;
+    /**
+     * Convert to full SVG element string
+     */
+    toSVGElement(options?: SVGElementOptions): string;
+    /**
+     * Render to canvas context
+     */
+    toCanvas(ctx: CanvasRenderingContext2D, options?: CanvasOptions): void;
+    /**
+     * Get Path2D object for canvas
+     */
+    toPath2D(options?: {
+        flipY?: boolean;
+        scale?: number;
+    }): Path2D;
+    /**
+     * Extract the raw GlyphPath (with transforms applied)
+     */
+    toPath(): GlyphPath;
+    /**
+     * Clone this builder
+     */
+    clone(): PathBuilder;
+    /**
+     * Apply accumulated transforms to path
+     */
+    private applyTransformToPath;
+    /**
+     * Check if there's any non-identity transform
+     */
+    private hasTransform;
+    /**
+     * Check if 2D matrix is non-identity
+     */
+    private hasTransform2D;
+    /**
+     * Combine accumulated 2D transform with render options
+     */
+    private combinedMatrix2D;
+    /**
+     * Combine accumulated transforms into 3x3 matrix with render options
+     */
+    private combinedMatrix3D;
+}