@vincentt-xr/sdk 2.0.0-alpha.1 → 2.0.0-alpha.3

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,161 +1,2 @@
-export type TextAlign = "left" | "center" | "right";
-export type TextBendPreset = "arc" | "arc-lower" | "arc-upper" | "arch" | "bulge" | "shell-lower" | "shell-upper" | "flag" | "wave" | "fish" | "rise" | "fisheye" | "inflate" | "squeeze" | "twist";
-/**
- * `<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;
-    /** 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?: Array<{
-        color: string;
-        width: number;
-        opacity?: number;
-    }>;
-    /** 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?: Array<{
-        color: string;
-        blur: number;
-        offsetX?: number;
-        offsetY?: number;
-        opacity?: number;
-    }>;
-    /** Optional inner shadow rendered inside the glyphs. */
-    innerShadow?: {
-        color: string;
-        blur: number;
-        offsetX?: number;
-        offsetY?: number;
-        opacity?: number;
-    };
-    /** Optional glow rendered behind the glyphs. */
-    glow?: {
-        color: string;
-        style: "outward" | "contoured";
-        intensity?: number;
-        range?: number;
-        horizontalAngle?: number;
-        verticalAngle?: number;
-    };
-    /** 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;
-    /** Overflow behavior. `clamp` keeps only full visible lines, `clip` allows canvas-edge clipping. */
-    overflow?: "clip" | "clamp" | "ellipsis" | "shrink";
-    /** 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?: "solid" | "gradient";
-    /** Background opacity multiplier. Default 1. */
-    bgOpacity?: number;
-    /** Background fit mode. `full` fills the label rect, `text` hugs the measured text block. */
-    bgFit?: "full" | "text";
-    /** 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?: Array<{
-        color: string;
-        position: number;
-    }>;
-    /** Optional static texture URL when `bgFillMode` is `texture`. */
-    bgTextureUrl?: string;
-    /** Texture fit behavior. Default `cover`. */
-    bgTextureFit?: "cover" | "contain" | "stretch";
-    /** 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 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;
-    /** Draw an underline beneath each rendered line. Default false. */
-    underline?: 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 declare function TextLabel(props: TextLabelProps): import("react/jsx-runtime").JSX.Element;
-export declare function resolveTextLabelDrawX(width: number, padding: number, textAlign: TextAlign): number;
-export declare function resolveTextLabelPanelX(width: number, panelWidth: number, textAlign: TextAlign, bgFit: "full" | "text"): number;
+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;
+};

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

@@ -1,6 +1,18 @@
 import { PropsWithChildren } from 'react';
-import { TrackingTarget } from '../../types/tracking';
+import { FaceCustomAnchorPoint, FaceTarget, TrackingTarget } from '../../types/tracking';
 import * as THREE from "three";
+export type TrackingAnchorSettings = {
+    target: FaceTarget;
+    customAnchorPoint: FaceCustomAnchorPoint;
+    offset: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    smoothing: number;
+    followFaceRoll: boolean;
+};
+export declare const DEFAULT_TRACKING_ANCHOR: TrackingAnchorSettings;
 /**
  * Frame-rate-independent lerp factor for a given smoothing rate and frame
  * delta: `alpha = 1 - e^(-smoothing*dt)`. Same rate produces the same visual
@@ -45,6 +57,8 @@ export type OneEuroState = {
  * each axis independently. On the first sample it seeds without smoothing.
  */
 export declare const stepOneEuro: (state: OneEuroState, sample: THREE.Vector3, dt: number, minCutoff: number, beta: number, dcutoff: number) => OneEuroState;
+/** Apply the SDK's tuned One Euro parameters for a public smoothing value. */
+export declare const stepTrackingSmoothing: (state: OneEuroState, sample: THREE.Vector3, dt: number, smoothing: number) => OneEuroState;
 type TrackingAnchorProps = PropsWithChildren & {
     /**
      * Landmark/joint to attach to. The namespace prefix (`face.`, `hand.`,
@@ -52,6 +66,8 @@ type TrackingAnchorProps = PropsWithChildren & {
      * mismatched anchors render `null` and emit a console warning.
      */
     target: TrackingTarget;
+    /** Face-local point used only when target is `face.custom`. */
+    customAnchorPoint?: FaceCustomAnchorPoint;
     /** Optional offset applied in the tracker's local frame after resolution. */
     offset?: [number, number, number];
     /**
@@ -70,5 +86,5 @@ type TrackingAnchorProps = PropsWithChildren & {
      */
     smoothing?: number;
 };
-export declare const TrackingAnchor: ({ target, offset, smoothing, children, }: TrackingAnchorProps) => import("react/jsx-runtime").JSX.Element | null;
+export declare const TrackingAnchor: ({ target, customAnchorPoint, offset, smoothing, children, }: TrackingAnchorProps) => import("react/jsx-runtime").JSX.Element | null;
 export {};

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

@@ -0,0 +1,30 @@
+import { ReactNode } from 'react';
+import { Group } from 'three';
+export type Transform3DVector = {
+    x: number;
+    y: number;
+    z: number;
+};
+export type Transform3DSettings = {
+    enabled: boolean;
+    linked: {
+        position: boolean;
+        rotation: boolean;
+        scale: boolean;
+    };
+    showTransformControls: boolean;
+    transformControlMode: "translate" | "rotate" | "scale";
+    transformControlSpace: "local" | "world";
+    position: Transform3DVector;
+    rotation: Transform3DVector;
+    scale: Transform3DVector;
+    visible: boolean;
+};
+export type Transform3DProps = {
+    children: ReactNode;
+    objectRef?: (object: Group | null) => void;
+    onChange?: (next: Transform3DSettings) => void;
+    value: Transform3DSettings;
+};
+export declare const DEFAULT_TRANSFORM_3D: Transform3DSettings;
+export declare const Transform3D: ({ children, objectRef, onChange, value }: Transform3DProps) => import("react/jsx-runtime").JSX.Element | null;