@codexo/exojs 0.8.4 → 0.9.0

package/dist/esm/rendering/text/TextLayout.js

@@ -1,41 +1,95 @@
 /**
- * Computes per-glyph quad placements for the given text and style.
+ * Compute the bounding pixel dimensions of `text` without allocating quad
+ * placements. Returns `{ width: 0, height: 0 }` for empty text.
+ */
+function measureText(text, style, provider) {
+    if (text.length === 0)
+        return { width: 0, height: 0 };
+    const { fontSize, lineHeight, leading } = style;
+    const computedLineHeight = fontSize * lineHeight + leading;
+    const lines = text.split('\n');
+    let maxLineWidth = 0;
+    for (const line of lines) {
+        let lineWidth = 0;
+        for (const char of line) {
+            lineWidth += provider.getGlyph(char, fontSize).advance;
+        }
+        if (lineWidth > maxLineWidth)
+            maxLineWidth = lineWidth;
+    }
+    return { width: maxLineWidth, height: lines.length * computedLineHeight };
+}
+/**
+ * Computes per-glyph quad placements for the given text, style, and layout
+ * options.
  *
- * Handles `\n` line breaks and left/center/right alignment. No word-wrap,
- * no RTL, no ligature shaping — Unicode/diacritics are delegated to the
- * browser's font engine via canvas `fillText`.
+ * Handles `\n` line breaks, left/center/right/justify alignment, `letterSpacing`,
+ * `leading`, `breakWords`, `whiteSpace` preprocessing, and optional kerning
+ * (if the provider implements `getKerning`). RTL and ligature shaping are out
+ * of scope; Unicode/diacritics are delegated to the browser's canvas engine.
  *
  * Returns an empty array for empty text.
  */
-function layoutText(text, style, atlas) {
-    if (text.length === 0) {
+function layoutText(text, style, layout, provider) {
+    if (text.length === 0)
         return [];
+    const { fontSize, lineHeight, leading, align } = style;
+    const computedLineHeight = fontSize * lineHeight + leading;
+    const letterSpacing = layout.letterSpacing ?? 0;
+    const maxWidth = layout.maxWidth;
+    const breakWords = layout.breakWords ?? false;
+    const whiteSpace = layout.whiteSpace ?? 'pre-line';
+    // ── Whitespace preprocessing ──────────────────────────────────────────────
+    const preprocessed = _applyWhiteSpace(text, whiteSpace);
+    // Split into hard lines then optionally word-wrap each.
+    const hardLines = preprocessed.split('\n');
+    const allLines = [];
+    for (const hard of hardLines) {
+        if (maxWidth === undefined) {
+            allLines.push(hard);
+        }
+        else {
+            allLines.push(..._wrapLine(hard, fontSize, provider, maxWidth, letterSpacing, breakWords));
+        }
     }
-    const { fontSize, fontFamily, fontWeight, fontStyle, lineHeight, align } = style;
-    const computedLineHeight = fontSize * lineHeight;
-    const lines = text.split('\n');
-    // Pass 1: gather glyph info per line, track line widths
+    // Pass 1: gather glyph info per line, track widths and word counts.
     const linePlacements = [];
     let maxLineWidth = 0;
-    for (let lineIndex = 0; lineIndex < lines.length; lineIndex++) {
-        const line = lines[lineIndex];
-        const y = lineIndex * computedLineHeight;
+    for (let lineIndex = 0; lineIndex < allLines.length; lineIndex++) {
+        const line = allLines[lineIndex];
+        const lineY = lineIndex * computedLineHeight;
         let cursorX = 0;
+        let wordCount = 0;
+        let inWord = false;
         const placements = [];
+        let prevChar = null;
         for (const char of line) {
-            const info = atlas.getGlyph(char, fontFamily, fontSize, fontWeight, fontStyle);
-            placements.push({ info, x: cursorX, y });
-            cursorX += info.advance;
+            // Kerning adjustment before placing this character.
+            if (prevChar !== null && provider.getKerning !== undefined) {
+                cursorX += provider.getKerning(prevChar, char, fontSize);
+            }
+            const info = provider.getGlyph(char, fontSize);
+            placements.push({ info, x: cursorX, y: lineY, char });
+            cursorX += info.advance + letterSpacing;
+            if (char === ' ') {
+                inWord = false;
+            }
+            else if (!inWord) {
+                inWord = true;
+                wordCount++;
+            }
+            prevChar = char;
         }
-        const lineWidth = cursorX;
-        if (lineWidth > maxLineWidth) {
+        const lineWidth = cursorX - (placements.length > 0 ? letterSpacing : 0);
+        if (lineWidth > maxLineWidth)
             maxLineWidth = lineWidth;
-        }
-        linePlacements.push({ placements, width: lineWidth });
+        linePlacements.push({ placements, width: lineWidth, wordCount });
     }
-    // Pass 2: apply alignment and build final GlyphPlacement array
+    // Pass 2: apply alignment offset and build final GlyphPlacement array.
     const result = [];
-    for (const line of linePlacements) {
+    const lastLineIndex = linePlacements.length - 1;
+    for (let li = 0; li < linePlacements.length; li++) {
+        const line = linePlacements[li];
         let offsetX = 0;
         if (align === 'right') {
             offsetX = maxLineWidth - line.width;
@@ -43,12 +97,42 @@ function layoutText(text, style, atlas) {
         else if (align === 'center') {
             offsetX = (maxLineWidth - line.width) / 2;
         }
+        else if (align === 'justify' && li !== lastLineIndex && line.wordCount > 1) {
+            // Justify: distribute extra space evenly among inter-word gaps.
+            const gaps = line.wordCount - 1;
+            const extraPerGap = (maxLineWidth - line.width) / gaps;
+            let wordIdx = -1;
+            let prevWasSpace = true;
+            const spaceAdv = provider.getGlyph(' ', fontSize).advance;
+            for (const entry of line.placements) {
+                if (prevWasSpace && entry.info.advance !== spaceAdv) {
+                    wordIdx++;
+                    prevWasSpace = false;
+                }
+                else if (!prevWasSpace && entry.info.advance === spaceAdv) {
+                    prevWasSpace = true;
+                }
+                result.push({
+                    x: entry.x + offsetX + wordIdx * extraPerGap + (entry.info.xBearing ?? 0),
+                    y: entry.y + (entry.info.yBearing ?? 0),
+                    width: entry.info.width,
+                    height: entry.info.height,
+                    page: entry.info.page,
+                    uvLeft: entry.info.uvLeft,
+                    uvTop: entry.info.uvTop,
+                    uvRight: entry.info.uvRight,
+                    uvBottom: entry.info.uvBottom,
+                });
+            }
+            continue;
+        }
         for (const { info, x, y } of line.placements) {
             result.push({
-                x: x + offsetX,
-                y,
+                x: x + offsetX + (info.xBearing ?? 0),
+                y: y + (info.yBearing ?? 0),
                 width: info.width,
                 height: info.height,
+                page: info.page,
                 uvLeft: info.uvLeft,
                 uvTop: info.uvTop,
                 uvRight: info.uvRight,
@@ -58,6 +142,131 @@ function layoutText(text, style, atlas) {
     }
     return result;
 }
+/**
+ * Convert {@link GlyphPlacement} arrays into per-atlas-page quad geometry
+ * ready for GPU upload. Zero-size placements (e.g. whitespace glyphs that
+ * have no atlas entry) are skipped.
+ */
+function buildTextPageQuads(placements) {
+    const byPage = new Map();
+    for (const p of placements) {
+        if (p.width <= 0 || p.height <= 0)
+            continue; // skip invisible/whitespace quads
+        let arr = byPage.get(p.page);
+        if (arr === undefined)
+            byPage.set(p.page, (arr = []));
+        arr.push(p);
+    }
+    const result = [];
+    for (const [pageIndex, pagePlacements] of byPage) {
+        const n = pagePlacements.length;
+        const vertices = new Float32Array(n * 8);
+        const uvs = new Float32Array(n * 8);
+        const indices = new Uint16Array(n * 6);
+        for (let i = 0; i < n; i++) {
+            const p = pagePlacements[i];
+            const v = i * 8;
+            const baseV = i * 4;
+            const idxBase = i * 6;
+            vertices[v + 0] = p.x;
+            vertices[v + 1] = p.y;
+            vertices[v + 2] = p.x + p.width;
+            vertices[v + 3] = p.y;
+            vertices[v + 4] = p.x + p.width;
+            vertices[v + 5] = p.y + p.height;
+            vertices[v + 6] = p.x;
+            vertices[v + 7] = p.y + p.height;
+            uvs[v + 0] = p.uvLeft;
+            uvs[v + 1] = p.uvTop;
+            uvs[v + 2] = p.uvRight;
+            uvs[v + 3] = p.uvTop;
+            uvs[v + 4] = p.uvRight;
+            uvs[v + 5] = p.uvBottom;
+            uvs[v + 6] = p.uvLeft;
+            uvs[v + 7] = p.uvBottom;
+            indices[idxBase + 0] = baseV;
+            indices[idxBase + 1] = baseV + 1;
+            indices[idxBase + 2] = baseV + 2;
+            indices[idxBase + 3] = baseV;
+            indices[idxBase + 4] = baseV + 2;
+            indices[idxBase + 5] = baseV + 3;
+        }
+        result.push({ pageIndex, vertices, uvs, indices, quadCount: n });
+    }
+    return result;
+}
+// ── Internal helpers ──────────────────────────────────────────────────────────
+function _applyWhiteSpace(text, mode) {
+    if (mode === 'pre')
+        return text;
+    if (mode === 'normal') {
+        return text.replaceAll('\n', ' ').replaceAll(/[ \t]+/g, ' ');
+    }
+    // 'pre-line': collapse spaces per line, preserve newlines (default)
+    return text
+        .split('\n')
+        .map(line => line.replaceAll(/[ \t]+/g, ' '))
+        .join('\n');
+}
+function _wrapLine(line, fontSize, provider, maxWidth, letterSpacing, breakWords) {
+    if (line.length === 0)
+        return [''];
+    const words = line.split(' ');
+    const lines = [];
+    let current = '';
+    let currentWidth = 0;
+    const spaceAdv = provider.getGlyph(' ', fontSize).advance + letterSpacing;
+    for (const word of words) {
+        let wordWidth = 0;
+        for (const char of word) {
+            wordWidth += provider.getGlyph(char, fontSize).advance + letterSpacing;
+        }
+        wordWidth = Math.max(0, wordWidth - letterSpacing);
+        if (breakWords && wordWidth > maxWidth) {
+            if (current.length > 0) {
+                lines.push(current);
+                current = '';
+                currentWidth = 0;
+            }
+            let charLine = '';
+            let charLineWidth = 0;
+            for (const char of word) {
+                const cw = provider.getGlyph(char, fontSize).advance + letterSpacing;
+                if (charLine.length > 0 && charLineWidth + cw > maxWidth) {
+                    lines.push(charLine);
+                    charLine = char;
+                    charLineWidth = cw;
+                }
+                else {
+                    charLine += char;
+                    charLineWidth += cw;
+                }
+            }
+            if (charLine.length > 0) {
+                current = charLine;
+                currentWidth = charLineWidth;
+            }
+        }
+        else if (current.length === 0) {
+            current = word;
+            currentWidth = wordWidth;
+        }
+        else {
+            const withSpace = currentWidth + spaceAdv + wordWidth;
+            if (withSpace <= maxWidth) {
+                current += ` ${word}`;
+                currentWidth = withSpace;
+            }
+            else {
+                lines.push(current);
+                current = word;
+                currentWidth = wordWidth;
+            }
+        }
+    }
+    lines.push(current);
+    return lines;
+}
 
-export { layoutText };
+export { buildTextPageQuads, layoutText, measureText };
 //# sourceMappingURL=TextLayout.js.map

package/dist/esm/rendering/text/TextLayout.js.map

@@ -1 +1 @@
-{"version":3,"file":"TextLayout.js","sources":["../../../../../src/rendering/text/TextLayout.ts"],"sourcesContent":[null],"names":[],"mappings":"AAaA;;;;;;;;AAQG;SACa,UAAU,CAAC,IAAY,EAAE,KAAgB,EAAE,KAAwB,EAAA;AACjF,IAAA,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE;AACrB,QAAA,OAAO,EAAE;IACX;AAEA,IAAA,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,KAAK,EAAE,GAAG,KAAK;AAChF,IAAA,MAAM,kBAAkB,GAAG,QAAQ,GAAG,UAAU;IAChD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;;IAG9B,MAAM,cAAc,GAAoB,EAAE;IAC1C,IAAI,YAAY,GAAG,CAAC;AAEpB,IAAA,KAAK,IAAI,SAAS,GAAG,CAAC,EAAE,SAAS,GAAG,KAAK,CAAC,MAAM,EAAE,SAAS,EAAE,EAAE;AAC7D,QAAA,MAAM,IAAI,GAAG,KAAK,CAAC,SAAS,CAAC;AAC7B,QAAA,MAAM,CAAC,GAAG,SAAS,GAAG,kBAAkB;QACxC,IAAI,OAAO,GAAG,CAAC;QACf,MAAM,UAAU,GAAgC,EAAE;AAElD,QAAA,KAAK,MAAM,IAAI,IAAI,IAAI,EAAE;AACvB,YAAA,MAAM,IAAI,GAAG,KAAK,CAAC,QAAQ,CAAC,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,UAAU,EAAE,SAAS,CAAC;AAE9E,YAAA,UAAU,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;AACxC,YAAA,OAAO,IAAI,IAAI,CAAC,OAAO;QACzB;QAEA,MAAM,SAAS,GAAG,OAAO;AAEzB,QAAA,IAAI,SAAS,GAAG,YAAY,EAAE;YAC5B,YAAY,GAAG,SAAS;QAC1B;QAEA,cAAc,CAAC,IAAI,CAAC,EAAE,UAAU,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;IACvD;;IAGA,MAAM,MAAM,GAAqB,EAAE;AAEnC,IAAA,KAAK,MAAM,IAAI,IAAI,cAAc,EAAE;QACjC,IAAI,OAAO,GAAG,CAAC;AAEf,QAAA,IAAI,KAAK,KAAK,OAAO,EAAE;AACrB,YAAA,OAAO,GAAG,YAAY,GAAG,IAAI,CAAC,KAAK;QACrC;AAAO,aAAA,IAAI,KAAK,KAAK,QAAQ,EAAE;YAC7B,OAAO,GAAG,CAAC,YAAY,GAAG,IAAI,CAAC,KAAK,IAAI,CAAC;QAC3C;AAEA,QAAA,KAAK,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,EAAE,IAAI,IAAI,CAAC,UAAU,EAAE;YAC5C,MAAM,CAAC,IAAI,CAAC;gBACV,CAAC,EAAE,CAAC,GAAG,OAAO;gBACd,CAAC;gBACD,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,MAAM,EAAE,IAAI,CAAC,MAAM;gBACnB,MAAM,EAAE,IAAI,CAAC,MAAM;gBACnB,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,OAAO,EAAE,IAAI,CAAC,OAAO;gBACrB,QAAQ,EAAE,IAAI,CAAC,QAAQ;AACxB,aAAA,CAAC;QACJ;IACF;AAEA,IAAA,OAAO,MAAM;AACf;;;;"}
+{"version":3,"file":"TextLayout.js","sources":["../../../../../src/rendering/text/TextLayout.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}

package/dist/esm/rendering/text/TextStyle.d.ts

@@ -1,115 +1,182 @@
 import { Color } from '@/core/Color';
+import { Signal } from '@/core/Signal';
 import type { TextAlignment } from './types';
-/** A CSS color string, canvas gradient, or canvas pattern accepted as fill or stroke. */
-export type TextStyleColor = string | CanvasGradient | CanvasPattern;
+export type GradientAxis = 'vertical' | 'horizontal';
+/**
+ * Describes how costly a style change is to incorporate.
+ *
+ * Hints accumulate to the heaviest pending change:
+ * `tint` < `layout` < `font`
+ */
+export type StyleChangeHint = 'tint' | 'layout' | 'font';
+/**
+ * Font weight values accepted by CSS / Canvas 2D.
+ */
+export type FontWeight = 'normal' | 'bold' | '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900';
+/**
+ * Open interface for compile-time font-family autocomplete via declaration
+ * merging. Register loaded font families in your app's `.d.ts`:
+ *
+ * ```ts
+ * declare module 'exojs' {
+ *   interface FontRegistry {
+ *     'AndyBold': true;
+ *   }
+ * }
+ * ```
+ */
+export interface FontRegistry {
+}
+/**
+ * A CSS font-family string. When {@link FontRegistry} has entries the type
+ * narrows to registered names ∪ arbitrary strings (for unregistered fonts);
+ * without registry entries it falls back to plain `string`.
+ */
+export type FontFamily = [keyof FontRegistry] extends [never] ? string : keyof FontRegistry | (string & {});
 /**
  * Construction-time options for a {@link TextStyle}.
- * All properties are optional; defaults match the {@link TextStyle} constructor defaults.
+ * All properties are optional; defaults match the {@link TextStyle} constructor.
  */
 export interface TextStyleOptions {
-    align?: TextAlignment;
-    fill?: TextStyleColor;
+    /**
+     * A pre-constructed {@link FontFace} to use as the font for this node.
+     *
+     * When passed to {@link Text}, the face is automatically registered
+     * with `document.fonts`. Load the face via {@link FontFactory} before
+     * constructing the node so glyphs render immediately.
+     *
+     * Takes precedence over `fontFamily` when both are set.
+     *
+     * ```ts
+     * const face = await loader.load(FontFactory, 'roboto.woff2', { family: 'Roboto' });
+     * const label = new Text('Score: 0', { font: face, fontSize: 24 });
+     * ```
+     */
+    font?: FontFace;
+    fontFamily?: FontFamily;
+    fontWeight?: FontWeight;
+    fontStyle?: 'normal' | 'italic';
+    fontSize?: number;
     fillColor?: Color;
+    outlineColor?: Color;
+    /** Outline width in SDF units (0..0.5). 0 disables the outline. */
+    outlineWidth?: number;
+    align?: TextAlignment;
     lineHeight?: number;
-    stroke?: TextStyleColor;
-    strokeThickness?: number;
-    fontSize?: number;
-    fontWeight?: string;
-    fontFamily?: string;
-    fontStyle?: 'normal' | 'italic';
-    wordWrap?: boolean;
-    wordWrapWidth?: number;
-    baseline?: CanvasTextBaseline;
-    lineJoin?: CanvasLineJoin;
-    miterLimit?: number;
-    padding?: number;
+    /** Extra pixel gap between lines, added on top of `lineHeight`. */
+    leading?: number;
+    /** Drop-shadow color. */
+    shadowColor?: Color;
+    /** Horizontal shadow offset in pixels. */
+    shadowOffsetX?: number;
+    /** Vertical shadow offset in pixels. */
+    shadowOffsetY?: number;
+    /** Shadow opacity (0..1). 0 disables the shadow. */
+    shadowAlpha?: number;
+    /** Shadow blur softness (0..1). Larger values soften the shadow edge. */
+    shadowBlur?: number;
+    /**
+     * Two-stop fill gradient `[top, bottom]`. When set, overrides `fillColor`
+     * for the glyph interior. `null` disables the gradient.
+     */
+    gradientColors?: [Color, Color] | null;
+    /** Gradient orientation. Defaults to `'vertical'`. */
+    gradientAxis?: GradientAxis;
 }
 /**
- * Immutable-style value bag that describes how a {@link Text} node should
- * render its string. Every property setter marks the style as `dirty` so
- * that the owning Text can detect changes and rebuild its glyph mesh.
+ * Describes how a {@link Text} node renders its string.
  *
- * Glyphs are always rasterized in white; `fillColor` is applied as a
- * `Mesh.tint` multiplier at draw time, so changing it never triggers
- * atlas re-rasterization. The canvas `fill` / `stroke` properties are
- * used only during glyph rasterization itself.
+ * Every setter marks the style dirty with a {@link StyleChangeHint} so that
+ * the owning node can batch-rebuild efficiently on the next frame:
+ * - `'tint'`  — only updates `Mesh.tint`, no atlas work
+ * - `'layout'` — rebuilds the glyph mesh, reuses cached atlas glyphs
+ * - `'font'`  — atlas lookup + full mesh rebuild
+ *
+ * Call {@link consumeDirty} at the start of each frame to get the accumulated
+ * hint and clear the flag.
  */
 export declare class TextStyle {
-    private _align;
-    private _fill;
-    private _fillColor;
-    private _lineHeight;
-    private _stroke;
-    private _strokeThickness;
-    private _fontSize;
-    private _fontWeight;
+    private _dirty;
+    private _pendingHint;
+    /** Fires once per dirty cycle when any property changes. */
+    readonly onChange: Signal<[]>;
     private _fontFamily;
+    private _fontWeight;
     private _fontStyle;
-    private _wordWrap;
-    private _wordWrapWidth;
-    private _baseline;
-    private _lineJoin;
-    private _miterLimit;
-    private _padding;
-    private _dirty;
+    private _fontSize;
+    private _fillColor;
+    private _outlineColor;
+    private _outlineWidth;
+    private _align;
+    private _lineHeight;
+    private _leading;
+    private _shadowColor;
+    private _shadowOffsetX;
+    private _shadowOffsetY;
+    private _shadowAlpha;
+    private _shadowBlur;
+    private _gradientColors;
+    private _gradientAxis;
     constructor(options?: TextStyleOptions);
-    get align(): TextAlignment;
-    set align(align: TextAlignment);
-    get fill(): TextStyleColor;
-    set fill(fill: TextStyleColor);
     /**
-     * Runtime fill color applied via `Mesh.tint`. Glyphs are always
-     * rasterized white; this color multiplies them at draw time so that
-     * changing the color never requires re-rasterizing cached glyphs.
+     * Returns the accumulated {@link StyleChangeHint} and clears the dirty flag,
+     * or `null` if nothing has changed since the last call.
+     *
+     * Call this once per frame from the owning node's `update()` method.
      */
-    get fillColor(): Color;
-    set fillColor(color: Color);
-    /**
-     * Line-height multiplier applied to `fontSize` when computing vertical
-     * spacing between lines. Defaults to 1.2.
-     */
-    get lineHeight(): number;
-    set lineHeight(lineHeight: number);
-    get stroke(): TextStyleColor;
-    set stroke(stroke: TextStyleColor);
-    get strokeThickness(): number;
-    set strokeThickness(strokeThickness: number);
-    get fontSize(): number;
-    set fontSize(fontSize: number);
-    get fontWeight(): string;
-    set fontWeight(fontWeight: string);
-    get fontFamily(): string;
-    set fontFamily(fontFamily: string);
+    consumeDirty(): StyleChangeHint | null;
+    private _markDirty;
+    get fontFamily(): FontFamily;
+    set fontFamily(v: FontFace | FontFamily);
+    get fontWeight(): FontWeight;
+    set fontWeight(v: FontWeight);
     get fontStyle(): 'normal' | 'italic';
-    set fontStyle(fontStyle: 'normal' | 'italic');
-    get wordWrap(): boolean;
-    set wordWrap(wordWrap: boolean);
-    get wordWrapWidth(): number;
-    set wordWrapWidth(wordWrapWidth: number);
-    get baseline(): CanvasTextBaseline;
-    set baseline(baseline: CanvasTextBaseline);
-    get lineJoin(): CanvasLineJoin;
-    set lineJoin(lineJoin: CanvasLineJoin);
-    get miterLimit(): number;
-    set miterLimit(miterLimit: number);
-    get padding(): number;
-    set padding(padding: number);
+    set fontStyle(v: 'normal' | 'italic');
+    get fontSize(): number;
+    set fontSize(v: number);
+    get align(): TextAlignment;
+    set align(v: TextAlignment);
+    get lineHeight(): number;
+    set lineHeight(v: number);
+    /** Extra pixel gap between lines, added on top of `lineHeight`. */
+    get leading(): number;
+    set leading(v: number);
     /**
-     * Whether any property has changed since the last time this flag was
-     * cleared. {@link Text} reads this to decide whether to rebuild its mesh.
+     * Runtime fill color applied as `Mesh.tint`. Glyphs are always rasterized
+     * white; this color multiplies them at draw time without touching the atlas.
      */
-    get dirty(): boolean;
-    set dirty(dirty: boolean);
+    get fillColor(): Color;
+    set fillColor(v: Color);
+    /** Outline color — used by BitmapText/SDF rendering as a shader uniform. */
+    get outlineColor(): Color;
+    set outlineColor(v: Color);
+    /** Outline width in SDF units (0..0.5). `0` disables the outline. */
+    get outlineWidth(): number;
+    set outlineWidth(v: number);
+    get shadowColor(): Color;
+    set shadowColor(v: Color);
+    get shadowOffsetX(): number;
+    set shadowOffsetX(v: number);
+    get shadowOffsetY(): number;
+    set shadowOffsetY(v: number);
+    /** Shadow opacity (0..1). `0` disables the shadow. */
+    get shadowAlpha(): number;
+    set shadowAlpha(v: number);
+    get shadowBlur(): number;
+    set shadowBlur(v: number);
     /**
-     * CSS font string derived from `fontWeight`, `fontSize`, and `fontFamily`.
-     * Used as `CanvasRenderingContext2D.font` during glyph rasterization.
+     * Two-stop fill gradient `[top, bottom]`. When set, overrides `fillColor`
+     * for the glyph interior. Assign `null` to disable.
      */
-    get font(): string;
+    get gradientColors(): [Color, Color] | null;
+    set gradientColors(v: [Color, Color] | null);
+    get gradientAxis(): GradientAxis;
+    set gradientAxis(v: GradientAxis);
     /**
-     * Apply this style's properties to a canvas 2D context so the next
-     * `fillText` / `strokeText` call uses the correct font, color, and stroke.
+     * CSS font string used as `CanvasRenderingContext2D.font` during glyph
+     * rasterization. Includes `fontStyle` so italic fonts render correctly.
      */
-    apply(context: CanvasRenderingContext2D): this;
+    get font(): string;
     /** Copy all properties from `style` into this instance and return `this`. */
     copy(style: TextStyle): this;
     /** Return a new {@link TextStyle} with all properties copied from this one. */