@vectojs/core 0.1.0 → 0.2.0

package/dist/layout.d.ts

@@ -1,319 +0,0 @@
-/**
- * Map from a single grapheme character to its pre-measured glyph metrics.
- *
- * Each entry provides the glyph's pixel `width` at `baseSize`, and an `ast`
- * property holding the raw vector path data used by the renderer.
- */
-interface GlyphAtlas {
-    [char: string]: {
-        width: number;
-        baseSize: number;
-        ast: any;
-    };
-}
-/**
- * Resolves the pixel advance width of a single grapheme at a given font size,
- * for glyphs not present in a pre-baked {@link GlyphAtlas}.
- *
- * Implemented by {@link createCanvasMeasurer} (canvas `measureText`), but kept
- * abstract so callers can supply their own metrics source.
- */
-interface GlyphMeasurer {
-    measure(char: string, fontSize: number): number;
-}
-/**
- * Per-run inline style for rich text ({@link LayoutEngine.prepareRich}). All
- * fields are optional and inherited from the call's base style when omitted.
- */
-interface TextStyle {
-    /** Font size in px for this run; overrides the base size (affects width + line height). */
-    fontSize?: number;
-    /** Fill color, e.g. `'#38bdf8'`. */
-    color?: string;
-    /** Bold weight (rendering only; width still measured at base metrics). */
-    bold?: boolean;
-    /** Italic slant (rendering only). */
-    italic?: boolean;
-    /** Hyperlink destination; carried through to the positioned nodes for hit-testing / a11y. */
-    href?: string;
-}
-/** A run of text sharing one {@link TextStyle}, the input unit of {@link LayoutEngine.prepareRich}. */
-interface StyledSpan {
-    text: string;
-    style?: TextStyle;
-}
-/**
- * A single positioned glyph produced by {@link LayoutEngine.layoutText}.
- */
-interface LayoutNode {
-    char: string;
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-    /** Inline style carried from rich text; `undefined` for plain (single-style) layout. */
-    style?: TextStyle;
-    sourceIndex?: number;
-    sourceLength?: number;
-    isRTL?: boolean;
-    combining?: string[];
-}
-/**
- * The complete output of a text layout pass — an ordered list of positioned
- * glyphs and the total bounding-box dimensions.
- */
-interface LayoutResult {
-    nodes: LayoutNode[];
-    totalWidth: number;
-    totalHeight: number;
-    fallbackToCanvas?: boolean;
-}
-/** A single measured grapheme (the "cold" half of the cold/hot split). */
-interface PreparedGlyph {
-    char: string;
-    /** Advance width at the prepared `fontSize`. */
-    width: number;
-    /** Inline style (rich text only); drives per-glyph size, color and baseline. */
-    style?: TextStyle;
-    level: number;
-    sourceIndex: number;
-    sourceLength: number;
-    combining?: string[];
-}
-/** A measured word/segment, ready to be placed without re-measuring. */
-interface PreparedWord {
-    glyphs: PreparedGlyph[];
-    /** Sum of glyph advances — used for word-level wrap decisions. */
-    width: number;
-    isWordLike: boolean | undefined;
-    /** Pre-computed `word.trim().length === 0`. */
-    isWhitespace: boolean;
-}
-/** A measured paragraph; `isEmpty` marks a blank line (forced newline). */
-interface PreparedParagraph {
-    words: PreparedWord[];
-    isEmpty: boolean;
-    fallbackToCanvas?: boolean;
-    baseLevel?: number;
-}
-/**
- * The result of the **cold** measurement pass ({@link LayoutEngine.prepare}):
- * segmented + measured text that is independent of layout constraints
- * (`maxWidth`/`maxHeight`/exclusion masks). Reuse it across cheap **hot**
- * re-layouts ({@link LayoutEngine.layoutPrepared}) on resize / reposition,
- * avoiding the per-frame `Intl.Segmenter` + measurement cost.
- */
-interface PreparedText {
-    paragraphs: PreparedParagraph[];
-    fontSize: number;
-    fallbackToCanvas?: boolean;
-}
-/**
- * A rectangular region (in the text's local coordinate space) that text must
- * flow around — the v1 of text flow exclusion shapes. A left/right rect acts
- * like a CSS float; a centered rect splits the affected lines in two.
- */
-interface ExclusionRect {
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-}
-/** A free horizontal interval `[x0, x1)` available for text on one line. */
-interface LineSegment {
-    x0: number;
-    x1: number;
-}
-/**
- * The free horizontal segments left in `[0, maxWidth]` for a line whose box
- * spans the vertical band `[top, bottom)`, after subtracting every
- * {@link ExclusionRect} that overlaps that band. Returns the full width when
- * nothing overlaps, and `[]` when an exclusion (or union of them) spans the
- * whole width. Pure — the testable core of exclusion flow.
- *
- * Time O(n log n) in the number of overlapping exclusions; space O(n).
- */
-declare function computeLineSegments(top: number, bottom: number, maxWidth: number, exclusions: ExclusionRect[]): LineSegment[];
-/**
- * VectoJS Global Layout Engine (Intl.Segmenter)
- * Advanced Typography Engine supporting CJK, Emoji, and Western Graphemes
- */
-declare class LayoutEngine {
-    maxWidth: number;
-    maxHeight: number;
-    preserveLeadingSpaces: boolean;
-    private wordSegmenter;
-    private charSegmenter;
-    private wordCache;
-    private graphemeCache;
-    private paragraphCache;
-    private richParagraphCache;
-    private lastAtlas;
-    private measurer;
-    constructor(maxWidth: number, maxHeight: number, measurer?: GlyphMeasurer | null);
-    private getWordSegments;
-    /**
-     * Resolve a grapheme's advance width at `fontSize`, in priority order:
-     * pre-baked atlas entry → injected {@link GlyphMeasurer} → `0.5em` fallback.
-     */
-    private glyphWidth;
-    private getGraphemes;
-    /**
-     * Lay out a Unicode string into a list of positioned {@link LayoutNode} glyphs.
-     *
-     * Uses `Intl.Segmenter` to correctly handle CJK, emoji, and Western word
-     * boundaries.  An optional `exclusionMask` callback allows glyphs to flow
-     * around arbitrary shapes (e.g. physics bodies or video regions).
-     *
-     * @param text - The raw text string to lay out (newlines force paragraph breaks).
-     * @param fontAtlas - Pre-measured glyph metrics keyed by grapheme character.
-     * @param fontSize - Target font size in pixels (default: `32`).
-     * @param exclusionMask - Optional callback returning `true` when a candidate
-     *   glyph bounding box overlaps a forbidden region; the engine skips that
-     *   position and advances horizontally.
-     * @returns A {@link LayoutResult} with all positioned glyph nodes and total dimensions.
-     * @example
-     * const result = engine.layoutText('Hello 世界', atlas, 24);
-     * result.nodes.forEach(n => console.log(n.char, n.x, n.y));
-     */
-    layoutText(text: string, fontAtlas: GlyphAtlas, fontSize?: number, exclusionMask?: (x: number, y: number, w: number, h: number) => boolean): LayoutResult;
-    /**
-     * **Cold pass.** Segment and measure `text` once into a reusable
-     * {@link PreparedText}. Runs `Intl.Segmenter` (word + grapheme) and resolves
-     * each grapheme's advance width — the expensive work. The result is
-     * independent of `maxWidth`/`maxHeight`/exclusion masks, so it can be re-laid
-     * out cheaply by {@link layoutPrepared} on resize / reposition / animation.
-     *
-     * @param text - The raw text string (newlines force paragraph breaks).
-     * @param fontAtlas - Pre-measured glyph metrics keyed by grapheme character.
-     * @param fontSize - Target font size in pixels (default: `32`).
-     */
-    prepare(text: string, fontAtlas: GlyphAtlas, fontSize?: number): PreparedText;
-    /**
-     * **Cold pass for rich text.** Like {@link prepare}, but takes an array of
-     * {@link StyledSpan}s so different inline runs (bold / italic / color / size /
-     * links) compose on the same wrapped lines. Each grapheme carries the
-     * (base-merged) style of the span it came from — so a style change *mid-word*
-     * (e.g. `He` + **`llo`**) is honored. Run `fontSize` affects measured width and
-     * line height; the rest is rendering metadata carried through to the nodes.
-     *
-     * The result feeds the same {@link layoutPrepared} as plain text.
-     *
-     * @param spans - The styled runs, in document order.
-     * @param fontAtlas - Pre-measured glyph metrics keyed by grapheme character.
-     * @param baseFontSize - Size for runs without an explicit `fontSize` (default 32).
-     * @param baseStyle - Style inherited by every run (each run's own style wins).
-     */
-    prepareRich(spans: StyledSpan[], fontAtlas: GlyphAtlas, baseFontSize?: number, baseStyle?: TextStyle): PreparedText;
-    /**
-     * **Hot pass.** Place an already-measured {@link PreparedText} into positioned
-     * glyphs. Does only wrap/positioning arithmetic — no `Intl.Segmenter`, no
-     * re-measurement — so it is cheap enough to call every frame or on every
-     * resize. Reads the engine's current `maxWidth`/`maxHeight`, so changing those
-     * and re-calling reflows the same prepared text.
-     *
-     * @param prepared - Output of {@link prepare}.
-     * @param exclusionMask - Optional per-glyph collision callback (see {@link layoutText}).
-     * @param exclusions - Optional rect regions text flows around (exclusion shapes); each
-     *   line is split into the free x-segments left after subtracting them. Omitting
-     *   it (or passing `[]`) leaves the single-column path byte-for-byte unchanged.
-     */
-    layoutPrepared(prepared: PreparedText, exclusionMask?: (x: number, y: number, w: number, h: number) => boolean, exclusions?: ExclusionRect[]): LayoutResult;
-    /**
-     * Lay out a Unicode string directly into a pre-allocated {@link LayoutResultBuffer}.
-     *
-     * Avoids GC allocations by writing results directly to flat typed arrays in the buffer.
-     *
-     * @param text - The raw text string to lay out.
-     * @param fontAtlas - Pre-measured glyph metrics keyed by grapheme character.
-     * @param fontSize - Target font size in pixels.
-     * @param buffer - The pre-allocated buffer to write layout results into.
-     * @param exclusionMask - Optional collision-detection callback.
-     */
-    layoutTextIntoBuffer(text: string, fontAtlas: GlyphAtlas, fontSize: number, buffer: LayoutResultBuffer, exclusionMask?: (x: number, y: number, w: number, h: number) => boolean): void;
-    /**
-     * **Hot pass, zero-GC variant.** Place an already-measured {@link PreparedText}
-     * directly into a pre-allocated {@link LayoutResultBuffer}. Like
-     * {@link layoutPrepared} but writes flat typed arrays instead of allocating
-     * {@link LayoutNode} objects — the per-frame path for large dynamic scenes.
-     */
-    layoutPreparedIntoBuffer(prepared: PreparedText, buffer: LayoutResultBuffer, exclusionMask?: (x: number, y: number, w: number, h: number) => boolean): void;
-}
-/**
- * Pre-allocated buffer for zero-GC layout results.
- * Reuse a single instance across frames by calling reset() before each layout pass.
- */
-declare class LayoutResultBuffer {
-    static readonly CAPACITY = 16384;
-    /** X positions of each glyph. */
-    xs: Float32Array;
-    /** Y positions of each glyph. */
-    ys: Float32Array;
-    /** Widths of each glyph. */
-    ws: Float32Array;
-    /** Heights of each glyph. */
-    hs: Float32Array;
-    /** Character for each glyph slot. */
-    chars: string[];
-    /** Number of valid glyphs written in this buffer. */
-    count: number;
-    /** Reset the buffer for reuse. Does NOT free memory. */
-    reset(): void;
-    /** Convert to the standard LayoutResult format (allocates — use sparingly). */
-    toLayoutResult(): LayoutResult;
-}
-
-/**
- * Create a {@link GlyphMeasurer} backed by a single lazily-created offscreen
- * Canvas 2D context.
- *
- * Each grapheme is measured once at `baseSize` and cached; because canvas
- * `measureText` advance width is linear in font size, later queries at any
- * `fontSize` are derived by pure arithmetic (no re-measure). This gives the
- * {@link LayoutEngine} real per-glyph metrics for text that has no pre-baked
- * vector atlas, fixing the coarse `0.5em` line-breaking fallback.
- *
- * Returns `null` in DOM-free environments (SSR, workers without a canvas) so
- * callers stay portable and the engine keeps its `0.5em` fallback.
- *
- * @param fontFamily - CSS font family used for measurement; should match what
- *   the renderer actually draws (e.g. `TextEntity` falls back to `sans-serif`).
- * @param baseSize - Pixel size at which each glyph is measured and cached.
- * @returns A measurer, or `null` when no Canvas 2D context is available.
- */
-declare function createCanvasMeasurer(fontFamily?: string, baseSize?: number): GlyphMeasurer | null;
-
-interface LayoutWorkerResponse {
-    id: string;
-    seqId: number;
-    width: number;
-    height: number;
-    codePoints: Uint32Array;
-    xCoords: Float32Array;
-    yCoords: Float32Array;
-    packedStyles: Uint32Array;
-}
-
-declare class LayoutWorkerManager {
-    private static instance;
-    private worker;
-    private registeredFonts;
-    private pendingCallbacks;
-    private seqIdCounter;
-    private debounceTimers;
-    private constructor();
-    static getInstance(): LayoutWorkerManager;
-    queueLayout(entityId: string, text: string, options: {
-        fontId: string;
-        fontSize: number;
-        maxWidth: number;
-        maxHeight: number;
-        fontData?: any;
-        lineHeight?: number;
-        letterSpacing?: number;
-        callback: (res: LayoutWorkerResponse) => void;
-    }): void;
-    cancelLayout(entityId: string): void;
-}
-
-export { type ExclusionRect, type GlyphAtlas, type GlyphMeasurer, LayoutEngine, type LayoutNode, type LayoutResult, LayoutResultBuffer, LayoutWorkerManager, type LineSegment, type PreparedGlyph, type PreparedParagraph, type PreparedText, type PreparedWord, type StyledSpan, type TextStyle, computeLineSegments, createCanvasMeasurer };

package/dist/renderer.d.mts

@@ -1,2 +0,0 @@
-export { C as CanvasRenderer, k as PointRenderer, R as RGBA, S as SVGLinearGradient, l as SVGRenderer, W as WebGPUParticleSystemManager, m as createWebGLPointRenderer, p as parseColorToRGBA } from './index-ByBDSmMK.mjs';
-export { I as IRenderer } from './Entity-D-rfAFCf.mjs';

package/dist/renderer.d.ts

@@ -1,2 +0,0 @@
-export { C as CanvasRenderer, k as PointRenderer, R as RGBA, S as SVGLinearGradient, l as SVGRenderer, W as WebGPUParticleSystemManager, m as createWebGLPointRenderer, p as parseColorToRGBA } from './index-C3Fd_XmG.js';
-export { I as IRenderer } from './Entity-D-rfAFCf.js';

package/dist/text.d.mts

@@ -1,201 +0,0 @@
-import { E as Entity, I as IRenderer } from './Entity-D-rfAFCf.mjs';
-
-/**
- * MSDF (Multi-channel Signed Distance Field) font support.
- *
- * Parses the `msdf-atlas-gen` JSON layout — the de-facto MSDF format produced by
- * Chlumsky's `msdf-atlas-gen` / `msdfgen` — and lays a string out into textured
- * quads positioned in CSS pixels with atlas UVs. Pair {@link MSDFFont.layout}
- * with the WebGL backend's `setMSDFTexture` + `addGlyph` to render GPU text that
- * stays crisp at any scale (and supports outline/glow in the shader).
- *
- * Geometry conventions match the renderer: local space is y-down, top-left
- * origin; UVs use v=0 at the top of the atlas image (atlas uploaded without a
- * Y-flip, the same as `setTexture`/`addSprite`).
- */
-/** Atlas section of an `msdf-atlas-gen` JSON file. */
-interface MSDFAtlasInfo {
-    /** Field type, e.g. `'msdf'` | `'mtsdf'` | `'sdf'`. */
-    type: string;
-    /** Distance field range in atlas pixels — drives the shader's edge sharpness. */
-    distanceRange: number;
-    /** Glyph size the atlas was rasterized at (em → px), informational. */
-    size: number;
-    /** Atlas image width in pixels. */
-    width: number;
-    /** Atlas image height in pixels. */
-    height: number;
-    /** Whether `atlasBounds` are measured from the image bottom or top. */
-    yOrigin: 'bottom' | 'top';
-}
-/** Font-wide metrics in em units. */
-interface MSDFMetrics {
-    emSize: number;
-    /** Line advance in em (multiply by font size for px). */
-    lineHeight: number;
-    /** Distance from baseline to the top of the line in em (positive, up). */
-    ascender: number;
-    /** Distance from baseline to the bottom in em (negative, down). */
-    descender: number;
-    underlineY?: number;
-    underlineThickness?: number;
-}
-/** Em-unit / atlas-pixel rectangle as emitted by `msdf-atlas-gen`. */
-interface MSDFBounds {
-    left: number;
-    bottom: number;
-    right: number;
-    top: number;
-}
-/** One glyph's metrics. Whitespace has `advance` but no plane/atlas bounds. */
-interface MSDFGlyphDef {
-    unicode: number;
-    /** Horizontal advance in em units. */
-    advance: number;
-    /** Quad position relative to the baseline, em units, y-up. */
-    planeBounds?: MSDFBounds;
-    /** Source rectangle in the atlas, pixels. */
-    atlasBounds?: MSDFBounds;
-}
-/** Kerning pair adjustment in em units. */
-interface MSDFKerning {
-    unicode1: number;
-    unicode2: number;
-    advance: number;
-}
-/** A parsed `msdf-atlas-gen` JSON document. */
-interface MSDFFontData {
-    atlas: MSDFAtlasInfo;
-    metrics: MSDFMetrics;
-    glyphs: MSDFGlyphDef[];
-    kerning?: MSDFKerning[];
-}
-/** A glyph positioned for rendering: a CSS-pixel quad + atlas UVs (0..1). */
-interface PositionedGlyph {
-    /** Source character (may be a surrogate-pair astral codepoint). */
-    char: string;
-    /** Quad top-left in local CSS pixels (y-down). */
-    x: number;
-    y: number;
-    /** Quad size in CSS pixels. */
-    w: number;
-    h: number;
-    /** Atlas UVs: `(u0,v0)` top-left, `(u1,v1)` bottom-right; v=0 is the atlas top. */
-    u0: number;
-    v0: number;
-    u1: number;
-    v1: number;
-}
-/** Result of {@link MSDFFont.layout}. */
-interface MSDFLayoutResult {
-    glyphs: PositionedGlyph[];
-    /** Total pen advance of the widest line in CSS pixels. */
-    width: number;
-    /** `lineCount × lineHeight × fontSize` in CSS pixels. */
-    height: number;
-}
-/** Options for {@link MSDFFont.layout}. */
-interface MSDFLayoutOptions {
-    /** Pen origin x (left of the first glyph), CSS pixels. Default 0. */
-    x?: number;
-    /** Text-block top y (baseline of line 0 = `y + ascender×size`). Default 0. */
-    y?: number;
-    /** Extra advance added after every glyph, CSS pixels. Default 0. */
-    letterSpacing?: number;
-}
-/**
- * A loaded MSDF font. Construct from parsed {@link MSDFFontData}, or use
- * {@link MSDFFont.parse} to read the JSON string straight from `msdf-atlas-gen`.
- */
-declare class MSDFFont {
-    private static idCounter;
-    readonly id: string;
-    readonly data: MSDFFontData;
-    private readonly byCode;
-    private readonly kern;
-    constructor(data: MSDFFontData);
-    /** Parse the `msdf-atlas-gen` JSON (string or already-parsed object). */
-    static parse(json: string | MSDFFontData): MSDFFont;
-    /** Get a glyph's definition by its unicode value in O(1) time. */
-    getGlyph(unicode: number): MSDFGlyphDef | undefined;
-    /** Distance field range in atlas pixels (for the shader's `u_distanceRange`). */
-    get distanceRange(): number;
-    get atlasWidth(): number;
-    get atlasHeight(): number;
-    /**
-     * Lay `text` out at `fontSizePx`. Returns positioned quads (skipping glyphs the
-     * font doesn't contain), the widest line's advance, and the total block height.
-     * Honors `\n`, kerning pairs, and `letterSpacing`.
-     */
-    layout(text: string, fontSizePx: number, opts?: MSDFLayoutOptions): MSDFLayoutResult;
-}
-
-interface MSDFTextEntityOptions {
-    font: MSDFFont;
-    texture: TexImageSource;
-    fallbackFont?: string;
-    fontSize?: number;
-    color?: string;
-    lineHeight?: number;
-    letterSpacing?: number;
-}
-declare class MSDFTextEntity extends Entity {
-    private font;
-    private texture;
-    private fallbackFont;
-    private fontSize;
-    color: string;
-    private letterSpacing;
-    private lineHeight?;
-    private text;
-    private lastRenderedSeqId;
-    private rgbColorCache;
-    private fontStringCache;
-    private layoutResult;
-    constructor(text: string, options: MSDFTextEntityOptions);
-    setText(text: string): void;
-    isPointInside(globalX: number, globalY: number): boolean;
-    render(renderer: any): void;
-    destroy(): void;
-}
-
-declare class SVGEntity extends Entity {
-    private svgSource;
-    private imageBitmap;
-    private imageElement;
-    private blobURL;
-    private currentImg;
-    private lodTimeout;
-    private cachedDoc;
-    private baseWidth;
-    private baseHeight;
-    private lastRasterizedScale;
-    private targetScale;
-    constructor(svgSource: string, id?: string);
-    setSVGSource(svgSource: string): void;
-    private parseSVGDimensions;
-    private triggerRasterization;
-    isPointInside(globalX: number, globalY: number): boolean;
-    render(r: IRenderer): void;
-    destroy(): void;
-}
-
-interface ShapedResult {
-    shapedText: string;
-    indexMap: Int32Array;
-}
-declare class ArabicShaper {
-    private static MAPPINGS;
-    private static isHarakat;
-    private static getJoiningType;
-    static shapeArabic(text: string): ShapedResult;
-}
-
-declare class BidiResolver {
-    private static getDirectionClass;
-    static getBaseLevel(text: string): number;
-    static resolveLevels(text: string): Uint8Array;
-    static reorderVisual(nodes: any[], baseLevel: number): void;
-}
-
-export { ArabicShaper, BidiResolver, type MSDFAtlasInfo, type MSDFBounds, MSDFFont, type MSDFFontData, type MSDFGlyphDef, type MSDFKerning, type MSDFLayoutOptions, type MSDFLayoutResult, type MSDFMetrics, MSDFTextEntity, type MSDFTextEntityOptions, type PositionedGlyph, SVGEntity, type ShapedResult };