@vincentt-xr/sdk 2.0.0-alpha.0

package/dist/components/FaceMesh/material/blendModes.d.ts

@@ -0,0 +1,2 @@
+import { FaceMeshBlendMode } from './types';
+export declare const blendModeIndices: Record<FaceMeshBlendMode, number>;

package/dist/components/FaceMesh/material/defaults.d.ts

@@ -0,0 +1,3 @@
+import { FaceMeshAppearance, FaceMeshMasking } from './types';
+export declare const DEFAULT_APPEARANCE: FaceMeshAppearance;
+export declare const DEFAULT_MASKING: FaceMeshMasking;

package/dist/components/FaceMesh/material/index.d.ts

@@ -0,0 +1,5 @@
+export * from './types';
+export * from './blendModes';
+export * from './defaults';
+export * from './options';
+export * from './support';

package/dist/components/FaceMesh/material/options.d.ts

@@ -0,0 +1,25 @@
+import { FaceMeshAlphaMap, FaceMeshBlendMode, FaceMeshMaterialType, FaceMeshShaderPreset, FaceMeshSide, FaceMeshTextureMap } from './types';
+export declare const materialTypeOptions: Array<{
+    label: string;
+    value: FaceMeshMaterialType;
+}>;
+export declare const shaderPresetOptions: Array<{
+    label: string;
+    value: FaceMeshShaderPreset;
+}>;
+export declare const sideOptions: Array<{
+    label: string;
+    value: FaceMeshSide;
+}>;
+export declare const textureMapOptions: Array<{
+    label: string;
+    value: FaceMeshTextureMap;
+}>;
+export declare const alphaMapOptions: Array<{
+    label: string;
+    value: FaceMeshAlphaMap;
+}>;
+export declare const blendModeOptions: Array<{
+    label: string;
+    value: FaceMeshBlendMode;
+}>;

package/dist/components/FaceMesh/material/support.d.ts

@@ -0,0 +1,3 @@
+import { FaceMeshMaterialType, FaceMeshShaderPreset } from './types';
+export declare const supportsTexturePanel: (materialType: FaceMeshMaterialType, shaderPreset: FaceMeshShaderPreset) => boolean;
+export declare const supportsBlendMode: (materialType: FaceMeshMaterialType, shaderPreset: FaceMeshShaderPreset) => boolean;

package/dist/components/FaceMesh/material/types.d.ts

@@ -0,0 +1,23 @@
+export type FaceMeshMaterialType = "basic" | "standard" | "physical" | "toon" | "normal" | "matcap" | "wireframe" | "shader";
+export type FaceMeshShaderPreset = "basicShader" | "originalFace" | "composite";
+export type FaceMeshTextureMap = "none" | "canonical" | "style2";
+export type FaceMeshAlphaMap = "none" | "canonical";
+export type FaceMeshMaskTextureSource = "none" | "canonical";
+export type FaceMeshSide = "front" | "back" | "double";
+export type FaceMeshBlendMode = "normal" | "add" | "subtract" | "multiply" | "screen" | "overlay" | "softLight" | "hardLight" | "lighten" | "darken" | "difference" | "exclusion";
+export type FaceMeshAppearance = {
+    materialType: FaceMeshMaterialType;
+    shaderPreset: FaceMeshShaderPreset;
+    textureMap: FaceMeshTextureMap;
+    alphaMap: FaceMeshAlphaMap;
+    alphaOpacity: number;
+    side: FaceMeshSide;
+    blendMode: FaceMeshBlendMode;
+    baseColor: string;
+    opacity: number;
+};
+export type FaceMeshMasking = {
+    mouth: boolean;
+    eyes: boolean;
+    nose: boolean;
+};

package/dist/components/FaceMesh/uv.d.ts

@@ -0,0 +1 @@
+export declare const FACE_MESH_UV: number[];

package/dist/components/FaceRetouch/Background.d.ts

@@ -0,0 +1,16 @@
+import * as THREE from "three";
+export type FaceRetouchBackgroundProps = {
+    retouchMask: THREE.Texture;
+    mouthMask: THREE.Texture;
+    retouchAmount: number;
+    blurRadius: number;
+    teethWhitening: number;
+    previewMask: boolean;
+    protectLandmarks: boolean;
+};
+/**
+ * Full-screen plane that composites the live camera texture with a
+ * landmark-driven retouch (skin smoothing + teeth whitening). Pair with
+ * `useFaceRetouchMask` to drive the masks.
+ */
+export declare const FaceRetouchBackground: ({ retouchMask, mouthMask, retouchAmount, blurRadius, teethWhitening, previewMask, protectLandmarks, }: FaceRetouchBackgroundProps) => import("react/jsx-runtime").JSX.Element | null;

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

@@ -0,0 +1,6 @@
+export { FaceRetouchBackground } from './Background';
+export type { FaceRetouchBackgroundProps } from './Background';
+export { drawFaceRetouchMask, drawMouthRetouchMask, FACE_MASK_SIZE, FACE_OVAL, LEFT_EYE, RIGHT_EYE, OUTER_LIPS, INNER_MOUTH, LEFT_EYEBROW, RIGHT_EYEBROW, } from './landmarkMask';
+export { createFaceRetouchRegions, DEFAULT_FEATURE_GROUPS, DEFAULT_FEATURE_POINT_INDICES, type CreateFaceRetouchRegionsOptions, } from './retouchRegions';
+export { useFaceRetouchMask } from './useFaceRetouchMask';
+export { useFaceRetouchRegions } from './useFaceRetouchRegions';

package/dist/components/FaceRetouch/landmarkMask.d.ts

@@ -0,0 +1,23 @@
+import { FaceLandmark2D } from '../../types/face';
+export declare const FACE_MASK_SIZE = 512;
+export declare const FACE_OVAL: number[];
+export declare const LEFT_EYE: number[];
+export declare const RIGHT_EYE: number[];
+export declare const OUTER_LIPS: number[];
+export declare const INNER_MOUTH: number[];
+export declare const LEFT_EYEBROW: number[];
+export declare const RIGHT_EYEBROW: number[];
+/**
+ * Render the three-channel face retouch mask used by FaceRetouchBackground:
+ *   - R: blurred face oval (soft retouch region)
+ *   - G: blurred feature polygons (protected: eyes, brows, lips, nose)
+ *   - B: hard face oval (clamping mask)
+ *
+ * `size` defaults to FACE_MASK_SIZE (512). The context must be sized to match.
+ */
+export declare const drawFaceRetouchMask: (context: CanvasRenderingContext2D, landmarks: FaceLandmark2D[] | undefined, size?: number) => void;
+/**
+ * Render a single-channel mouth mask (inner-lip polygon, lightly blurred).
+ * Used for teeth-whitening regions.
+ */
+export declare const drawMouthRetouchMask: (context: CanvasRenderingContext2D, landmarks: FaceLandmark2D[] | undefined, size?: number) => void;

package/dist/components/FaceRetouch/retouchRegions.d.ts

@@ -0,0 +1,23 @@
+import { FaceLandmark2D, FaceRetouchRegion } from '../../types/face';
+export declare const DEFAULT_FEATURE_GROUPS: number[][];
+export declare const DEFAULT_FEATURE_POINT_INDICES: number[];
+export type CreateFaceRetouchRegionsOptions = {
+    faceOvalIndices?: number[];
+    featureGroups?: number[][];
+    featurePointIndices?: number[];
+    faceBoundsExpansion?: number;
+    featureBoundsExpansion?: number;
+    minRegionRadius?: number;
+    faceRegionStrength?: number;
+    featureRegionStrength?: number;
+    featurePointRegionStrength?: number;
+    featurePointRadiusRatio?: number;
+};
+/**
+ * Compute elliptical retouch regions from MediaPipe face landmarks.
+ *
+ * The defaults match the V2 face-retouch demo. Override `featureGroups`
+ * or `featurePointIndices` to retouch a different anatomy (or a different
+ * landmark model).
+ */
+export declare const createFaceRetouchRegions: (landmarks: FaceLandmark2D[] | undefined, options?: CreateFaceRetouchRegionsOptions) => FaceRetouchRegion[];

package/dist/components/FaceRetouch/useFaceRetouchMask.d.ts

@@ -0,0 +1,14 @@
+import { XRModelNodeFaceTracking } from '../../types/nodes';
+import * as THREE from "three";
+/**
+ * Drive the two CanvasTexture masks consumed by `FaceRetouchBackground`
+ * from the latest face landmarks. Re-rendered on requestAnimationFrame.
+ *
+ * `size` controls the mask resolution (default 512). Both masks share the
+ * same size.
+ */
+export declare const useFaceRetouchMask: (faceNode: XRModelNodeFaceTracking | null, size?: number) => {
+    canvas: HTMLCanvasElement;
+    texture: THREE.CanvasTexture;
+    mouthTexture: THREE.CanvasTexture;
+};

package/dist/components/FaceRetouch/useFaceRetouchRegions.d.ts

@@ -0,0 +1,12 @@
+import { FaceRetouchRegion } from '../../types/face';
+import { XRModelNodeFaceTracking } from '../../types/nodes';
+import { CreateFaceRetouchRegionsOptions } from './retouchRegions';
+/**
+ * Continuously recompute face-retouch regions from the active face's
+ * landmarks. Returns a stable array reference when the regions haven't
+ * meaningfully changed (4-decimal precision).
+ *
+ * Pass `options` to retouch a different anatomy or landmark model — see
+ * `createFaceRetouchRegions`.
+ */
+export declare const useFaceRetouchRegions: (faceNode: XRModelNodeFaceTracking | null, options?: CreateFaceRetouchRegionsOptions) => FaceRetouchRegion[];

package/dist/components/FaceTracker/BoundingBoxOverlay.d.ts

@@ -0,0 +1,20 @@
+import { CSSProperties } from 'react';
+import { BoundingBox } from '../../types/face';
+export type BoundingBoxOverlayProps = {
+    /** Normalized 0..1 bounding box, e.g. from `useFaceBoundingBox`. */
+    boundingBox: BoundingBox;
+    /** Optional label rendered above the box. Pass `null` to hide. Default: "face bounding box". */
+    label?: string | null;
+    /** Border color. Default: tailwind green-500. */
+    color?: string;
+    /** Override the rendered <div> style (merges over defaults). */
+    style?: CSSProperties;
+    /** Override the label <div> style (merges over defaults). */
+    labelStyle?: CSSProperties;
+};
+/**
+ * Absolutely-positioned DOM overlay for a normalized bounding box.
+ * Render this inside a relatively-positioned container that mirrors the
+ * camera feed dimensions.
+ */
+export declare const BoundingBoxOverlay: ({ boundingBox, label, color, style, labelStyle, }: BoundingBoxOverlayProps) => import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,54 @@
+import { PropsWithChildren } from 'react';
+import { FaceMesh } from '../FaceMesh';
+type FaceTrackerProps = PropsWithChildren & {
+    /** Index of the face to bind to in the face-tracking model's results. */
+    faceIndex?: number;
+    /**
+     * Maximum number of faces the shared face-tracking model should detect.
+     * The first mounted face-tracking consumer initializes the shared model,
+     * so multi-face scenes should pass the same value to every binding.
+     */
+    numFaces?: number;
+    /**
+     * When `true`, children are also scaled by the detected face's
+     * cheek-to-cheek extent (face-normalized units, ~0.13 world units per
+     * authored unit). Useful for filters and jewellery that should resize
+     * with the face. Default `false` so that 1×1 author units stay 1×1
+     * world units — preserves WYSIWYG with the design editor.
+     */
+    scaleWithFace?: boolean;
+    /**
+     * Cap this tracker's inference rate (fps). Overrides the session-level
+     * `perf.targetFps`. Lower = cooler, less smooth. Omit to inherit the session
+     * default (or uncapped). The first mounted face consumer wins, mirroring
+     * `numFaces`.
+     */
+    targetFps?: number;
+    /**
+     * Whether this tracker should run. `false` pauses the shared model's
+     * per-frame inference (and its expensive GPU→CPU readback) while keeping it
+     * mounted and initialized, so gating it off-scene costs nothing yet flipping
+     * back to `true` resumes instantly — no unmount, no registry re-acquire race.
+     * When several trackers share the model, it runs while any is active.
+     * Defaults to `true`.
+     */
+    active?: boolean;
+};
+declare const FaceTrackerComponent: ({ faceIndex, numFaces, scaleWithFace, targetFps, active, children, }: FaceTrackerProps) => import("react/jsx-runtime").JSX.Element;
+/**
+ * Face mesh sub-component. Renders the deforming MediaPipe face mesh
+ * for the parent `FaceTracker`'s face index. Replaces the legacy
+ * `FaceMesh` top-level component.
+ *
+ * Implementation delegates to the existing `FaceMesh` component, which
+ * already handles geometry updates per frame and material composition.
+ */
+declare const FaceTrackerMesh: typeof FaceMesh;
+export declare const FaceTracker: typeof FaceTrackerComponent & {
+    Mesh: typeof FaceTrackerMesh;
+};
+export declare const HeadTracker: (({ faceIndex, numFaces, scaleWithFace, targetFps, active, children, }: FaceTrackerProps) => import("react/jsx-runtime").JSX.Element) & {
+    Mesh: typeof FaceTrackerMesh;
+};
+export { BoundingBoxOverlay } from './BoundingBoxOverlay';
+export type { BoundingBoxOverlayProps } from './BoundingBoxOverlay';

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

@@ -0,0 +1,31 @@
+import { PropsWithChildren } from 'react';
+type GestureTrackerProps = PropsWithChildren & {
+    /** Hand index in detection results. Defaults to 0. */
+    handIndex?: number;
+    /**
+     * Cap this tracker's inference rate (fps). Overrides the session-level
+     * `perf.targetFps` and the gesture model's 15fps default. Lower = cooler.
+     */
+    targetFps?: number;
+    /**
+     * Whether this tracker should run. `false` pauses the shared model's
+     * per-frame inference (and its expensive GPU→CPU readback) while keeping it
+     * mounted and initialized, so gating it off-scene costs nothing yet flipping
+     * back to `true` resumes instantly — no unmount, no registry re-acquire race.
+     * When several trackers share the model, it runs while any is active.
+     * Defaults to `true`.
+     */
+    active?: boolean;
+};
+/**
+ * Declarative wrapper around the gesture-tracking model. Mounting this
+ * acquires the model for as long as the component is mounted; consumers
+ * can read `context.xr.session.getModelNode(XRModel.GESTURE_TRACKER)` in
+ * scene scripts without calling `registerXRPipeline` themselves.
+ *
+ * Mirrors `<HandTracker>` semantics — children inherit the wrist
+ * transform — but binds to the gesture recognizer so the node also
+ * exposes `.gesture` (e.g. `"victory"`, `"pointing_up"`).
+ */
+export declare const GestureTracker: ({ children, targetFps, active }: GestureTrackerProps) => import("react/jsx-runtime").JSX.Element;
+export {};

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

@@ -0,0 +1,3 @@
+import { UseGestureEdgeOptions } from '../../hooks/useGestureEdge';
+export type GestureTriggerProps = UseGestureEdgeOptions;
+export declare const GestureTrigger: (props: GestureTriggerProps) => null;

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

@@ -0,0 +1,24 @@
+import { PropsWithChildren } from 'react';
+type HandTrackerProps = PropsWithChildren & {
+    /** Which hand to bind to. Currently informational — the model tracks one hand. */
+    hand?: "left" | "right";
+    /** Hand index in detection results. Defaults to 0. */
+    handIndex?: number;
+    /**
+     * Cap this tracker's inference rate (fps). Overrides the session-level
+     * `perf.targetFps`. Lower = cooler, less smooth. Omit to inherit the session
+     * default (or uncapped).
+     */
+    targetFps?: number;
+    /**
+     * Whether this tracker should run. `false` pauses the shared model's
+     * per-frame inference (and its expensive GPU→CPU readback) while keeping it
+     * mounted and initialized, so gating it off-scene costs nothing yet flipping
+     * back to `true` resumes instantly — no unmount, no registry re-acquire race.
+     * When several trackers share the model, it runs while any is active.
+     * Defaults to `true`.
+     */
+    active?: boolean;
+};
+export declare const HandTracker: ({ children, targetFps, active }: HandTrackerProps) => import("react/jsx-runtime").JSX.Element;
+export {};

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

@@ -0,0 +1,31 @@
+import { PropsWithChildren } from 'react';
+import * as THREE from "three";
+export type HeadBindingOccluderOptions = {
+    position?: [number, number, number];
+    rotation?: [number, number, number];
+    scale?: [number, number, number];
+    url?: string;
+    showDebugMaterial?: boolean;
+    opacity?: number;
+};
+export type HeadBindingProps = PropsWithChildren & {
+    /** Face index from the shared face-tracking result to bind this subtree to. */
+    faceIndex?: number;
+    /**
+     * Maximum number of faces the shared tracker should detect. Defaults to 4
+     * so multiple `<HeadBinding faceIndex={...}>` instances work out of the box.
+     * Use `numFaces={1}` for single-face experiences that need maximum speed.
+     */
+    numFaces?: number;
+    /**
+     * Optional face-relative scaling. Enabled by default because head occlusion
+     * must follow the detected face size rather than raw world units.
+     */
+    scaleWithFace?: boolean;
+    /** Render the depth-only head mesh that lets 3D children pass behind the head. */
+    occluder?: boolean | HeadBindingOccluderOptions;
+    /** Optional debug face mesh for calibration and authoring. */
+    showFaceMesh?: boolean;
+    faceMeshMaterial?: THREE.Material;
+};
+export declare const HeadBinding: ({ children, faceIndex, numFaces, scaleWithFace, occluder, showFaceMesh, faceMeshMaterial, }: HeadBindingProps) => import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,36 @@
+import { FaceTrackingResult } from '../../types/face';
+import { HeadBindingCubeModel, HeadBindingCubePose } from '../../types/headBinding';
+type HeadBindingOccluderProps = {
+    boxColor: string;
+    boxOpacity: number;
+    face: FaceTrackingResult | null;
+    headDepthOffset: number;
+    lockDepth: boolean;
+    lockRotation: boolean;
+    model: HeadBindingCubeModel;
+    occluderOffset: [number, number, number];
+    occluderOpacity: number;
+    occluderScale: [number, number, number];
+    showOccluderProxy?: boolean;
+    offsetX: number;
+    offsetY: number;
+    pose?: HeadBindingCubePose | null;
+    rotationOffsetX: number;
+    rotationOffsetY: number;
+    rotationOffsetZ: number;
+    scaleX: number;
+    scaleY: number;
+    scaleZ: number;
+    show: boolean;
+    showCenterDot: boolean;
+    showFacePlaneReference: boolean;
+    showGizmo: boolean;
+    showHeadOccluder: boolean;
+    skullCenterMode: boolean;
+    skullVerticalBias: number;
+    url?: string;
+    viewportHeight: number;
+    viewportWidth: number;
+};
+export declare const HeadBindingOccluder: ({ boxColor, boxOpacity, face, headDepthOffset, lockDepth, lockRotation, model, occluderOffset, occluderOpacity, occluderScale, showOccluderProxy, offsetX, offsetY, pose: solvedPose, rotationOffsetX, rotationOffsetY, rotationOffsetZ, scaleX, scaleY, scaleZ, show, showCenterDot, showFacePlaneReference, showGizmo, showHeadOccluder, skullCenterMode, skullVerticalBias, url, viewportHeight, viewportWidth, }: HeadBindingOccluderProps) => import("react/jsx-runtime").JSX.Element | null;
+export {};

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

@@ -0,0 +1,13 @@
+type HeadOccluderProps = {
+    position?: [number, number, number];
+    rotation?: [number, number, number];
+    scale?: [number, number, number];
+    url?: string;
+    showDebugMaterial?: boolean;
+    opacity?: number;
+};
+export declare const HEAD_OCCLUDER_DEFAULT_POSITION: [number, number, number];
+export declare const HEAD_OCCLUDER_DEFAULT_SCALE: [number, number, number];
+export declare const HEAD_OCCLUDER_DEFAULT_OPACITY = 1;
+export declare const HeadOccluder: ({ position: modelPosition, rotation: modelRotation, scale: modelScale, url, showDebugMaterial, opacity, }: HeadOccluderProps) => import("react/jsx-runtime").JSX.Element | null;
+export {};

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

@@ -0,0 +1,71 @@
+import * as THREE from "three";
+/**
+ * `<Panel>` — a rounded, colored, optionally outlined rectangle rendered as
+ * a single textured mesh. A first-class scene-tree primitive so lifecycle
+ * scripts don't have to hand-paint canvas textures for cosmetic surfaces.
+ *
+ * The mesh is sized 1×1 in world units by default; place / size it through
+ * the parent (`scale` on the JSX node, or anchored inside a
+ * `<ScreenTransform>` / `<TrackingAnchor>`).
+ *
+ * Rendering: a single `MeshBasicMaterial` with a procedurally drawn
+ * `CanvasTexture`. The texture is rebuilt only when one of the visual
+ * props changes, never per frame.
+ */
+export type PanelProps = {
+    /** Fill color. CSS color string. Default `rgba(20,40,110,0.88)`. */
+    color?: string;
+    /** Optional border color. Omit for no border. */
+    borderColor?: string;
+    /** Border thickness, in canvas px. Ignored when `borderColor` is unset. Default 0. */
+    borderWidth?: number;
+    /**
+     * Corner radius, in canvas px. Use 0 for a square panel. Default 24.
+     * Note: the texture canvas is fixed at ~512×512 px; visual radius scales
+     * with the mesh's world size.
+     */
+    borderRadius?: number;
+    /**
+     * Internal canvas size (px). Larger = crisper at the cost of GPU memory.
+     * 512 is plenty for most cosmetic panels. Default 512.
+     */
+    resolution?: number;
+    /**
+     * Aspect ratio of the panel's content area (width / height). The mesh
+     * itself is always 1×1; this controls how the texture is drawn so that
+     * the corner radius reads correctly when the panel is non-square.
+     * Default 1 (square).
+     */
+    aspect?: number;
+    /** Material opacity multiplier. Default 1. */
+    opacity?: number;
+    /** Optional `name` for runtime `getObjectByName` lookups. */
+    name?: string;
+    /**
+     * When true, the panel ignores depth — appropriate for overlay UI.
+     * Default true (matches the common ScreenSpaceUI use case).
+     */
+    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 Panel({ color, borderColor, borderWidth, borderRadius, resolution, aspect, opacity, name, overlay, position, rotation, scale, visible, }: PanelProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Internal: draw a rounded rect with optional stroke into an offscreen
+ * canvas and wrap it as a CanvasTexture. Exported for `<TextLabel>` to
+ * reuse the same drawing path.
+ */
+export declare function buildPanelTexture(opts: {
+    width: number;
+    height: number;
+    color: string;
+    borderColor?: string;
+    borderWidth: number;
+    borderRadius: number;
+}): THREE.CanvasTexture;

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

@@ -0,0 +1,14 @@
+import { PerspectiveCameraProps } from '@react-three/fiber';
+/**
+ * @deprecated Use @react-three/drei's PerspectiveCamera directly for the new unified architecture.
+ * This component is kept for backwards compatibility with old examples.
+ *
+ * For new projects, use:
+ * ```tsx
+ * import { PerspectiveCamera } from '@react-three/drei';
+ * <PerspectiveCamera makeDefault position={[0, 0, 5]} fov={45} />
+ * ```
+ */
+export declare const PerspectiveCamera: (props: PerspectiveCameraProps & {
+    makeDefault?: boolean;
+}) => import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,54 @@
+import { ReactNode } from 'react';
+export type ScreenAnchorEdges = {
+    left?: number;
+    right?: number;
+    top?: number;
+    bottom?: number;
+};
+export type ScreenOffsetEdges = {
+    left?: number;
+    right?: number;
+    top?: number;
+    bottom?: number;
+};
+export type ScreenTransformProps = {
+    /**
+     * Per-edge anchors normalized to [-1, 1]. -1 = parent's left/bottom edge,
+     * +1 = parent's right/top edge. When `left !== right` or `top !== bottom`
+     * the element stretches between the anchor positions.
+     * @default { left: 0, right: 0, top: 0, bottom: 0 }
+     */
+    anchors?: ScreenAnchorEdges;
+    /**
+     * Per-edge offsets in world units. Each offset is applied as inward
+     * padding from the corresponding anchor position.
+     * @default { left: 0, right: 0, top: 0, bottom: 0 }
+     */
+    offsets?: ScreenOffsetEdges;
+    /**
+     * Pivot in normalized local space ([-1, 1] per axis). Used as the
+     * (0, 0) point for children and as the rotation center.
+     * @default [0, 0]
+     */
+    pivot?: [number, number];
+    children?: ReactNode;
+};
+export type ResolvedScreenTransform = {
+    centerX: number;
+    centerY: number;
+    width: number;
+    height: number;
+    pivotX: number;
+    pivotY: number;
+};
+/**
+ * Pure layout math for `ScreenTransform`. Exported for unit testing
+ * and for the editor's anchor picker preview.
+ */
+export declare const computeScreenTransform: (parentWidth: number, parentHeight: number, anchors: Required<ScreenAnchorEdges>, offsets: Required<ScreenOffsetEdges>, pivot: [number, number]) => ResolvedScreenTransform;
+/**
+ * `ScreenTransform` lays out its children inside a `ScreenSpaceUI`
+ * parent using normalized anchors + per-edge offsets. The element
+ * stretches between opposing anchors when they differ.
+ */
+export declare const ScreenTransform: ({ anchors, offsets, pivot, children, }: ScreenTransformProps) => import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,29 @@
+export type ScreenDimensions = {
+    width: number;
+    height: number;
+};
+export declare const ScreenSpaceContext: import('react').Context<ScreenDimensions | null>;
+export declare const useScreenSpace: () => ScreenDimensions;
+/**
+ * Published by `ScreenTransform` so descendants (specifically the xr-client
+ * renderer applying `mapFit: "contain"`) know the rendered width/height
+ * aspect of the enclosing rect. The v2 fit mechanism multiplies a
+ * contain-scale factor into the mesh's scale using this aspect as the
+ * "rect aspect" input to `computeContainScale`.
+ *
+ * `null` outside a ScreenTransform — the renderer uses the null sentinel
+ * to detect the out-of-context case and skip fit with a warning (rect is
+ * ambiguous without a ScreenTransform). Consumers that just want the
+ * aspect for layout can use `useScreenRectAspect()` which maps `null` → 1.
+ */
+export declare const ScreenRectAspectContext: import('react').Context<number | null>;
+/**
+ * Returns the rendered aspect ratio (width / height) of the nearest
+ * enclosing `ScreenTransform`, or `1` when no ScreenTransform is above.
+ *
+ * Consumers that need to distinguish "no ScreenTransform above me" from
+ * "rect aspect is 1" (specifically the renderer's `mapFit: "contain"` path)
+ * should read `ScreenRectAspectContext` directly with `useContext` so they
+ * see the `null` sentinel.
+ */
+export declare const useScreenRectAspect: () => number;

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

@@ -0,0 +1,40 @@
+import { ReactNode } from 'react';
+import { useScreenSpace, useScreenRectAspect, ScreenRectAspectContext, ScreenDimensions } from './context';
+export { useScreenSpace, useScreenRectAspect, ScreenRectAspectContext };
+export type { ScreenDimensions };
+export type ScreenSpaceUIProps = {
+    /**
+     * Child components to render in screen space.
+     * Use useScreenSpace() hook to access screen dimensions.
+     */
+    children: ReactNode;
+    /**
+     * Z position of the screen plane.
+     * Default: 0 (at the camera's focal plane)
+     */
+    depth?: number;
+};
+/**
+ * ScreenSpaceUI provides a container for 2D UI elements that maintain
+ * consistent screen-space positioning regardless of camera movement.
+ *
+ * Children must be `ScreenTransform` nodes, which express normalized-anchor +
+ * edge-offset layouts (corners, edges, full-width bands, fill, …). The editor
+ * exposes the common cases as `AnchorPicker` presets.
+ *
+ * @example
+ * ```tsx
+ * <ScreenSpaceUI>
+ *   <ScreenTransform
+ *     anchors={{ left: -1, right: 1, top: -0.7, bottom: -1 }}
+ *     offsets={{ left: 0.1, right: 0.1, top: 0, bottom: 0.1 }}
+ *   >
+ *     <FullWidthBanner />
+ *   </ScreenTransform>
+ * </ScreenSpaceUI>
+ * ```
+ */
+export declare const ScreenSpaceUI: ({ children, depth }: ScreenSpaceUIProps) => import("react/jsx-runtime").JSX.Element;
+export { ScreenTransform } from './ScreenTransform';
+export type { ScreenTransformProps, ScreenAnchorEdges, ScreenOffsetEdges, ResolvedScreenTransform, } from './ScreenTransform';
+export { computeScreenTransform } from './ScreenTransform';