@vincentt-xr/sdk 2.0.0-alpha.0 → 2.0.0-alpha.2

package/dist/components/ScreenSpaceUI/ScreenTransformOverlayGuide.d.ts

@@ -0,0 +1,9 @@
+import { ScreenTransform2DSettings } from '../../screen2d';
+export type ScreenTransformGuideLayer = "scene" | "overlay";
+export type ScreenTransformOverlayGuideProps = {
+    color?: string;
+    handleColor?: string;
+    onChange?: (next: ScreenTransform2DSettings) => void;
+    transform: ScreenTransform2DSettings;
+};
+export declare const ScreenTransformOverlayGuide: ({ color, handleColor, onChange, transform, }: ScreenTransformOverlayGuideProps) => null;

package/dist/components/ScreenSpaceUI/index.d.ts

@@ -36,5 +36,7 @@ export type ScreenSpaceUIProps = {
  */
 export declare const ScreenSpaceUI: ({ children, depth }: ScreenSpaceUIProps) => import("react/jsx-runtime").JSX.Element;
 export { ScreenTransform } from './ScreenTransform';
+export { ScreenTransformGuide } from './ScreenTransformGuide';
+export { ScreenTransformOverlayGuide, type ScreenTransformGuideLayer, } from './ScreenTransformOverlayGuide';
 export type { ScreenTransformProps, ScreenAnchorEdges, ScreenOffsetEdges, ResolvedScreenTransform, } from './ScreenTransform';
 export { computeScreenTransform } from './ScreenTransform';

package/dist/components/ScreenText/components/ScreenTextBody.d.ts

@@ -0,0 +1,2 @@
+import { ScreenTextBodyProps } from '../types';
+export declare function ScreenTextBody(props: ScreenTextBodyProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/ScreenText/components/ScreenTextTransformFrame.d.ts

@@ -0,0 +1,9 @@
+import { ReactNode } from 'react';
+import { ScreenTransformGuideLayer } from '../../ScreenSpaceUI';
+import { ScreenTransform2DSettings } from '../../../screen2d';
+export declare function ScreenTextTransformFrame({ transform, guideLayer, onChange, children, }: {
+    transform: ScreenTransform2DSettings;
+    guideLayer: ScreenTransformGuideLayer;
+    onChange?: (next: ScreenTransform2DSettings) => void;
+    children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/components/ScreenText/constants.d.ts

@@ -0,0 +1,5 @@
+import { ScreenAnchorEdges } from '../ScreenSpaceUI';
+import { ScreenTextVerticalAlign } from './types';
+export declare const DEFAULT_SCREEN_TEXT_ASPECT = 2.5;
+export declare const SCREEN_TEXT_GUIDE_COLOR = "#38bdf8";
+export declare const SCREEN_TEXT_ANCHORS: Record<ScreenTextVerticalAlign, Required<ScreenAnchorEdges>>;

package/dist/components/ScreenText/index.d.ts

@@ -0,0 +1,6 @@
+import { ScreenTextProps } from './types';
+export { SCREEN_TEXT_ANCHORS } from './constants';
+export { resolveScreenTextAnchors } from './utils/ScreenTextHelpers';
+export { resolveScreenTextBendProps, resolveScreenTextLayoutTexture, } from './utils/ScreenTextMappings';
+export type { ScreenTextBendSettings, ScreenTextProps, ScreenTextVerticalAlign } from './types';
+export declare function ScreenText({ anchors, coordinateSpace, canvasSize, offsets, pivot, position, rotation, size, transform, screenTransform, onScreenTransformChange, transformGuideLayer, verticalAlign, ...textLabelProps }: ScreenTextProps): import("react/jsx-runtime").JSX.Element | null;

package/dist/components/ScreenText/types.d.ts

@@ -0,0 +1,31 @@
+import { TextBendPreset, TextLabelProps } from '../TextLabel';
+import { ScreenAnchorEdges, ScreenTransformGuideLayer } from '../ScreenSpaceUI';
+import { ScreenCanvasSize, ScreenCoordinateSpace, ScreenTransform2D, ScreenTransform2DSettings } from '../../screen2d';
+export type ScreenTextVerticalAlign = "top" | "center" | "bottom";
+export type ScreenTextBendSettings = {
+    preset: TextBendPreset;
+    strength: number;
+};
+export type ScreenTextProps = Omit<TextLabelProps, "aspect" | "position" | "rotation" | "scale"> & {
+    anchors?: ScreenAnchorEdges;
+    coordinateSpace?: ScreenCoordinateSpace;
+    canvasSize?: ScreenCanvasSize;
+    offsets?: ScreenTransform2D["offsets"];
+    pivot?: [number, number];
+    position?: [number, number];
+    rotation?: number;
+    size?: [number, number];
+    transform?: ScreenTransform2D;
+    screenTransform?: Partial<ScreenTransform2DSettings>;
+    onScreenTransformChange?: (next: ScreenTransform2DSettings) => void;
+    transformGuideLayer?: ScreenTransformGuideLayer;
+    verticalAlign?: ScreenTextVerticalAlign;
+    bend?: ScreenTextBendSettings;
+    showTransformGuides?: boolean;
+};
+export type ScreenTextBodyProps = Omit<ScreenTextProps, "anchors" | "coordinateSpace" | "canvasSize" | "offsets" | "pivot" | "position" | "rotation" | "size" | "transform"> & {
+    layoutSize?: {
+        width: number;
+        height: number;
+    };
+};

package/dist/components/ScreenText/utils/ScreenTextHelpers.d.ts

@@ -0,0 +1,14 @@
+import { ScreenTextProps, ScreenTextVerticalAlign } from '../types';
+export declare function resolveScreenTextAnchors(verticalAlign?: ScreenTextVerticalAlign): Required<import('../..').ScreenAnchorEdges>;
+export declare function resolveScreenTextTransformProps({ anchors, coordinateSpace, canvasSize, position, size, transform, pivot, verticalAlign, }: Pick<ScreenTextProps, "anchors" | "coordinateSpace" | "canvasSize" | "position" | "size" | "transform" | "pivot"> & {
+    verticalAlign: ScreenTextVerticalAlign;
+}): {
+    resolvedAnchors: import('../..').ScreenAnchorEdges;
+    resolvedOffsets: {
+        left?: number;
+        right?: number;
+        top?: number;
+        bottom?: number;
+    } | undefined;
+    resolvedPivot: [number, number];
+};

package/dist/components/ScreenText/utils/ScreenTextMappings.d.ts

@@ -0,0 +1,17 @@
+import { TextBendPreset } from '../../TextLabel';
+import { ScreenTextBendSettings } from '../types';
+export declare function resolveScreenTextBendProps({ bend, bendPreset, bendStrength, }: {
+    bend?: ScreenTextBendSettings;
+    bendPreset?: TextBendPreset;
+    bendStrength?: number;
+}): {
+    bendPreset: TextBendPreset | undefined;
+    bendStrength: number | undefined;
+};
+export declare function resolveScreenTextLayoutTexture({ width, height, }: {
+    width: number;
+    height: number;
+}): {
+    aspect: number;
+    resolution: number;
+};

package/dist/components/SequentialRenderPasses/index.d.ts

@@ -0,0 +1,6 @@
+export type SequentialRenderPassesProps = {
+    /** Camera layers in top-first/bottom-last hierarchy order. */
+    layers: number[];
+};
+/** Takes over R3F rendering and composes render-group layers sequentially. */
+export declare const SequentialRenderPasses: ({ layers }: SequentialRenderPassesProps) => null;

package/dist/components/TextLabel/TextLabel.d.ts

@@ -0,0 +1,5 @@
+import { TextLabelProps } from './types';
+export type { TextLabelProps } from './types';
+export { resolveTextLabelDrawX, resolveTextLabelPanelX, resolveTextLabelStartY } from './alignment';
+export type { TextAlign, TextBackgroundFillMode, TextBackgroundFit, TextBackgroundTextureFit, TextBendPreset, TextGlow, TextGradientStop, TextInnerShadow, TextOverflowMode, TextShadowLayer, TextStrokeLayer, TextVerticalAlign, } from './types';
+export declare function TextLabel(props: TextLabelProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/TextLabel/alignment.d.ts

@@ -0,0 +1,4 @@
+import { TextAlign, TextVerticalAlign } from './types';
+export declare function resolveTextLabelDrawX(width: number, padding: number, textAlign: TextAlign): number;
+export declare function resolveTextLabelStartY(height: number, padding: number, fontSize: number, textBlockContentHeight: number, verticalAlign: TextVerticalAlign): number;
+export declare function resolveTextLabelPanelX(width: number, panelWidth: number, textAlign: TextAlign, bgFit: "full" | "text"): number;

package/dist/components/TextLabel/bend.d.ts

@@ -0,0 +1,9 @@
+import { TextBendPreset } from './types';
+export type BendGlyphTransform = {
+    xOffset: number;
+    yOffset: number;
+    rotation: number;
+    scaleX: number;
+    scaleY: number;
+};
+export declare function resolveBendGlyphTransform(preset: TextBendPreset, normalizedX: number, index: number, glyphCount: number, amplitude: number, halfWidth: number): BendGlyphTransform;

package/dist/components/TextLabel/canvas/buildTextLabelTexture.d.ts

@@ -0,0 +1,4 @@
+import { BuildTextLabelTextureOptions } from '../types';
+import * as THREE from "three";
+export { resolveTextLayout } from '../layout/resolveTextLayout';
+export declare function buildTextLabelTexture(opts: BuildTextLabelTextureOptions): THREE.CanvasTexture;

package/dist/components/TextLabel/canvas/canvasTypography.d.ts

@@ -0,0 +1,13 @@
+import { BuildTextLabelTextureOptions } from '../types';
+export declare function createTextCanvas(width: number, height: number): HTMLCanvasElement;
+export declare function resolveCanvasTextMetrics(ctx: CanvasRenderingContext2D, opts: BuildTextLabelTextureOptions): {
+    fontSize: number;
+    resolvedLines: string[];
+    letterSpacingPx: number;
+    lineHeight: number;
+    startY: number;
+    textBlockWidth: number;
+    textBlockHeight: number;
+    textX: number;
+};
+export declare function drawRoundedRectPath(ctx: CanvasRenderingContext2D, x: number, y: number, width: number, height: number, radius: number): void;

package/dist/components/TextLabel/canvas/drawBackground.d.ts

@@ -0,0 +1,21 @@
+import { TextAlign, TextBackgroundFillMode, TextBackgroundFit, TextBackgroundTextureFit, TextGradientStop } from '../types';
+export declare function clampPanelDimension(value: number | undefined, fallback: number, maxValue: number): number;
+export declare function drawPanelBackground(ctx: CanvasRenderingContext2D, opts: {
+    canvasWidth: number;
+    canvasHeight: number;
+    textAlign: TextAlign;
+    bgFit: TextBackgroundFit;
+    panelWidth: number;
+    panelHeight: number;
+    bgColor: string;
+    bgFillMode: TextBackgroundFillMode;
+    bgOpacity: number;
+    bgGradientStops?: TextGradientStop[];
+    bgTextureImage?: CanvasImageSource;
+    bgTextureFit: TextBackgroundTextureFit;
+    bgTextureFlipX: boolean;
+    bgTextureFlipY: boolean;
+    borderColor?: string;
+    borderWidth: number;
+    borderRadius: number;
+}): void;

package/dist/components/TextLabel/canvas/drawEffects.d.ts

@@ -0,0 +1,34 @@
+import { TextAlign, TextBendPreset } from '../types';
+export declare function drawGlow(ctx: CanvasRenderingContext2D, opts: {
+    lines: string[];
+    textX: number;
+    startY: number;
+    lineHeight: number;
+    letterSpacingPx: number;
+    bendPreset: TextBendPreset;
+    bendStrength: number;
+    color: string;
+    style: "outward" | "contoured";
+    intensity: number;
+    range: number;
+    horizontalAngle: number;
+    verticalAngle: number;
+}): void;
+export declare function drawInnerShadow(ctx: CanvasRenderingContext2D, opts: {
+    width: number;
+    height: number;
+    font: string;
+    lines: string[];
+    textX: number;
+    startY: number;
+    lineHeight: number;
+    letterSpacingPx: number;
+    bendPreset: TextBendPreset;
+    bendStrength: number;
+    textAlign: TextAlign;
+    color: string;
+    opacity: number;
+    blur: number;
+    offsetX: number;
+    offsetY: number;
+}): void;

package/dist/components/TextLabel/canvas/drawText.d.ts

@@ -0,0 +1,19 @@
+import { TextAlign, TextBendPreset, TextShadowLayer, TextStrokeLayer } from '../types';
+export declare function drawTextLine(ctx: CanvasRenderingContext2D, line: string, textX: number, lineY: number, letterSpacingPx: number, mode: "fill" | "stroke", bendPreset?: TextBendPreset, bendStrength?: number): void;
+export declare function drawTextDecorationLine(ctx: CanvasRenderingContext2D, line: string, textX: number, lineY: number, textAlign: TextAlign, color: string, fontSize: number, letterSpacingPx: number, decoration: "underline" | "strikethrough"): void;
+export declare function drawTextLayers(ctx: CanvasRenderingContext2D, opts: {
+    lines: string[];
+    textX: number;
+    startY: number;
+    lineHeight: number;
+    textAlign: TextAlign;
+    color: string;
+    fontSize: number;
+    letterSpacingPx: number;
+    bendPreset: TextBendPreset;
+    bendStrength: number;
+    shadowLayers: TextShadowLayer[];
+    strokeLayers: TextStrokeLayer[];
+    underline: boolean;
+    strikethrough: boolean;
+}): void;

package/dist/components/TextLabel/components/TextLabelMesh.d.ts

@@ -0,0 +1,13 @@
+import type * as THREE from "three";
+export type TextLabelMeshProps = {
+    texture: THREE.Texture;
+    name?: string;
+    overlay: boolean;
+    opacity: number;
+    position?: [number, number, number];
+    rotation?: [number, number, number];
+    scale?: [number, number, number] | number;
+    visible?: boolean;
+    renderOrder?: number;
+};
+export declare const TextLabelMesh: import('react').ForwardRefExoticComponent<TextLabelMeshProps & import('react').RefAttributes<THREE.Mesh<THREE.BufferGeometry<THREE.NormalBufferAttributes>, THREE.Material | THREE.Material[], THREE.Object3DEventMap>>>;

package/dist/components/TextLabel/constants.d.ts

@@ -0,0 +1,2 @@
+import { TextLabelDefaults } from './types';
+export declare const TEXT_LABEL_DEFAULTS: TextLabelDefaults;

package/dist/components/TextLabel/hooks/useTextLabelTexture.d.ts

@@ -0,0 +1,7 @@
+import { TextLabelDefaults, TextLabelProps } from '../types';
+type NormalizedTextLabelProps = TextLabelProps & TextLabelDefaults;
+export declare function useTextLabelTexture(props: NormalizedTextLabelProps, overrides: {
+    text: string;
+    bgColor: string;
+}): import('three').CanvasTexture;
+export {};

package/dist/components/TextLabel/index.d.ts

@@ -1,62 +1,2 @@
-/**
- * `<TextLabel>` — a text label drawn into a CanvasTexture and rendered as
- * a single mesh. First-class scene-tree primitive so lifecycle scripts
- * don't have to hand-paint canvas textures for every quiz question,
- * progress indicator, or floating answer.
- *
- * Sizes itself 1×1 in world units; use `scale` on the JSX node or a
- * parent `<ScreenTransform>` / `<TrackingAnchor>` to place it.
- *
- * Word-wraps automatically inside the panel's width; when there are too
- * many lines for the chosen font size, the font shrinks one step before
- * the text is allowed to clip.
- */
-export type TextLabelProps = {
-    /** The text to render. Required. */
-    text: string;
-    /** Text color. Default `#ffffff`. */
-    color?: string;
-    /** Font weight. Default `bold`. */
-    fontWeight?: "normal" | "bold" | number;
-    /** Font family. Default `Arial, sans-serif`. */
-    fontFamily?: string;
-    /**
-     * Font size in canvas px at the default 512px resolution. Roughly maps
-     * to "10pt" → 28, "12pt" → 36, "16pt" → 48, etc. Default 48.
-     */
-    fontSize?: number;
-    /** Panel background color. Use `'transparent'` for text-only. Default `rgba(20,40,110,0.88)`. */
-    bgColor?: string;
-    /** Optional border color. Omit for no border. */
-    borderColor?: string;
-    /** Border thickness. Default 0. */
-    borderWidth?: number;
-    /** Corner radius. Use 0 for square. Default 24. */
-    borderRadius?: number;
-    /** Inner padding in canvas px. Default 32. */
-    padding?: number;
-    /**
-     * Aspect ratio (width / height). The mesh itself is always 1×1; this
-     * controls how the texture canvas is shaped so wrapping and corner
-     * radius read correctly when the label isn't square. Default 2.5
-     * (roughly banner-shaped).
-     */
-    aspect?: number;
-    /** Canvas resolution (height in px). Default 512. */
-    resolution?: number;
-    /** Material opacity multiplier. Default 1. */
-    opacity?: number;
-    /** Optional `name` for runtime `getObjectByName` lookups. */
-    name?: string;
-    /** Ignore depth — appropriate for overlay UI. Default true. */
-    overlay?: boolean;
-    /** Local position offset, forwarded to the underlying mesh. */
-    position?: [number, number, number];
-    /** Local rotation (Euler radians), forwarded to the underlying mesh. */
-    rotation?: [number, number, number];
-    /** Local scale, forwarded to the underlying mesh. */
-    scale?: [number, number, number] | number;
-    /** Mesh visibility, forwarded so descendants inherit correctly. */
-    visible?: boolean;
-};
-export declare function TextLabel(props: TextLabelProps): import("react/jsx-runtime").JSX.Element;
+export { TextLabel, resolveTextLabelDrawX, resolveTextLabelPanelX, resolveTextLabelStartY, } from './TextLabel';
+export type { TextAlign, TextBackgroundFillMode, TextBackgroundFit, TextBackgroundTextureFit, TextBendPreset, TextGlow, TextGradientStop, TextInnerShadow, TextLabelProps, TextOverflowMode, TextShadowLayer, TextStrokeLayer, TextVerticalAlign, } from './types';

package/dist/components/TextLabel/layout/measurement.d.ts

@@ -0,0 +1,8 @@
+export declare function formatCanvasFont(fontStyle: "normal" | "italic", fontWeight: "normal" | "bold" | number, fontSize: number, fontFamily: string): string;
+export declare function resolveLetterSpacingPx(fontSize: number, letterSpacing: number): number;
+export declare function resolveLineHeight(fontSize: number, lineSpacing: number): number;
+export declare function applyCanvasLetterSpacing(ctx: CanvasRenderingContext2D, letterSpacingPx: number): void;
+export declare function resetCanvasLetterSpacing(ctx: CanvasRenderingContext2D): void;
+export declare function measureTextWidth(ctx: CanvasRenderingContext2D, text: string, letterSpacingPx: number): number;
+export declare function computeMaxLines(height: number, padding: number, fontSize: number, lineSpacing: number): number;
+export declare function linesFit(ctx: CanvasRenderingContext2D, sourceLines: string[], maxWidth: number, maxLines: number, letterSpacingPx: number): boolean;

package/dist/components/TextLabel/layout/resolveTextLayout.d.ts

@@ -0,0 +1,25 @@
+import { TextOverflowMode } from '../types';
+export type ResolveTextLayoutOptions = {
+    ctx: CanvasRenderingContext2D;
+    text: string;
+    explicitLines?: string[];
+    maxWidth: number;
+    maxHeight: number;
+    padding: number;
+    fontStyle: "normal" | "italic";
+    fontWeight: "normal" | "bold" | number;
+    fontSize: number;
+    fontFamily: string;
+    letterSpacing: number;
+    lineSpacing: number;
+    overflow?: TextOverflowMode;
+    resizeToFit?: boolean;
+    minFontSize: number;
+};
+export type ResolveLegacyTextLayoutOptions = Omit<ResolveTextLayoutOptions, "explicitLines" | "overflow" | "resizeToFit" | "minFontSize">;
+export type ResolvedTextLayout = {
+    fontSize: number;
+    lines: string[];
+};
+export declare function resolveTextLayout(opts: ResolveTextLayoutOptions): ResolvedTextLayout;
+export declare function resolveLegacyTextLayout(opts: ResolveLegacyTextLayoutOptions): ResolvedTextLayout;

package/dist/components/TextLabel/layout/wrapText.d.ts

@@ -0,0 +1,6 @@
+import { TextOverflowMode } from '../types';
+export declare function wrapText(ctx: CanvasRenderingContext2D, text: string, maxWidth: number, fontStyle: "normal" | "italic", fontWeight: "normal" | "bold" | number, fontSize: number, fontFamily: string, letterSpacingPx: number): string[];
+export declare function wrapTextPreservingBreaks(ctx: CanvasRenderingContext2D, text: string, maxWidth: number, fontStyle: "normal" | "italic", fontWeight: "normal" | "bold" | number, fontSize: number, fontFamily: string, letterSpacingPx: number): string[];
+export declare function trimLineToWidth(ctx: CanvasRenderingContext2D, line: string, maxWidth: number, withEllipsis: boolean, letterSpacingPx: number): string;
+export declare function clampLinesToWidth(ctx: CanvasRenderingContext2D, sourceLines: string[], maxWidth: number, overflow: TextOverflowMode | undefined, letterSpacingPx: number): string[];
+export declare function collapseToLineBudget(ctx: CanvasRenderingContext2D, sourceLines: string[], maxLines: number, maxWidth: number, withEllipsis: boolean, letterSpacingPx: number): string[];

package/dist/components/TextLabel/types.d.ts

@@ -0,0 +1,227 @@
+export type TextAlign = "left" | "center" | "right";
+export type TextVerticalAlign = "top" | "center" | "bottom";
+export type TextBendPreset = "arc" | "arc-lower" | "arc-upper" | "arch" | "bulge" | "shell-lower" | "shell-upper" | "flag" | "wave" | "fish" | "rise" | "fisheye" | "inflate" | "squeeze" | "twist";
+export type TextStrokeLayer = {
+    color: string;
+    width: number;
+    opacity?: number;
+};
+export type TextShadowLayer = {
+    color: string;
+    blur: number;
+    offsetX?: number;
+    offsetY?: number;
+    opacity?: number;
+};
+export type TextInnerShadow = {
+    color: string;
+    blur: number;
+    offsetX?: number;
+    offsetY?: number;
+    opacity?: number;
+};
+export type TextGlow = {
+    color: string;
+    style: "outward" | "contoured";
+    intensity?: number;
+    range?: number;
+    horizontalAngle?: number;
+    verticalAngle?: number;
+};
+export type TextOverflowMode = "clip" | "clamp" | "ellipsis" | "shrink";
+export type TextBackgroundFillMode = "solid" | "gradient";
+export type TextBackgroundFit = "full" | "text";
+export type TextBackgroundTextureFit = "cover" | "contain" | "stretch";
+export type TextGradientStop = {
+    color: string;
+    position: number;
+};
+/**
+ * `<TextLabel>` — a text label drawn into a CanvasTexture and rendered as
+ * a single mesh. First-class scene-tree primitive so lifecycle scripts
+ * don't have to hand-paint canvas textures for every quiz question,
+ * progress indicator, or floating answer.
+ *
+ * Sizes itself 1x1 in world units; use `scale` on the JSX node or a
+ * parent `<ScreenTransform>` / `<TrackingAnchor>` to place it.
+ *
+ * Word-wraps automatically inside the panel's width; when there are too
+ * many lines for the chosen font size, the font shrinks one step before
+ * the text is allowed to clip.
+ */
+export type TextLabelProps = {
+    /** The text to render. Required. */
+    text: string;
+    /** Optional precomputed lines. When provided, these are rendered directly without word wrapping. */
+    lines?: string[];
+    /** Text color. Default `#ffffff`. */
+    color?: string;
+    /** Multiple stroke layers, drawn outer-to-inner. */
+    strokeLayers?: TextStrokeLayer[];
+    /** Master visibility gate for all stroke/outline rendering. Default true. */
+    outlineEnabled?: boolean;
+    /** Optional text stroke color. Omit or pair with `strokeWidth={0}` for no stroke. */
+    strokeColor?: string;
+    /** Text stroke thickness in canvas px. Default 0. */
+    strokeWidth?: number;
+    /** Stroke opacity multiplier. Default 1. */
+    strokeOpacity?: number;
+    /** Multiple shadow / glow layers, drawn back-to-front. */
+    shadowLayers?: TextShadowLayer[];
+    /** Master visibility gate for all outer shadow rendering. Default true. */
+    shadowEnabled?: boolean;
+    /** Optional inner shadow rendered inside the glyphs. */
+    innerShadow?: TextInnerShadow;
+    /** Optional glow rendered behind the glyphs. */
+    glow?: TextGlow;
+    /** Optional text shadow/glow color. Omit for none. */
+    shadowColor?: string;
+    /** Shadow blur radius in canvas px. Default 0. */
+    shadowBlur?: number;
+    /** Shadow X offset in canvas px. Default 0. */
+    shadowOffsetX?: number;
+    /** Shadow Y offset in canvas px. Default 0. */
+    shadowOffsetY?: number;
+    /** Shadow opacity multiplier. Default 1. */
+    shadowOpacity?: number;
+    /** Font weight. Default `bold`. */
+    fontWeight?: "normal" | "bold" | number;
+    /** Font style. Default `normal`. */
+    fontStyle?: "normal" | "italic";
+    /** Font family. Default `Arial, sans-serif`. */
+    fontFamily?: string;
+    /**
+     * Font size in canvas px at the default 512px resolution. Roughly maps
+     * to "10pt" -> 28, "12pt" -> 36, "16pt" -> 48, etc. Default 48.
+     */
+    fontSize?: number;
+    /** Horizontal text alignment inside the available lane. Default `center`. */
+    textAlign?: TextAlign;
+    /** Vertical text alignment inside the available lane. Default `center`. */
+    verticalAlign?: TextVerticalAlign;
+    /** Overflow behavior. `clamp` keeps only full visible lines, `clip` allows canvas-edge clipping. */
+    overflow?: TextOverflowMode;
+    /** When true, keep shrinking until the text fits or `minFontSize` is hit. */
+    resizeToFit?: boolean;
+    /** Minimum shrink target in canvas px. Default 12. */
+    minFontSize?: number;
+    /** Character spacing as a normalized ratio from 0 to 1. Default 0. */
+    letterSpacing?: number;
+    /** Line spacing as a normalized ratio from 0 to 1. Default 0.3. */
+    lineSpacing?: number;
+    /** Panel background color. Use `'transparent'` for text-only. Default `rgba(20,40,110,0.88)`. */
+    bgColor?: string;
+    /** Background fill mode. Default `solid`. */
+    bgFillMode?: TextBackgroundFillMode;
+    /** Background opacity multiplier. Default 1. */
+    bgOpacity?: number;
+    /** Background fit mode. `full` fills the label rect, `text` hugs the measured text block. */
+    bgFit?: TextBackgroundFit;
+    /** When true, ignore explicit background width/height and size from the text block. */
+    bgAutoSize?: boolean;
+    /** Optional explicit background width in canvas px. */
+    bgWidth?: number;
+    /** Optional explicit background height in canvas px. */
+    bgHeight?: number;
+    /** Optional gradient stops when `bgFillMode` is `gradient`. */
+    bgGradientStops?: TextGradientStop[];
+    /** Optional static texture URL when `bgFillMode` is `texture`. */
+    bgTextureUrl?: string;
+    /** Texture fit behavior. Default `cover`. */
+    bgTextureFit?: TextBackgroundTextureFit;
+    /** Mirror the background texture horizontally. Default false. */
+    bgTextureFlipX?: boolean;
+    /** Mirror the background texture vertically. Default false. */
+    bgTextureFlipY?: boolean;
+    /** Optional border color. Omit for no border. */
+    borderColor?: string;
+    /** Border thickness. Default 0. */
+    borderWidth?: number;
+    /** Corner radius. Use 0 for square. Default 24. */
+    borderRadius?: number;
+    /** Inner padding in canvas px. Default 32. */
+    padding?: number;
+    /**
+     * Aspect ratio (width / height). The mesh itself is always 1x1; this
+     * controls how the texture canvas is shaped so wrapping and corner
+     * radius read correctly when the label isn't square. Default 2.5
+     * (roughly banner-shaped).
+     */
+    aspect?: number;
+    /** Canvas resolution (height in px). Default 512. */
+    resolution?: number;
+    /** Material opacity multiplier. Default 1. */
+    opacity?: number;
+    /** Draw an underline beneath each rendered line. Default false. */
+    underline?: boolean;
+    /** Draw a strikethrough across each rendered line. Default false. */
+    strikethrough?: boolean;
+    /** Bend text along a shallow vertical curve. Range -100..100. Default 0. */
+    bendPreset?: TextBendPreset;
+    bendStrength?: number;
+    /** Optional `name` for runtime `getObjectByName` lookups. */
+    name?: string;
+    /** Ignore depth - appropriate for overlay UI. Default true. */
+    overlay?: boolean;
+    /** Local position offset, forwarded to the underlying mesh. */
+    position?: [number, number, number];
+    /** Local rotation (Euler radians), forwarded to the underlying mesh. */
+    rotation?: [number, number, number];
+    /** Local scale, forwarded to the underlying mesh. */
+    scale?: [number, number, number] | number;
+    /** Mesh visibility, forwarded so descendants inherit correctly. */
+    visible?: boolean;
+    /** Render ordering for overlay composition. */
+    renderOrder?: number;
+};
+export type TextLabelDefaults = Required<Pick<TextLabelProps, "color" | "strokeWidth" | "strokeOpacity" | "shadowBlur" | "shadowOffsetX" | "shadowOffsetY" | "shadowOpacity" | "fontWeight" | "fontStyle" | "fontFamily" | "fontSize" | "textAlign" | "verticalAlign" | "minFontSize" | "letterSpacing" | "lineSpacing" | "bgColor" | "bgFillMode" | "bgOpacity" | "bgFit" | "bgTextureFit" | "bgTextureFlipX" | "bgTextureFlipY" | "borderWidth" | "borderRadius" | "padding" | "aspect" | "resolution" | "opacity" | "underline" | "strikethrough" | "bendPreset" | "bendStrength">>;
+export type BuildTextLabelTextureOptions = {
+    text: string;
+    lines?: string[];
+    color: string;
+    strokeLayers?: TextStrokeLayer[];
+    strokeColor?: string;
+    strokeWidth: number;
+    strokeOpacity: number;
+    shadowLayers?: TextShadowLayer[];
+    innerShadow?: TextInnerShadow;
+    glow?: TextGlow;
+    shadowColor?: string;
+    shadowBlur: number;
+    shadowOffsetX: number;
+    shadowOffsetY: number;
+    shadowOpacity: number;
+    fontWeight: "normal" | "bold" | number;
+    fontStyle: "normal" | "italic";
+    fontFamily: string;
+    fontSize: number;
+    textAlign: TextAlign;
+    verticalAlign: TextVerticalAlign;
+    overflow?: TextOverflowMode;
+    resizeToFit?: boolean;
+    minFontSize: number;
+    letterSpacing: number;
+    lineSpacing: number;
+    bgColor: string;
+    bgFillMode: TextBackgroundFillMode;
+    bgOpacity: number;
+    bgFit: TextBackgroundFit;
+    bgAutoSize?: boolean;
+    bgWidth?: number;
+    bgHeight?: number;
+    bgGradientStops?: TextGradientStop[];
+    bgTextureImage?: CanvasImageSource;
+    bgTextureFit: TextBackgroundTextureFit;
+    bgTextureFlipX: boolean;
+    bgTextureFlipY: boolean;
+    borderColor?: string;
+    borderWidth: number;
+    borderRadius: number;
+    padding: number;
+    width: number;
+    height: number;
+    underline: boolean;
+    strikethrough: boolean;
+    bendPreset: TextBendPreset;
+    bendStrength: number;
+};