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

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

@@ -0,0 +1,5 @@
+import { DEFAULT_SCREEN_GRADIENT, MAX_SCREEN_GRADIENT_STOPS, normalizeScreenGradient, normalizeScreenGradientStops } from './defaults';
+import { ScreenGradientMaterialProps } from './types';
+export type { ScreenGradientMaterialProps, ScreenGradientSettings, ScreenGradientStop, ScreenGradientType, } from './types';
+export { DEFAULT_SCREEN_GRADIENT, MAX_SCREEN_GRADIENT_STOPS, normalizeScreenGradient, normalizeScreenGradientStops, };
+export declare const ScreenGradientMaterial: ({ opacity, value }: ScreenGradientMaterialProps) => import("react/jsx-runtime").JSX.Element;

package/dist/components/ScreenGradient/shaders.d.ts

@@ -0,0 +1,2 @@
+export declare const screenGradientVertexShader = "\n  varying vec2 vPosition;\n  void main() {\n    vPosition = position.xy;\n    gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);\n  }\n";
+export declare const screenGradientFragmentShader = "\n  #define MAX_STOPS 8\n  uniform vec3 stopColors[MAX_STOPS];\n  uniform float stopOffsets[MAX_STOPS];\n  uniform int stopCount;\n  uniform int gradientType;\n  uniform vec2 direction;\n  uniform vec2 center;\n  uniform float radius;\n  uniform float angleOffset;\n  uniform float opacity;\n  varying vec2 vPosition;\n\n  vec3 sampleGradient(float amount) {\n    vec3 color = stopColors[0];\n    for (int index = 1; index < MAX_STOPS; index++) {\n      if (index >= stopCount) break;\n      if (amount <= stopOffsets[index]) {\n        float width = max(0.0001, stopOffsets[index] - stopOffsets[index - 1]);\n        return mix(stopColors[index - 1], stopColors[index], clamp((amount - stopOffsets[index - 1]) / width, 0.0, 1.0));\n      }\n      color = stopColors[index];\n    }\n    return color;\n  }\n\n  void main() {\n    vec2 delta = vPosition - center;\n    float amount;\n    if (gradientType == 1) {\n      amount = clamp(length(delta) / radius, 0.0, 1.0);\n    } else if (gradientType == 2) {\n      amount = fract(atan(delta.y, delta.x) / 6.28318530718 + 0.5 + angleOffset);\n    } else {\n      amount = clamp(dot(delta, direction) + 0.5, 0.0, 1.0);\n    }\n    gl_FragColor = vec4(sampleGradient(amount), opacity);\n  }\n";

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

@@ -0,0 +1,19 @@
+export type ScreenGradientType = "linear" | "radial" | "angular";
+export type ScreenGradientStop = {
+    offset: number;
+    color: string;
+};
+export type ScreenGradientSettings = {
+    type: ScreenGradientType;
+    stops: ScreenGradientStop[];
+    angle: number;
+    center: {
+        x: number;
+        y: number;
+    };
+    radius: number;
+};
+export type ScreenGradientMaterialProps = {
+    value: ScreenGradientSettings;
+    opacity?: number;
+};

package/dist/components/ScreenImage/ScreenImage.d.ts

@@ -0,0 +1,4 @@
+import { default as defaultScreenImageUrl } from './assets/Default_square_image.png';
+import { ScreenImageProps } from './types';
+export declare function ScreenImage({ anchors, coordinateSpace, canvasSize, position, size, offsets, pivot, rotation, transform, onScreenTransformChange, transformGuideLayer, ...bodyProps }: ScreenImageProps): import("react/jsx-runtime").JSX.Element | null;
+export { defaultScreenImageUrl };

package/dist/components/ScreenImage/components/DynamicTextureSync.d.ts

@@ -0,0 +1,9 @@
+import type * as THREE from "three";
+export declare function DynamicTextureSync({ materialTexture, sourceTexture, onSourceSizeChange, }: {
+    materialTexture: THREE.Texture;
+    sourceTexture: THREE.Texture;
+    onSourceSizeChange: (size: {
+        width: number;
+        height: number;
+    }) => void;
+}): null;

package/dist/components/ScreenImage/components/ScreenImageBody.d.ts

@@ -0,0 +1,9 @@
+import { ScreenImageProps } from '../types';
+type ScreenImageBodyProps = Omit<ScreenImageProps, "anchors" | "coordinateSpace" | "canvasSize" | "position" | "size" | "offsets" | "pivot" | "transform"> & {
+    layoutSize?: {
+        width: number;
+        height: number;
+    };
+};
+export declare function ScreenImageBody({ name, source, src, fit, stretchMode, materialType, blendMode, backdropTexture: providedBackdropTexture, rotation, opacity, color, maskTexture, maskChannel, maskInvert, maskFeather, maskErode, flipX, flipY, renderOrder, transparent, alphaTest, overlay, visible, layoutSize, }: ScreenImageBodyProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/ScreenImage/components/ScreenImageFrame.d.ts

@@ -0,0 +1,9 @@
+import { ReactNode } from 'react';
+import { ScreenAnchorEdges, ScreenOffsetEdges } from '../../ScreenSpaceUI';
+export declare function ScreenImageFrame({ anchors, offsets, pivot, rotation, children, }: {
+    anchors: ScreenAnchorEdges;
+    offsets: ScreenOffsetEdges;
+    pivot: [number, number];
+    rotation: number;
+    children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/components/ScreenImage/components/ScreenImageTransformFrame.d.ts

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

package/dist/components/ScreenImage/fit.d.ts

@@ -0,0 +1,52 @@
+export type ScreenImageFit = "stretch" | "contain" | "cover";
+export type ScreenImageStretchMode = "fit" | "fitWidth" | "fitHeight" | "center" | "stretch" | "fill" | "fillAndCut";
+export type ScreenImageFittedRectInput = {
+    rectSize: {
+        width: number;
+        height: number;
+    };
+    textureSize?: {
+        width: number;
+        height: number;
+    };
+    textureAspect?: number;
+    stretchMode?: ScreenImageStretchMode;
+    fit?: ScreenImageFit;
+    flipX?: boolean;
+    flipY?: boolean;
+};
+export type ScreenImageFittedRect = {
+    rectAspect: number;
+    textureAspect: number;
+    scale: {
+        x: number;
+        y: number;
+    };
+    size: {
+        width: number;
+        height: number;
+    };
+    uvRepeat: {
+        x: number;
+        y: number;
+    };
+    uvOffset: {
+        x: number;
+        y: number;
+    };
+};
+export type ScreenImageFitResolution = {
+    meshScale: [number, number, number];
+    guideScale: [number, number, number];
+    repeat: [number, number];
+    offset: [number, number];
+};
+export declare const resolveScreenImageStretchMode: (stretchMode: ScreenImageStretchMode | undefined, fit: ScreenImageFit | undefined) => ScreenImageStretchMode;
+export declare const computeScreenImageFitResolution: (stretchMode: ScreenImageStretchMode, rectAspect: number, textureAspect: number, flipX: boolean, flipY: boolean, rectSize?: {
+    width: number;
+    height: number;
+}, textureSize?: {
+    width: number;
+    height: number;
+}) => ScreenImageFitResolution;
+export declare const computeScreenImageFittedRect: ({ rectSize, textureSize, textureAspect: providedTextureAspect, stretchMode, fit, flipX, flipY, }: ScreenImageFittedRectInput) => ScreenImageFittedRect;

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

@@ -0,0 +1,10 @@
+export { ScreenImage, defaultScreenImageUrl } from './ScreenImage';
+export { screenImageBlendModeOptions } from './utils/ScreenImageConstants';
+export { resolveBlendProps } from './materials/ScreenImageBlendMaterial';
+export { SCREEN_IMAGE_MASK_CHANNELS, resolveMaskChannelIndex, } from './materials/ScreenImageMaskMaterial';
+export type { ScreenImageMaskChannel } from './materials/ScreenImageMaskMaterial';
+export type { ScreenImageBlendMode, ScreenImageMaterialType, ScreenImageProps } from './types';
+export type { ScreenImageSource } from './source';
+export { getScreenImageTextureAspect, getScreenImageTextureSize, isDynamicScreenImageTexture, resolveScreenImageSource, } from './source';
+export { computeScreenImageFitResolution, computeScreenImageFittedRect, resolveScreenImageStretchMode, } from './fit';
+export type { ScreenImageFit, ScreenImageFittedRect, ScreenImageFittedRectInput, ScreenImageStretchMode, } from './fit';

package/dist/components/ScreenImage/materials/ScreenImageBlendMaterial.d.ts

@@ -0,0 +1,9 @@
+import { ScreenImageBlendMode } from '../types';
+import * as THREE from "three";
+export declare const ADVANCED_BLEND_MODES: Set<ScreenImageBlendMode>;
+export type AdvancedBlendMode = Extract<ScreenImageBlendMode, "overlay" | "softLight" | "hardLight" | "difference" | "exclusion">;
+export declare const advancedBlendModeIndices: Record<AdvancedBlendMode, number>;
+export type BlendMaterialProps = Partial<Pick<THREE.Material, "blending" | "blendSrc" | "blendDst" | "blendEquation">>;
+export declare const resolveBlendProps: (mode: ScreenImageBlendMode) => BlendMaterialProps;
+export declare const advancedBlendVertexShader = "\nvarying vec2 vUv;\nvoid main(){vUv=uv;gl_Position=projectionMatrix*modelViewMatrix*vec4(position,1.0);}";
+export declare const advancedBlendFragmentShader = "\nuniform sampler2D imageMap;uniform sampler2D backdropMap;uniform vec2 resolution;\nuniform vec3 tint;uniform float opacity;uniform float alphaTest;uniform int blendMode;varying vec2 vUv;\nfloat overlayChannel(float b,float s){return b<.5?2.*b*s:1.-2.*(1.-b)*(1.-s);}\nfloat hardLightChannel(float b,float s){return s<.5?2.*b*s:1.-2.*(1.-b)*(1.-s);}\nfloat softLightChannel(float b,float s){return s<.5?b-(1.-2.*s)*b*(1.-b):b+(2.*s-1.)*(sqrt(max(b,0.))-b);}\nvec3 applyAdvancedBlend(vec3 b,vec3 s){\nif(blendMode==0)return vec3(overlayChannel(b.r,s.r),overlayChannel(b.g,s.g),overlayChannel(b.b,s.b));\nif(blendMode==1)return vec3(softLightChannel(b.r,s.r),softLightChannel(b.g,s.g),softLightChannel(b.b,s.b));\nif(blendMode==2)return vec3(hardLightChannel(b.r,s.r),hardLightChannel(b.g,s.g),hardLightChannel(b.b,s.b));\nif(blendMode==3)return abs(b-s);return b+s-2.*b*s;}\nvoid main(){vec4 image=texture2D(imageMap,vUv)*vec4(tint,opacity);if(image.a<=alphaTest)discard;\nvec2 uv=gl_FragCoord.xy/max(resolution,vec2(1.));vec3 base=texture2D(backdropMap,uv).rgb;\nvec3 mixed=applyAdvancedBlend(base,image.rgb);gl_FragColor=vec4(mix(base,mixed,image.a),1.);\n#include <colorspace_fragment>\n}";

package/dist/components/ScreenImage/materials/ScreenImageMaskMaterial.d.ts

@@ -0,0 +1,11 @@
+/** Which channel of a `maskTexture` carries coverage. */
+export declare const SCREEN_IMAGE_MASK_CHANNELS: readonly ["alpha", "red", "green", "luminance"];
+export type ScreenImageMaskChannel = (typeof SCREEN_IMAGE_MASK_CHANNELS)[number];
+export declare const resolveMaskChannelIndex: (channel: ScreenImageMaskChannel | undefined) => number;
+export declare const maskedVertexShader = "\nvarying vec2 vUv;\nvoid main(){vUv=uv;gl_Position=projectionMatrix*modelViewMatrix*vec4(position,1.0);}";
+/**
+ * Image × mask. Both are sampled through the image's fit transform (repeat /
+ * offset / flips), so a mask authored in the image's own space — a camera
+ * frame and its segmentation mask — stays aligned under cover-cropping.
+ */
+export declare const maskedFragmentShader = "\nuniform sampler2D imageMap;uniform sampler2D maskMap;uniform mat3 mapTransform;\nuniform vec3 tint;uniform float opacity;uniform float alphaTest;uniform int maskChannel;uniform float maskInvert;\nuniform float maskFeather;uniform float maskErode;uniform vec2 maskTexel;\nvarying vec2 vUv;\nfloat coverageAt(vec2 uv){\nvec4 m=texture2D(maskMap,uv);\nfloat c=maskChannel==0?m.a:maskChannel==1?m.r:maskChannel==2?m.g:dot(m.rgb,vec3(0.299,0.587,0.114));\nreturn mix(c,1.0-c,maskInvert);}\nvoid main(){\nvec2 uv=(mapTransform*vec3(vUv,1.0)).xy;\nvec4 image=texture2D(imageMap,uv);\nfloat coverage;\nif(maskFeather>0.0){\nvec2 step=maskTexel*maskFeather;\ncoverage=0.0;\nfor(int y=-1;y<=1;y++){for(int x=-1;x<=1;x++){coverage+=coverageAt(uv+vec2(float(x),float(y))*step);}}\ncoverage/=9.0;\n// Erode: raise the threshold on the blurred edge so the silhouette shrinks\n// by up to the feather radius (maskErode is a fraction of that width).\ncoverage=smoothstep(clamp(maskErode,0.0,0.95),1.0,coverage);\n}else{coverage=coverageAt(uv);}\nfloat alpha=image.a*opacity*coverage;\nif(alpha<=alphaTest)discard;\ngl_FragColor=vec4(image.rgb*tint,alpha);\n#include <colorspace_fragment>\n}";

package/dist/components/ScreenImage/materials/ScreenImageMatcap.d.ts

@@ -0,0 +1,3 @@
+import * as THREE from "three";
+/** Creates the internally owned procedural matcap used by ScreenImage. */
+export declare const createMatcapTexture: () => THREE.CanvasTexture;

package/dist/components/ScreenImage/source.d.ts

@@ -0,0 +1,25 @@
+import type * as THREE from "three";
+export type ScreenImageSource = {
+    kind: "default";
+} | {
+    kind: "image";
+    src: string;
+} | {
+    kind: "gif";
+    src: string;
+} | {
+    kind: "texture";
+    texture: THREE.Texture;
+};
+export declare const resolveScreenImageSource: (source: ScreenImageSource | undefined, src: string | undefined) => ScreenImageSource;
+export declare const getScreenImageTextureSize: (texture: THREE.Texture) => {
+    width: number;
+    height: number;
+};
+/**
+ * Textures whose pixels change after upload: videos and any canvas-backed
+ * texture, including `OffscreenCanvas` sources such as the session camera
+ * feed. These need `needsUpdate` every frame to stay live.
+ */
+export declare const isDynamicScreenImageTexture: (texture: THREE.Texture) => boolean;
+export declare const getScreenImageTextureAspect: (texture: THREE.Texture) => number;

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

@@ -0,0 +1,64 @@
+import { ScreenAnchorEdges, ScreenOffsetEdges, ScreenTransformGuideLayer } from '../ScreenSpaceUI';
+import { ScreenCanvasSize, ScreenCoordinateSpace, ScreenTransform2DSettings } from '../../screen2d';
+import { ScreenImageFit, ScreenImageStretchMode } from './fit';
+import { ScreenImageMaskChannel } from './materials/ScreenImageMaskMaterial';
+import { ScreenImageSource } from './source';
+import type * as THREE from "three";
+export type ScreenImageMaterialType = "unlit" | "standardPBR" | "matcap";
+export type ScreenImageBlendMode = "normal" | "add" | "subtract" | "multiply" | "screen" | "lighten" | "darken" | "overlay" | "softLight" | "hardLight" | "difference" | "exclusion";
+export type ScreenImageProps = {
+    name?: string;
+    source?: ScreenImageSource;
+    src?: string;
+    anchors?: ScreenAnchorEdges;
+    coordinateSpace?: ScreenCoordinateSpace;
+    canvasSize?: ScreenCanvasSize;
+    position?: [number, number];
+    size?: [number, number];
+    rotation?: number;
+    offsets?: ScreenOffsetEdges;
+    pivot?: [number, number];
+    transform?: Partial<ScreenTransform2DSettings>;
+    onScreenTransformChange?: (next: ScreenTransform2DSettings) => void;
+    transformGuideLayer?: ScreenTransformGuideLayer;
+    /** @tweak label=Fit */
+    fit?: ScreenImageFit;
+    stretchMode?: ScreenImageStretchMode;
+    materialType?: ScreenImageMaterialType;
+    /** @tweak label="Blend mode" */
+    blendMode?: ScreenImageBlendMode;
+    backdropTexture?: THREE.Texture | null;
+    /** @tweak unit=ratio min=0 max=1 step=0.01 label=Opacity */
+    opacity?: number;
+    /** @tweak color label=Tint */
+    color?: THREE.ColorRepresentation;
+    /**
+     * Alpha mask in the image's own texture space: it is sampled through the
+     * same fit / crop / flip transform as the image, so a camera frame and its
+     * segmentation mask stay aligned. Takes precedence over advanced blend modes.
+     */
+    maskTexture?: THREE.Texture | null;
+    /** Channel of `maskTexture` that carries coverage. Default `"alpha"`. */
+    maskChannel?: ScreenImageMaskChannel;
+    /** Keep where the mask is 0 instead of 1. */
+    maskInvert?: boolean;
+    /** Soften mask edges: 3×3 blur radius in mask texels. 0 = hard. */
+    maskFeather?: number;
+    /**
+     * Shrink the kept region into the feathered edge, 0..1 of the feather
+     * width; removes fringe from the source. Needs `maskFeather` > 0.
+     */
+    maskErode?: number;
+    /** @tweak label="Flip X" */
+    flipX?: boolean;
+    /** @tweak label="Flip Y" */
+    flipY?: boolean;
+    /** @tweak step=1 label="Render order" */
+    renderOrder?: number;
+    transparent?: boolean;
+    alphaTest?: number;
+    /** @tweak label=Overlay */
+    overlay?: boolean;
+    /** @tweak label=Visible */
+    visible?: boolean;
+};

package/dist/components/ScreenImage/utils/ScreenImageConstants.d.ts

@@ -0,0 +1,9 @@
+import { ScreenAnchorEdges, ScreenOffsetEdges } from '../../ScreenSpaceUI';
+import { ScreenImageBlendMode } from '../types';
+export declare const DEFAULT_SCREEN_IMAGE_ANCHORS: Required<ScreenAnchorEdges>;
+export declare const DEFAULT_SCREEN_IMAGE_OFFSET: ScreenOffsetEdges;
+export declare const DEFAULT_SCREEN_IMAGE_PIVOT: [number, number];
+export declare const screenImageBlendModeOptions: Array<{
+    label: string;
+    value: ScreenImageBlendMode;
+}>;

package/dist/components/ScreenImage/utils/ScreenImageHelpers.d.ts

@@ -0,0 +1,4 @@
+import { ScreenAnchorEdges } from '../../ScreenSpaceUI';
+import { ScreenCanvasSize, ScreenCoordinateSpace } from '../../../screen2d';
+export declare const toScreenTransformPivot: (pivot: [number, number]) => [number, number];
+export declare const resolveScreenImageAnchors: (anchors: ScreenAnchorEdges | undefined, coordinateSpace: ScreenCoordinateSpace | undefined, canvasSize: ScreenCanvasSize | undefined, position: [number, number] | undefined, size: [number, number] | undefined) => ScreenAnchorEdges;

package/dist/components/ScreenShape/geometry.d.ts

@@ -0,0 +1,5 @@
+import { ScreenShapeSettings } from './types';
+import * as THREE from "three";
+export type ScreenShapePoint = [number, number, number];
+export declare const buildScreenShapePath: (settings: ScreenShapeSettings) => ScreenShapePoint[];
+export declare const createScreenShapeFill: (points: ScreenShapePoint[]) => THREE.Shape;

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

@@ -0,0 +1,5 @@
+import { ScreenShapeProps, ScreenShapeSettings, ScreenShapeSettingsInput } from './types';
+export type { ScreenShapeKind, ScreenShapeProps, ScreenShapeSettings, ScreenShapeSettingsInput, } from './types';
+export declare const DEFAULT_SCREEN_SHAPE_SETTINGS: ScreenShapeSettings;
+export declare const mergeScreenShapeSettings: (settings?: ScreenShapeSettingsInput) => ScreenShapeSettings;
+export declare const ScreenShape: ({ name, onScreenTransformChange, renderOrder, settings: partialSettings, transform: partialTransform, transformGuideLayer, visible, }: ScreenShapeProps) => import("react/jsx-runtime").JSX.Element | null;

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

@@ -0,0 +1,54 @@
+import { ScreenTransformGuideLayer } from '../ScreenSpaceUI';
+import { ScreenTransform2DSettings } from '../../screen2d';
+import { ScreenGradientSettings } from '../ScreenGradient';
+import { ScreenGlassSettings } from '../ScreenGlass';
+export type ScreenShapeKind = "circle" | "ellipse" | "rectangle" | "roundedRectangle" | "polygon" | "star" | "line";
+export type ScreenShapeSettings = {
+    /** @tweak label=Shape */
+    kind: ScreenShapeKind;
+    /** @tweak color label="Fill colour" */
+    fillColor: string;
+    /** @tweak unit=ratio min=0 max=1 step=0.01 label="Fill opacity" */
+    fillOpacity: number;
+    /** @tweak label="Fill mode" */
+    fillMode: "solid" | "gradient" | "glass";
+    gradient: ScreenGradientSettings;
+    glass: ScreenGlassSettings;
+    /** @tweak color label="Stroke colour" */
+    strokeColor: string;
+    /** @tweak unit=ratio min=0 max=1 step=0.01 label="Stroke opacity" */
+    strokeOpacity: number;
+    /** @tweak unit=px min=0 step=0.5 label="Stroke width" */
+    strokeWidth: number;
+    /** @tweak unit=ratio min=0 max=0.5 step=0.01 label="Corner radius" */
+    cornerRadius: number;
+    /** @tweak min=3 max=12 step=1 label=Sides */
+    sides: number;
+    /** @tweak unit=ratio min=0.05 max=0.95 step=0.01 label="Inner radius" */
+    innerRadiusRatio: number;
+    /** @tweak label=Dashed */
+    dashed: boolean;
+    lineStart: {
+        x: number;
+        y: number;
+    };
+    lineEnd: {
+        x: number;
+        y: number;
+    };
+};
+export type ScreenShapeSettingsInput = Omit<Partial<ScreenShapeSettings>, "gradient" | "glass"> & {
+    gradient?: Partial<ScreenGradientSettings>;
+    glass?: Partial<ScreenGlassSettings>;
+};
+export type ScreenShapeProps = {
+    name?: string;
+    settings?: ScreenShapeSettingsInput;
+    transform?: Partial<ScreenTransform2DSettings>;
+    onScreenTransformChange?: (next: ScreenTransform2DSettings) => void;
+    transformGuideLayer?: ScreenTransformGuideLayer;
+    /** @tweak step=1 label="Render order" */
+    renderOrder?: number;
+    /** @tweak label=Visible */
+    visible?: boolean;
+};

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

@@ -0,0 +1,15 @@
+import { ThreeEvent } from '@react-three/fiber';
+export type ScreenTransformControlHandle = "move" | "pivot" | "rotateTopLeft" | "rotateTopRight" | "rotateBottomLeft" | "rotateBottomRight" | "top" | "bottom" | "left" | "right" | "topLeft" | "topRight" | "bottomLeft" | "bottomRight";
+export type ScreenTransformGuideProps = {
+    color?: string;
+    controlScale?: [number, number, number];
+    handleColor?: string;
+    onHandlePointerDown?: (handle: ScreenTransformControlHandle, event: ThreeEvent<PointerEvent>) => void;
+    opacity?: number;
+    pivot?: [number, number];
+    pivotScale?: [number, number, number];
+    renderOrder?: number;
+    showSideHandles?: boolean;
+    thickness?: number;
+};
+export declare const ScreenTransformGuide: ({ color, controlScale, handleColor, onHandlePointerDown, opacity, pivot, pivotScale, renderOrder, showSideHandles, thickness, }: ScreenTransformGuideProps) => import("react/jsx-runtime").JSX.Element;

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

@@ -11,6 +11,7 @@ export type ScreenSpaceUIProps = {
     /**
      * Z position of the screen plane.
      * Default: 0 (at the camera's focal plane)
+     * @tweak unit=m step=0.01 label=Depth
      */
     depth?: number;
 };
@@ -36,5 +37,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/SegmentationOverlay/SegmentationOverlay.d.ts

@@ -0,0 +1,37 @@
+import { ReactNode } from 'react';
+import { SemanticMask } from '../../segmentation2d/types';
+import { SegmentationOverlaySettings } from './settings';
+import * as THREE from "three";
+export type SegmentationOverlayMaterialContext = {
+    cameraTexture: THREE.Texture | null;
+    /**
+     * Class-index texture (red channel, 0..255 → index); nearest-filtered.
+     * Re-allocated when the mask changes size; the factory is re-run with the
+     * new texture, so read it from the context rather than caching it.
+     */
+    maskTexture: THREE.Texture;
+    /** Feed UV → mask UV, including the row flip, mirror and source cover-fit. */
+    maskTransform: THREE.Matrix3;
+    /** Class indices the overlay selects, resolved from `label` against the mask; empty until the mask has data. */
+    labelIndices: number[];
+    mask: SemanticMask | null;
+    settings: SegmentationOverlaySettings;
+};
+export type SegmentationOverlayMaterialSpec = ReactNode | THREE.Material | ((context: SegmentationOverlayMaterialContext) => ReactNode | THREE.Material);
+export type SegmentationOverlayProps = Partial<SegmentationOverlaySettings> & {
+    /** The mask to draw from: a provider hook's result or your own `SemanticMask`. */
+    mask: SemanticMask | null;
+    /** Optional image multiplied into the paint, sampled in screen UV (cover of the viewport). */
+    texture?: THREE.Texture | string;
+    /** Custom material (node, instance, or factory). Replaces the built-in look. */
+    material?: SegmentationOverlayMaterialSpec;
+    /** Default: just above the video background. */
+    renderOrder?: number;
+    visible?: boolean;
+};
+/**
+ * Draw one or more semantic regions of a mask as a screen-aligned 2D layer,
+ * tinted and composited over the camera feed. Covers the viewport exactly
+ * like `VideoBackground`, so feed-space masks need no coordinate work.
+ */
+export declare const SegmentationOverlay: ({ mask, texture, material, renderOrder, visible, ...settingsInput }: SegmentationOverlayProps) => import("react/jsx-runtime").JSX.Element | null;

package/dist/components/SegmentationOverlay/SegmentationOverlayMaterial.d.ts

@@ -0,0 +1,31 @@
+import { SemanticMask } from '../../segmentation2d/types';
+import { SegmentationOverlaySettings } from './settings';
+import * as THREE from "three";
+/** Up to this many labels can be selected by one overlay. */
+export declare const MAX_OVERLAY_LABELS = 4;
+export type SegmentationOverlayMaterialInputs = {
+    cameraTexture: THREE.Texture | null;
+    maskTexture: THREE.Texture;
+    mask: SemanticMask | null;
+    settings: SegmentationOverlaySettings;
+    /** Optional image sampled in screen UV and multiplied into the paint. */
+    designTexture?: THREE.Texture | null;
+    /** Feed (camera texture) size, for cover-fitting source-space masks. */
+    feedWidth?: number;
+    feedHeight?: number;
+};
+export declare const SEGMENTATION_OVERLAY_VERTEX_SHADER = "\nvarying vec2 vUv;\nvoid main() {\n  vUv = uv;\n  gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);\n}";
+export declare const SEGMENTATION_OVERLAY_FRAGMENT_SHADER = "\nuniform sampler2D cameraTexture;\nuniform sampler2D maskTexture;\nuniform sampler2D designTexture;\nuniform float useDesign;\nuniform vec4 labels;\nuniform float labelCount;\nuniform float invert;\nuniform vec3 tint;\nuniform float opacity;\nuniform float blendMode;\nuniform float feather;\nuniform vec2 maskTexel;\nuniform mat3 maskTransform;\nvarying vec2 vUv;\n\nfloat member(vec2 uv) {\n  if (uv.x < 0.0 || uv.x > 1.0 || uv.y < 0.0 || uv.y > 1.0) return 0.0;\n  float index = floor(texture2D(maskTexture, uv).r * 255.0 + 0.5);\n  float m = 0.0;\n  if (labelCount > 0.5 && abs(index - labels.x) < 0.5) m = 1.0;\n  if (labelCount > 1.5 && abs(index - labels.y) < 0.5) m = 1.0;\n  if (labelCount > 2.5 && abs(index - labels.z) < 0.5) m = 1.0;\n  if (labelCount > 3.5 && abs(index - labels.w) < 0.5) m = 1.0;\n  return invert > 0.5 ? 1.0 - m : m;\n}\n\nvoid main() {\n  vec2 maskUv = (maskTransform * vec3(vUv, 1.0)).xy;\n  float coverage;\n  if (feather > 0.0) {\n    vec2 step = maskTexel * feather;\n    coverage = 0.0;\n    for (int y = -1; y <= 1; y++) {\n      for (int x = -1; x <= 1; x++) {\n        coverage += member(maskUv + vec2(float(x), float(y)) * step);\n      }\n    }\n    coverage /= 9.0;\n  } else {\n    coverage = member(maskUv);\n  }\n\n  vec3 base = texture2D(cameraTexture, vUv).rgb;\n  vec4 design = useDesign > 0.5 ? texture2D(designTexture, vUv) : vec4(1.0);\n  vec3 paint = tint * design.rgb;\n  vec3 blended = blendMode < 0.5\n    ? paint\n    : blendMode < 1.5\n      ? base * paint\n      : blendMode < 2.5\n        ? 1.0 - (1.0 - base) * (1.0 - paint)\n        : mix(2.0 * base * paint, 1.0 - 2.0 * (1.0 - base) * (1.0 - paint), step(0.5, base));\n\n  gl_FragColor = vec4(blended, coverage * opacity * design.a);\n  #include <colorspace_fragment>\n}";
+/** The built-in overlay material as a plain three.js object (shareable across meshes). */
+export declare const createSegmentationOverlayMaterial: () => THREE.ShaderMaterial;
+/** Resolve the selected labels to class indices for a mask (unknown labels are skipped). */
+export declare const resolveOverlayLabelIndices: (mask: Pick<SemanticMask, "labels"> | null, label: string | readonly string[]) => number[];
+/**
+ * The class indices an overlay should draw right now: the resolved labels,
+ * or none while the mask is still at `version` 0 (no data yet). Shared by
+ * the built-in material and the custom-material context so both agree.
+ */
+export declare const resolveActiveOverlayLabelIndices: (mask: SemanticMask | null, label: string | readonly string[]) => number[];
+export declare const updateSegmentationOverlayMaterial: (material: THREE.ShaderMaterial, { cameraTexture, maskTexture, mask, settings, designTexture, feedWidth, feedHeight, }: SegmentationOverlayMaterialInputs) => THREE.ShaderMaterial;
+/** Own one overlay material and keep it in sync with the inputs on every render. */
+export declare const useSegmentationOverlayMaterial: (inputs: SegmentationOverlayMaterialInputs) => THREE.ShaderMaterial;

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

@@ -0,0 +1,9 @@
+export { SegmentationOverlay } from './SegmentationOverlay';
+export type { SegmentationOverlayMaterialContext, SegmentationOverlayMaterialSpec, SegmentationOverlayProps, } from './SegmentationOverlay';
+export { MAX_OVERLAY_LABELS, SEGMENTATION_OVERLAY_FRAGMENT_SHADER, SEGMENTATION_OVERLAY_VERTEX_SHADER, createSegmentationOverlayMaterial, resolveActiveOverlayLabelIndices, resolveOverlayLabelIndices, updateSegmentationOverlayMaterial, useSegmentationOverlayMaterial, } from './SegmentationOverlayMaterial';
+export type { SegmentationOverlayMaterialInputs } from './SegmentationOverlayMaterial';
+export { createSemanticMaskTexture, uploadSemanticMask, useSemanticMaskTexture, } from './maskTexture';
+export { PERSON_MASK_LABELS, resolveMaskSize, useFaceRegionMask, useHairMask, usePersonMask, useSemanticSegmentationMask, } from './providers';
+export type { SemanticSegmentationMaskResult, UseFaceRegionMaskOptions, UsePersonMaskOptions, UseSemanticSegmentationMaskOptions, } from './providers';
+export { DEFAULT_SEGMENTATION_OVERLAY_SETTINGS, SEGMENTATION_OVERLAY_BLEND_MODES, SEGMENTATION_OVERLAY_SETTINGS_FIELDS, parseOverlayLabels, patchSegmentationOverlaySettings, resolveSegmentationOverlaySettings, } from './settings';
+export type { SegmentationOverlayBlendMode, SegmentationOverlaySettings } from './settings';

package/dist/components/SegmentationOverlay/maskTexture.d.ts

@@ -0,0 +1,23 @@
+import { SemanticMask } from '../../segmentation2d/types';
+import * as THREE from "three";
+/** One red byte per pixel holding the class index; nearest filtering keeps classes crisp. */
+export declare const createSemanticMaskTexture: (width?: number, height?: number) => THREE.DataTexture;
+/**
+ * Copy a mask into the texture, re-allocating when its size changed. Returns
+ * the texture to use (a new one when re-allocated; dispose the old one).
+ */
+export declare const uploadSemanticMask: (texture: THREE.DataTexture, mask: SemanticMask) => THREE.DataTexture;
+type Uploaded = {
+    texture: THREE.DataTexture;
+    version: number;
+    mask: SemanticMask | null;
+};
+/**
+ * Keep a GPU copy of a mask in sync with its `version`. The returned holder
+ * is stable; call `sync()` once per frame (or render) before drawing.
+ */
+export declare const useSemanticMaskTexture: (mask: SemanticMask | null) => {
+    holder: Uploaded;
+    sync: () => THREE.DataTexture;
+};
+export {};