three-text 0.4.11 → 0.4.12

package/dist/vector/types/slug-lib/src/types.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Pure Slug algorithm types — no dependency on three-text internals.
+ * Based on Eric Lengyel's reference implementation (MIT License, 2017).
+ */
+export interface QuadCurve {
+    p1: [number, number];
+    p2: [number, number];
+    p3: [number, number];
+}
+export interface SlugShape {
+    curves: QuadCurve[];
+    bounds: [number, number, number, number];
+}
+export interface SlugPackedTexture {
+    data: Float32Array | Uint32Array;
+    width: number;
+    height: number;
+}
+export interface SlugGPUData {
+    curveTexture: SlugPackedTexture & {
+        data: Float32Array;
+    };
+    bandTexture: SlugPackedTexture & {
+        data: Uint32Array;
+    };
+    /** 5 attribs x 4 components x 4 verts per shape, tightly packed per-shape */
+    vertices: Float32Array;
+    indices: Uint16Array;
+    shapeCount: number;
+}
+export interface SlugPackOptions {
+    bandCount?: number;
+    evenOdd?: boolean;
+}

package/dist/vector/types/src/core/types.d.ts

@@ -0,0 +1,381 @@
+import type { HyphenationTrieNode } from '../hyphenation';
+import type { CacheStats } from '../utils/Cache';
+import type { Vec2, Vec3, BoundingBox } from '../utils/vectors';
+export type { HyphenationTrieNode };
+export interface Path {
+    points: Vec2[];
+    glyphIndex: number;
+    bounds?: {
+        minX: number;
+        minY: number;
+        maxX: number;
+        maxY: number;
+    };
+}
+export interface HarfBuzzGlyph {
+    g: number;
+    cl: number;
+    ax: number;
+    ay: number;
+    dx: number;
+    dy: number;
+    x?: number;
+    y?: number;
+    lineIndex: number;
+    absoluteTextIndex: number;
+}
+export interface GlyphCluster {
+    text: string;
+    glyphs: HarfBuzzGlyph[];
+    position: Vec3;
+}
+export interface GlyphContours {
+    glyphId: number;
+    paths: Path[];
+    bounds: {
+        min: {
+            x: number;
+            y: number;
+        };
+        max: {
+            x: number;
+            y: number;
+        };
+    };
+}
+export type OutlineSegmentType = 0 | 1 | 2;
+export interface OutlineSegment {
+    type: OutlineSegmentType;
+    contourId: number;
+    p0: Vec2;
+    p1: Vec2;
+    p2?: Vec2;
+    p3?: Vec2;
+}
+export interface GlyphOutline {
+    glyphId: number;
+    textIndex: number;
+    segments: OutlineSegment[];
+    bounds: {
+        min: {
+            x: number;
+            y: number;
+        };
+        max: {
+            x: number;
+            y: number;
+        };
+    };
+}
+export type TextAlign = 'left' | 'center' | 'right' | 'justify';
+export type TextDirection = 'ltr' | 'rtl';
+export interface LineInfo {
+    text: string;
+    originalStart: number;
+    originalEnd: number;
+    xOffset: number;
+    adjustmentRatio?: number;
+    isLastLine?: boolean;
+    naturalWidth?: number;
+    endedWithHyphen?: boolean;
+}
+export interface LoadedFont {
+    hb: HarfBuzzAPI;
+    fontBlob: HarfBuzzBlob;
+    face: HarfBuzzFace;
+    font: HarfBuzzFont;
+    module: HarfBuzzModule;
+    upem: number;
+    metrics: ExtractedMetrics;
+    fontVariations?: {
+        [key: string]: number;
+    };
+    fontFeatures?: {
+        [tag: string]: boolean | number;
+    };
+    isVariable?: boolean;
+    variationAxes?: {
+        [key: string]: VariationAxis;
+    };
+    availableFeatures?: string[];
+    featureNames?: {
+        [tag: string]: string;
+    };
+    _buffer?: ArrayBuffer;
+}
+export interface HarfBuzzModule {
+    addFunction: (func: Function, signature: string) => number;
+    exports: any;
+    removeFunction: (ptr: number) => void;
+}
+export interface VariationAxis {
+    min: number;
+    default: number;
+    max: number;
+    name?: string;
+}
+export interface HarfBuzzAPI {
+    createBlob: (data: Uint8Array) => HarfBuzzBlob;
+    createFace: (blob: HarfBuzzBlob, index: number) => HarfBuzzFace;
+    createFont: (face: HarfBuzzFace) => HarfBuzzFont;
+    createBuffer: () => HarfBuzzBuffer;
+    shape: (font: HarfBuzzFont, buffer: HarfBuzzBuffer, features?: string) => void;
+}
+export interface HarfBuzzBlob {
+    destroy: () => void;
+}
+export interface HarfBuzzFace {
+    destroy: () => void;
+    getAxisInfos: () => {
+        [tag: string]: VariationAxis;
+    };
+}
+export interface HarfBuzzFont {
+    ptr: number;
+    destroy: () => void;
+    setScale: (xScale: number, yScale: number) => void;
+    setVariations: (variations: {
+        [key: string]: number;
+    }) => void;
+}
+export interface HarfBuzzBuffer {
+    addText: (text: string) => void;
+    guessSegmentProperties: () => void;
+    setDirection: (direction: string) => void;
+    json: (font: HarfBuzzFont) => any[];
+    destroy: () => void;
+}
+export interface HarfBuzzInstance {
+    hb: HarfBuzzAPI;
+    module: HarfBuzzModule;
+}
+export interface ExtractedMetrics {
+    isCFF: boolean;
+    unitsPerEm: number;
+    hheaAscender: number | null;
+    hheaDescender: number | null;
+    hheaLineGap: number | null;
+    typoAscender: number | null;
+    typoDescender: number | null;
+    typoLineGap: number | null;
+    winAscent: number | null;
+    winDescent: number | null;
+    axisNames: {
+        [tag: string]: string;
+    } | null;
+}
+export interface VerticalMetrics {
+    ascender: number;
+    descender: number;
+    lineGap: number;
+}
+export interface FontMetrics {
+    ascender: number;
+    descender: number;
+    lineGap: number;
+    unitsPerEm: number;
+    naturalLineHeight: number;
+}
+export interface ProcessedPath {
+    outer: Path;
+    holes: Path[];
+}
+export interface Triangles {
+    vertices: number[];
+    indices: number[];
+}
+export interface ProcessedGeometry {
+    triangles: Triangles;
+    contours: number[][];
+    contoursAreBoundary?: boolean;
+}
+export interface GlyphData {
+    geometry: ProcessedGeometry;
+    vertices: Float32Array;
+    normals: Float32Array;
+    indices: Uint32Array;
+    bounds: {
+        min: {
+            x: number;
+            y: number;
+            z: number;
+        };
+        max: {
+            x: number;
+            y: number;
+            z: number;
+        };
+    };
+    useCount: number;
+}
+export interface PathInfo {
+    start: number;
+    count: number;
+}
+export interface GlyphGeometryInfo {
+    textIndex: number;
+    lineIndex: number;
+    vertexStart: number;
+    vertexCount: number;
+    bounds: {
+        min: {
+            x: number;
+            y: number;
+            z: number;
+        };
+        max: {
+            x: number;
+            y: number;
+            z: number;
+        };
+    };
+    paths?: PathInfo[];
+}
+export interface TextRange {
+    start: number;
+    end: number;
+    originalText: string;
+    bounds: {
+        min: {
+            x: number;
+            y: number;
+            z: number;
+        };
+        max: {
+            x: number;
+            y: number;
+            z: number;
+        };
+    }[];
+    glyphs: GlyphGeometryInfo[];
+    lineIndices: number[];
+}
+export interface TextQueryOptions {
+    byText?: string[];
+    byCharRange?: {
+        start: number;
+        end: number;
+    }[];
+}
+export interface TextGeometryInfo {
+    vertices: Float32Array;
+    normals: Float32Array;
+    indices: Uint32Array;
+    colors?: Float32Array;
+    glyphAttributes?: {
+        glyphCenter: Float32Array;
+        glyphIndex: Float32Array;
+        glyphLineIndex: Float32Array;
+        glyphProgress: Float32Array;
+        glyphBaselineY: Float32Array;
+    };
+    glyphs: GlyphGeometryInfo[];
+    planeBounds: BoundingBox;
+    stats: {
+        trianglesGenerated: number;
+        verticesGenerated: number;
+        pointsRemovedByVisvalingam: number;
+        originalPointCount: number;
+    } & Partial<CacheStats & {
+        hitRate: number;
+        memoryUsageMB: number;
+    }>;
+    query(options: TextQueryOptions): TextRange[];
+    coloredRanges?: ColoredRange[];
+}
+export interface TextHandle extends TextGeometryInfo {
+    getLoadedFont(): LoadedFont | undefined;
+    getCacheSize(): number;
+    clearCache(): void;
+    measureTextWidth(text: string, letterSpacing?: number): number;
+    update(options: Partial<TextOptions>): Promise<TextHandle>;
+}
+export interface ColorByRange {
+    start: number;
+    end: number;
+    color: [number, number, number];
+}
+export interface ColorOptions {
+    default?: [number, number, number];
+    byText?: {
+        [text: string]: [number, number, number];
+    };
+    byCharRange?: ColorByRange[];
+}
+export interface ColoredRange {
+    start: number;
+    end: number;
+    originalText: string;
+    color: [number, number, number];
+    bounds: {
+        min: {
+            x: number;
+            y: number;
+            z: number;
+        };
+        max: {
+            x: number;
+            y: number;
+            z: number;
+        };
+    }[];
+    glyphs: GlyphGeometryInfo[];
+    lineIndices: number[];
+}
+export interface TextOptions {
+    text: string;
+    font: string | ArrayBuffer;
+    size?: number;
+    depth?: number;
+    lineHeight?: number;
+    letterSpacing?: number;
+    perGlyphAttributes?: boolean;
+    fontVariations?: {
+        [key: string]: number;
+    };
+    fontFeatures?: {
+        [tag: string]: boolean | number;
+    };
+    maxTextLength?: number;
+    removeOverlaps?: boolean;
+    curveSteps?: number;
+    curveFidelity?: CurveFidelityConfig;
+    geometryOptimization?: GeometryOptimizationOptions;
+    layout?: LayoutOptions;
+    color?: [number, number, number] | ColorOptions;
+}
+export interface HyphenationPatternsMap {
+    [language: string]: HyphenationTrieNode;
+}
+export interface CurveFidelityConfig {
+    distanceTolerance?: number;
+    angleTolerance?: number;
+    cuspLimit?: number;
+    collinearityEpsilon?: number;
+    recursionLimit?: number;
+}
+export interface GeometryOptimizationOptions {
+    enabled?: boolean;
+    areaThreshold?: number;
+}
+export interface LayoutOptions {
+    width?: number;
+    align?: TextAlign;
+    direction?: TextDirection;
+    respectExistingBreaks?: boolean;
+    hyphenate?: boolean;
+    language?: string;
+    patternsPath?: string;
+    tolerance?: number;
+    pretolerance?: number;
+    emergencyStretch?: number;
+    autoEmergencyStretch?: number;
+    hyphenationPatterns?: HyphenationPatternsMap;
+    lefthyphenmin?: number;
+    righthyphenmin?: number;
+    linepenalty?: number;
+    adjdemerits?: number;
+    hyphenpenalty?: number;
+    exhyphenpenalty?: number;
+    doublehyphendemerits?: number;
+}

package/dist/vector/types/src/hyphenation/HyphenationPatternLoader.d.ts

@@ -0,0 +1,2 @@
+import { HyphenationTrieNode } from './types';
+export declare function loadPattern(language: string, patternsPath?: string): Promise<HyphenationTrieNode>;

package/dist/vector/types/src/hyphenation/index.d.ts

@@ -0,0 +1,7 @@
+export interface HyphenationTrieNode {
+    patterns: number[] | null;
+    children: {
+        [char: string]: HyphenationTrieNode;
+    };
+}
+export { loadPattern } from './HyphenationPatternLoader';

package/dist/vector/types/src/hyphenation/types.d.ts

@@ -0,0 +1,6 @@
+export interface HyphenationTrieNode {
+    patterns: number[] | null;
+    children: {
+        [key: string]: HyphenationTrieNode;
+    };
+}

package/dist/vector/types/src/utils/Cache.d.ts

@@ -0,0 +1,14 @@
+export interface CacheStats {
+    size: number;
+}
+export declare class Cache<K, V> {
+    private cache;
+    get(key: K): V | undefined;
+    has(key: K): boolean;
+    set(key: K, value: V): void;
+    delete(key: K): boolean;
+    clear(): void;
+    get size(): number;
+    keys(): K[];
+    getStats(): CacheStats;
+}

package/dist/vector/types/src/utils/vectors.d.ts

@@ -0,0 +1,75 @@
+export declare class Vec2 {
+    x: number;
+    y: number;
+    constructor(x?: number, y?: number);
+    set(x: number, y: number): Vec2;
+    clone(): Vec2;
+    copy(v: Vec2): Vec2;
+    add(v: Vec2): Vec2;
+    sub(v: Vec2): Vec2;
+    multiply(scalar: number): Vec2;
+    divide(scalar: number): Vec2;
+    length(): number;
+    lengthSq(): number;
+    normalize(): Vec2;
+    dot(v: Vec2): number;
+    distanceTo(v: Vec2): number;
+    distanceToSquared(v: Vec2): number;
+    equals(v: Vec2): boolean;
+    angle(): number;
+}
+export declare class Vec3 {
+    x: number;
+    y: number;
+    z: number;
+    constructor(x?: number, y?: number, z?: number);
+    set(x: number, y: number, z: number): Vec3;
+    clone(): Vec3;
+    copy(v: Vec3): Vec3;
+    add(v: Vec3): Vec3;
+    sub(v: Vec3): Vec3;
+    multiply(scalar: number): Vec3;
+    divide(scalar: number): Vec3;
+    length(): number;
+    lengthSq(): number;
+    normalize(): Vec3;
+    dot(v: Vec3): number;
+    cross(v: Vec3): Vec3;
+    distanceTo(v: Vec3): number;
+    distanceToSquared(v: Vec3): number;
+    equals(v: Vec3): boolean;
+}
+export declare class Box3 {
+    min: Vec3;
+    max: Vec3;
+    constructor(min?: Vec3, max?: Vec3);
+    set(min: Vec3, max: Vec3): Box3;
+    setFromPoints(points: Vec3[]): Box3;
+    makeEmpty(): Box3;
+    isEmpty(): boolean;
+    expandByPoint(point: Vec3): Box3;
+    expandByScalar(scalar: number): Box3;
+    containsPoint(point: Vec3): boolean;
+    containsBox(box: Box3): boolean;
+    intersectsBox(box: Box3): boolean;
+    getCenter(target?: Vec3): Vec3;
+    getSize(target?: Vec3): Vec3;
+    clone(): Box3;
+    copy(box: Box3): Box3;
+    union(box: Box3): Box3;
+    equals(box: Box3): boolean;
+}
+export interface BoundingBox {
+    min: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    max: {
+        x: number;
+        y: number;
+        z: number;
+    };
+}
+export declare function box3ToBoundingBox(box: Box3): BoundingBox;
+export declare function boundingBoxToBox3(bounds: BoundingBox): Box3;

package/dist/vector/types/src/vector/VectorDataBuilder.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Bridges three-text's glyph outline pipeline to the Slug packer.
+ *
+ * Takes GlyphOutline[] (raw bezier segments from HarfBuzz) and produces
+ * SlugGPUData ready for WebGL2/WebGPU upload.
+ */
+import type { GlyphOutline } from '../core/types';
+import type { SlugGPUData, SlugPackOptions } from '../../slug-lib/src/types';
+export interface VectorBuildResult {
+    gpuData: SlugGPUData;
+    /** Per-glyph metadata for query/selection */
+    glyphMeta: {
+        glyphId: number;
+        textIndex: number;
+        shapeIndex: number;
+        bounds: [number, number, number, number];
+    }[];
+}
+/**
+ * Convert glyph outlines to Slug GPU data.
+ *
+ * @param outlines - Raw glyph outlines from GlyphOutlineCollector
+ * @param positions - World-space positions per glyph (x, y for each outline)
+ * @param scale - Scale factor (fontSize / unitsPerEm)
+ * @param options - Slug packing options
+ */
+export declare function buildVectorData(outlines: GlyphOutline[], positions: {
+    x: number;
+    y: number;
+}[], scale: number, options?: SlugPackOptions): VectorBuildResult;

package/dist/vector/types/src/vector/VectorThreeAdapter.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Three.js integration for Slug-based vector text rendering.
+ *
+ * Provides helpers to create RawShaderMaterial and BufferGeometry
+ * from SlugGPUData, compatible with Three.js scenes.
+ */
+import type { SlugGPUData } from '../../slug-lib/src/types';
+type THREE = typeof import('three');
+export interface VectorThreeResources {
+    geometry: InstanceType<THREE['BufferGeometry']>;
+    material: InstanceType<THREE['RawShaderMaterial']>;
+    mesh: InstanceType<THREE['Mesh']>;
+    dispose(): void;
+}
+/**
+ * Create a complete Three.js mesh for vector text rendering.
+ *
+ * @param THREE - The three.js module (pass `import * as THREE from 'three'`)
+ * @param gpuData - Output from packSlugData or buildVectorData
+ */
+export declare function createVectorThreeMesh(THREE: THREE, gpuData: SlugGPUData): VectorThreeResources;
+/**
+ * Update the slug_matrix and slug_viewport uniforms before rendering.
+ * Call this in your render loop or when the camera/viewport changes.
+ */
+export declare function updateVectorUniforms(material: InstanceType<THREE['RawShaderMaterial']>, mvpMatrix: InstanceType<THREE['Matrix4']>, viewportWidth: number, viewportHeight: number): void;
+export {};

package/dist/vector/types/src/vector/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * three-text/vector — Text-specific vector rendering via Slug algorithm.
+ *
+ * Bridges HarfBuzz glyph outlines to slug-lib,
+ * with Three.js integration.
+ */
+export { buildVectorData } from './VectorDataBuilder';
+export type { VectorBuildResult } from './VectorDataBuilder';
+export { createVectorThreeMesh, updateVectorUniforms } from './VectorThreeAdapter';
+export type { VectorThreeResources } from './VectorThreeAdapter';
+export { createWebGL2Resources, drawWebGL2 } from '../../slug-lib/src/WebGL2Renderer';
+export type { SlugWebGL2Resources } from '../../slug-lib/src/WebGL2Renderer';
+export { createWebGPUResources, drawWebGPU } from '../../slug-lib/src/WebGPURenderer';
+export type { SlugWebGPUResources } from '../../slug-lib/src/WebGPURenderer';
+export type { SlugGPUData, SlugPackOptions } from '../../slug-lib/src/types';