@vincentt-xr/sdk 2.0.0-alpha.7 → 2.0.0-alpha.8

package/docs/examples/lip-shaders.mdx

@@ -0,0 +1,224 @@
+---
+title: "Lip Shader Examples"
+description: "Custom material factories for LipEffect: animated gloss, noise texture, iridescence, and a time-based shimmer."
+sidebarTitle: "Lip Shaders"
+icon: "wand-magic-sparkles"
+---
+
+{/* Generated by scripts/generate-lip-shader-docs.mjs from example/src/pages/LipEffect/customMaterials.tsx. Edit the source, then re-run. */}
+
+`LipEffect`'s `material` prop accepts a factory. It receives a
+`LipEffectMaterialContext` and returns a material node or a three.js material
+instance. These four examples share one component shell and differ only in
+their fragment shader. They are live on the example playground's `/lip-effect`
+page under the material picker; the source is
+`example/src/pages/LipEffect/customMaterials.tsx`.
+
+## What every example relies on
+
+- `LIP_EFFECT_VERTEX_SHADER` from `@vincentt-xr/sdk/face-effects` provides
+  `vUv` (canonical UV), `vFaceUv` (live camera UV), `vLipEdge` (0 at the outer
+  ring, 1 at the mouth line), `vNormal` and `vViewDir`.
+- One `uniforms` object per material, created with `useMemo` and mutated on
+  each render. three.js binds the uniforms object when the program compiles,
+  so a new object per render would be ignored.
+- `useFrame` advances `uTime` for the animated looks.
+- The stencil test follows `context.maskMode`: `stencilWrite` must be true for
+  three.js to run the comparison at all, and the keep-ops stop the material
+  from altering the mouth stencil it tests against.
+- Coverage is design alpha × opacity × a feather from `vLipEdge`, read from
+  `context.settings`, so the panel controls still apply.
+
+```glsl
+const COMMON_HEAD = `
+uniform sampler2D cameraTexture;
+uniform sampler2D designTexture;
+uniform float useDesign;
+uniform vec3 tint;
+uniform float opacity;
+uniform float edgeSoftness;
+uniform float uTime;
+varying vec2 vFaceUv;
+varying vec2 vUv;
+varying float vLipEdge;
+varying vec3 vNormal;
+varying vec3 vViewDir;
+
+float hash(vec2 p) {
+  return fract(sin(dot(p, vec2(127.1, 311.7))) * 43758.5453123);
+}
+float noise(vec2 p) {
+  vec2 i = floor(p);
+  vec2 f = fract(p);
+  f = f * f * (3.0 - 2.0 * f);
+  return mix(
+    mix(hash(i), hash(i + vec2(1.0, 0.0)), f.x),
+    mix(hash(i + vec2(0.0, 1.0)), hash(i + vec2(1.0, 1.0)), f.x),
+    f.y
+  );
+}
+float coverage() {
+  vec4 design = mix(vec4(1.0), texture2D(designTexture, vUv), useDesign);
+  float fade = smoothstep(0.0, max(edgeSoftness, 1e-4), vLipEdge);
+  return design.a * opacity * fade;
+}
+vec3 facing() {
+  vec3 n = normalize(vNormal);
+  return gl_FrontFacing ? n : -n;
+}
+`;
+```
+
+## Animated gloss
+
+The key light orbits, sweeping a pulsing highlight across the lips.
+
+````glsl
+void main() {
+  vec3 base = texture2D(cameraTexture, vFaceUv).rgb;
+  // The key light orbits slowly, so the highlight sweeps across the lips.
+  vec3 light = normalize(vec3(sin(uTime * 0.8), 0.6, cos(uTime * 0.8) * 0.5 + 0.8));
+  vec3 h = normalize(light + normalize(vViewDir));
+  float specular = pow(max(dot(facing(), h), 0.0), 48.0);
+  float pulse = 0.75 + 0.25 * sin(uTime * 2.0);
+  vec3 painted = tint * (0.6 + 0.8 * dot(base, vec3(0.333)));
+  float c = coverage();
+  gl_FragColor = vec4(mix(base, painted, c) + specular * pulse * c, c);
+  #include <colorspace_fragment>
+}```
+
+## Noise texture
+
+Value noise breaks up the paint and a sparse hash adds glitter grains. No image
+texture is needed.
+
+```glsl
+void main() {
+  vec3 base = texture2D(cameraTexture, vFaceUv).rgb;
+  // Fine value noise breaks up the paint; a sparse hash adds glitter grains.
+  float grain = noise(vUv * 420.0);
+  float glitter = step(0.985, hash(floor(vUv * 900.0)));
+  vec3 painted = tint * (0.75 + 0.5 * grain) + glitter * 0.6;
+  painted *= 0.5 + dot(base, vec3(0.333));
+  float c = coverage();
+  gl_FragColor = vec4(mix(base, painted, c), c);
+  #include <colorspace_fragment>
+}```
+
+## Iridescence
+
+A cosine palette driven by the viewing angle (fresnel) and the band position,
+drifting slowly over time.
+
+```glsl
+vec3 palette(float t) {
+  return 0.5 + 0.5 * cos(6.28318 * (vec3(1.0, 1.0, 1.0) * t + vec3(0.0, 0.33, 0.67)));
+}
+void main() {
+  vec3 base = texture2D(cameraTexture, vFaceUv).rgb;
+  vec3 n = facing();
+  vec3 v = normalize(vViewDir);
+  // Hue shifts with the viewing angle (fresnel) and drifts slowly with time.
+  float fresnel = pow(1.0 - max(dot(n, v), 0.0), 1.5);
+  vec3 sheen = palette(fresnel * 1.2 + vLipEdge * 0.25 + uTime * 0.05);
+  vec3 painted = mix(tint, sheen, 0.55 + 0.45 * fresnel) * (0.6 + 0.8 * dot(base, vec3(0.333)));
+  vec3 h = normalize(vec3(0.3, 0.6, 1.0) + v);
+  float specular = pow(max(dot(n, h), 0.0), 64.0) * 0.8;
+  float c = coverage();
+  gl_FragColor = vec4(mix(base, painted, c) + specular * c, c);
+  #include <colorspace_fragment>
+}```
+
+## Time-based shimmer
+
+Per-cell twinkling grains with a slow bright band moving across the lips.
+
+```glsl
+void main() {
+  vec3 base = texture2D(cameraTexture, vFaceUv).rgb;
+  // Twinkling grains: each cell blinks on its own phase; a bright band sweeps across.
+  vec2 cell = floor(vUv * 520.0);
+  float seed = hash(cell);
+  float twinkle = 0.5 + 0.5 * sin(uTime * 6.0 + seed * 60.0);
+  float sparkle = smoothstep(0.96, 1.0, seed * twinkle);
+  float band = smoothstep(0.08, 0.0, abs(fract(vUv.x * 2.5 - uTime * 0.25) - 0.5));
+  vec3 painted = tint * (0.7 + 0.6 * dot(base, vec3(0.333))) + vec3(sparkle) + band * 0.25;
+  float c = coverage();
+  gl_FragColor = vec4(mix(base, painted, c), c);
+  #include <colorspace_fragment>
+}```
+
+## The factory component
+
+```tsx
+/** One factory component for every example; the shader key picks the look. */
+export const CustomLipShader = ({
+  context,
+  shader,
+}: {
+  context: LipEffectMaterialContext;
+  shader: CustomLipShaderKey;
+}) => {
+  // One uniforms object for the material's lifetime; values are mutated.
+  const uniforms = useMemo(
+    () => ({
+      cameraTexture: { value: null as THREE.Texture | null },
+      designTexture: { value: null as THREE.Texture | null },
+      useDesign: { value: 0 },
+      tint: { value: new THREE.Color() },
+      opacity: { value: 1 },
+      edgeSoftness: { value: 0.12 },
+      uTime: { value: 0 },
+    }),
+    [],
+  );
+  uniforms.cameraTexture.value = context.cameraTexture;
+  uniforms.designTexture.value = context.designTexture;
+  uniforms.useDesign.value = context.designTexture ? 1 : 0;
+  uniforms.tint.value.set(context.settings.color);
+  uniforms.opacity.value = context.settings.opacity;
+  uniforms.edgeSoftness.value = context.settings.edgeSoftness;
+  useFrame((_, delta) => {
+    uniforms.uTime.value += delta;
+  });
+
+  return (
+    <shaderMaterial
+      key={shader}
+      uniforms={uniforms}
+      vertexShader={LIP_EFFECT_VERTEX_SHADER}
+      fragmentShader={SHADERS[shader]}
+      transparent
+      side={THREE.DoubleSide}
+      depthWrite={false}
+      toneMapped={false}
+      // The stencil test only runs while stencilWrite is true; keep-ops make
+      // it a pure comparison against the mouth stencil, writing nothing back.
+      stencilWrite
+      stencilRef={1}
+      stencilFunc={
+        context.maskMode === "outer-and-inner-lips"
+          ? THREE.NotEqualStencilFunc
+          : THREE.AlwaysStencilFunc
+      }
+      stencilFail={THREE.KeepStencilOp}
+      stencilZFail={THREE.KeepStencilOp}
+      stencilZPass={THREE.KeepStencilOp}
+    />
+  );
+};
+````
+
+Use it like any other factory:
+
+```tsx
+<LipEffect
+  preset="gloss"
+  material={(context) => <CustomLipShader context={context} shader="iridescence" />}
+/>
+```
+
+To share one custom material across several faces, build a
+`THREE.ShaderMaterial` yourself, update its uniforms in `useFrame`, and return
+the instance from the factory (or pass it as `sharedMaterial`); the renderer
+sets a material instance on the mesh directly, so several meshes can use it.

package/docs/guides/lip-effect-textures.mdx

@@ -0,0 +1,292 @@
+---
+title: "Lip Effect Textures"
+description: "How to author a design texture for LipEffect: the canvas contract, the lip UV template, orientation, mask modes, and the custom material context."
+sidebarTitle: "Lip Effect Textures"
+icon: "palette"
+---
+
+`LipEffect` (from `@vincentt-xr/sdk/face-effects`) paints a design texture onto
+the lips of a tracked face. The texture lives in the **canonical face UV
+atlas**, but only the lip triangles are ever sampled. Everything this page
+describes is derived from the canonical mesh's own `uv` attribute: the mesh is
+the design contract, not a hand-drawn diagram.
+
+## The canvas contract
+
+- **Square image, any resolution.** 1024×1024 or 2048×2048 is plenty; the lips
+  cover a small part of it. The layout is the same atlas as
+  `Canonical_Face_Color.png`.
+- **Only the lip region is used.** The outer lip ring spans roughly
+  **x 38–62 %** and **y 65–74 %** of the image. Pixels outside the lip
+  triangles are never sampled, so leave them transparent or use them for notes.
+- **Transparent means untouched skin.** The alpha channel drives the blend
+  (`design.a × opacity`). Soft edges in alpha give soft lip edges.
+- **RGB is tinted by `color`.** At `intensity={1}` the design's RGB is
+  multiplied by `color`; at `intensity={0}` the design colours show as painted.
+  Paint white or light grey for a pure tint, or paint real colour and lower
+  `intensity`.
+- **Image top is `v = 1`.** Textures load with `flipY`, so the top row of the
+  image is the top of the UV atlas and the upper lip sits above the lower lip
+  in the image, as you would expect.
+
+## The lip UV template
+
+<img
+  src="/guides/lip-uv-template.svg"
+  alt="Lip UV template generated from the canonical face mesh"
+/>
+
+The template is generated from `canonical_face_model.obj`:
+
+- **Solid pink ring** — the outer lip ring (MediaPipe `FACEMESH_LIPS` outer
+  contour). This is the painted edge.
+- **Dashed blue ring and blue fill** — the inner lip ring and the mouth
+  interior. In the default `outer-and-inner-lips` mask mode this area is cut
+  out, so teeth and tongue stay clean when the mouth opens.
+- **Grey wireframe** — the lip triangles that are actually sampled.
+- **Orientation labels** — image **left** is the subject's **right** lip corner.
+
+Regenerate it after the canonical OBJ changes on the CDN; the script verifies
+the download against the hash pinned in `lib/utils/integrity.ts`:
+
+```bash
+pnpm dlx tsx scripts/generate-lip-uv-guide.ts --png
+```
+
+### Mirrored camera behaviour
+
+The design is always mapped in the **subject's** frame: the left edge of the
+lip region is the subject's right lip corner, whatever is on screen.
+
+- With the **webcam**, the session mirrors the feed once (selfie view), so the
+  subject's right appears on **screen right**. The left side of your design
+  therefore lands on the right side of the screen.
+- With **image or video sources**, nothing is mirrored, so the subject's right
+  (and the left side of your design) appears on **screen left**.
+
+Do not add a second mirror in CSS, canvas, or a shader; see "Camera, layout,
+mirror, and capture parity" in `GROUNDING.md`.
+
+### Generating the guide at runtime
+
+The same renderer is exported, so an editor or a debug panel can draw the guide
+from the live mesh:
+
+```tsx
+import {
+  createLipUvGuideDataUrl,
+  createLipUvGuideSvg,
+  getLipUvBounds,
+  useCanonicalFaceMesh,
+} from "@vincentt-xr/sdk/face-effects";
+
+const mesh = useCanonicalFaceMesh();
+const svg = mesh ? createLipUvGuideSvg(mesh, { size: 1024 }) : null;
+const zoomed = mesh ? createLipUvGuideDataUrl(mesh, { region: "lips" }) : null;
+const bounds = mesh ? getLipUvBounds(mesh) : null; // { minU, maxU, minV, maxV }
+```
+
+Options: `size` (canvas pixels), `region` (`"canvas"` or `"lips"`),
+`wireframe`, `labels`, `background`. `lipUvToPixel(u, v, size)` converts a UV
+to image pixels with the `flipY` convention.
+
+The example playground's `/lip-effect` page has a **Texture preview / UV
+guide** toggle: it overlays the guide on the current design texture, shows a
+zoomed crop of the lip region, and paints the template itself onto the tracked
+lips so the labelled rings can be checked against a real mouth.
+
+## Presets and material controls
+
+`LipEffect` takes flat, serializable settings (`LipEffectSettings`). Start from
+a preset and override what you need; explicit props always win over the preset:
+
+```tsx
+<LipEffect preset="matte" color="#8b2635" designTexture="/lips/matte.png" />
+```
+
+| Preset     | Look                                                            |
+| ---------- | --------------------------------------------------------------- |
+| `lipstick` | Opaque colour with a soft highlight                             |
+| `gloss`    | Translucent colour with a strong, tight highlight               |
+| `matte`    | Opaque, no highlight, heavy skin shading                        |
+| `tint`     | Sheer wash of colour that keeps the natural lip                 |
+| `metallic` | Full-strength, tight gold-tinted highlight                      |
+| `gradient` | Ombre: strong colour at the mouth line fading at the outer edge |
+
+Controls: `color`, `opacity`, `intensity` (0 shows the design as painted, 1
+multiplies it by `color`), `shading` (how much the camera's own lip light and
+shadow show through), `gloss` and `roughness` (highlight amount and spread),
+`highlightColor`, and `gradientColor` with `gradientAmount`. Without a
+`designTexture` the lips are filled with `color`, so every preset works on its
+own.
+
+The `LipEffectSettingsPanel` from `@vincentt-xr/sdk/debug-ui` edits all of these
+live, including the mask mode and the texture transform, and the `/lip-effect`
+example page mounts it next to the design-texture picker.
+
+## Procedural colour, edges, inner lip and split lips
+
+- **Procedural colour.** Leave `designTexture` out, or set
+  `colorMode="solid"` to ignore one, and the lips are filled with `color`.
+  Add `gradientColor` with `gradientAmount` and pick `gradientDirection`:
+  `outward` runs from the mouth line to the outer edge, `vertical` and
+  `horizontal` span the lip box.
+- **Edge softness.** `edgeSoftness` feathers the outer lip boundary as a
+  fraction of the lip band (default `0.12`; `0` is a hard polygon edge). It
+  uses the mesh's own band position, so it follows the tracked lip shape.
+- **Inner lip.** `innerLipColor` with `innerLipAmount` tints the inner part of
+  the lips next to the mouth line; `innerLipWidth` sets how far out it reaches.
+  In `outer-lips` mask mode the same tint fills the mouth interior.
+- **Separate lower lip.** Turn on `splitLips` to give the lower lip its own
+  `lowerLipColor` and `lowerLipOpacity`, and pass `lowerDesignTexture` for a
+  separate texture (it falls back to `designTexture`). The split happens at the
+  mouth line of the canonical UV atlas with a thin blend at the corners.
+
+## Texture transform
+
+A design that does not line up can be fitted without repainting:
+
+| Setting                            | Effect                                                                                        |
+| ---------------------------------- | --------------------------------------------------------------------------------------------- |
+| `textureScaleX`, `textureScaleY`   | Multiplier about the lip centre; `2` makes the design twice as large                          |
+| `textureOffsetX`, `textureOffsetY` | Fraction of the lip region's width/height; `0.5` moves half a lip width (positive y moves up) |
+| `textureRotation`                  | Degrees, counter-clockwise as seen on the face                                                |
+| `textureFlipX`, `textureFlipY`     | Mirror across the lip centre                                                                  |
+
+The transform is applied to the sampled UV, so the gradient and the mask are
+unaffected. `createLipTextureTransform(settings, bounds)` returns the same
+`Matrix3` the shader uses if a custom material wants it.
+
+## Downloading the template
+
+The `/lip-effect` page has **Download SVG** and **Download PNG** buttons that
+export the guide at 2048 px straight from the loaded mesh. In code,
+`createLipUvGuideSvg(mesh, { size })` returns the SVG string and
+`createLipUvGuidePngBlob(mesh, { size })` resolves to a PNG `Blob` (browser
+only). The shipped copies are `docs/guides/lip-uv-template.svg` and
+`docs/guides/lip-uv-template.png`.
+
+## Mask modes
+
+```tsx
+<LipEffect designTexture="/lips/gloss.png" maskMode="outer-and-inner-lips" />
+```
+
+- `outer-and-inner-lips` (default) — paint the lip surface only. The mouth
+  interior writes the shared stencil buffer and the lip material skips it.
+- `outer-lips` — paint everything inside the outer ring, mouth interior
+  included.
+
+## Several faces and performance
+
+`LipEffects` renders one lip effect per face slot. Pass one config for every
+face or a picker per face:
+
+```tsx
+<LipEffects maxFaces={2} faces={{ preset: "gloss", designTexture: "/lips/gloss.png" }} />
+<LipEffects
+  maxFaces={2}
+  faces={(faceIndex) =>
+    faceIndex === 0 ? { preset: "matte", color: "#8b2635" } : { preset: "gloss" }
+  }
+/>
+```
+
+With a single config the faces share one built-in material. The material is a
+plain three.js object underneath: `useLipEffectMaterial(inputs)` returns one you
+can pass as `sharedMaterial` to any number of `LipEffect`s, or return from a
+`material` factory. `maxUpdateFps` caps how often the lip mesh follows the
+landmarks, and `<XRProvider perf={{ targetFps, camRes }}>` lowers the tracking
+rate and the analysed camera resolution for the whole session.
+
+## Custom materials
+
+`material` accepts a React material node or a factory. The factory receives a
+stable context and is called once per lip geometry group (plus the mouth
+interior in `outer-lips` mode), only after the canonical mesh has loaded:
+
+```ts
+type LipEffectMaterialContext = {
+  cameraTexture: THREE.Texture | null;
+  designTexture: THREE.Texture | null;
+  faceUv: THREE.BufferAttribute;
+  lipEdge: THREE.BufferAttribute;
+  lowerDesignTexture: THREE.Texture | null;
+  faceIndex: number;
+  maskMode: LipMaskMode;
+  lipUvBounds: LipUvBounds;
+  settings: LipEffectSettings;
+};
+```
+
+`lipEdge` is a static per-vertex position across the lip band: `0` on the
+outer ring, `1` on the mouth line. It is bound as `attribute float lipEdge`
+and is what the built-in material uses for feathering, the outward gradient
+and the inner-lip tint. `lipUvBounds.mouthV` is the mouth line in UV space.
+
+`faceUv` is the live per-vertex camera-texture UV. It is already bound to the
+geometry, so a custom vertex shader reads it as `attribute vec2 faceUv`; the
+attribute object is exposed for uniforms, debugging, or readback.
+
+```tsx
+<LipEffect
+  designTexture={texture}
+  material={({ cameraTexture, designTexture, maskMode }) => (
+    <shaderMaterial
+      uniforms={{
+        cameraTexture: { value: cameraTexture },
+        designTexture: { value: designTexture },
+      }}
+      vertexShader={`
+        attribute vec2 faceUv;
+        varying vec2 vFaceUv; varying vec2 vUv;
+        void main() {
+          vUv = uv; vFaceUv = faceUv;
+          gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
+        }`}
+      fragmentShader={`
+        uniform sampler2D cameraTexture; uniform sampler2D designTexture;
+        varying vec2 vFaceUv; varying vec2 vUv;
+        void main() {
+          vec4 design = texture2D(designTexture, vUv);
+          vec3 skin = texture2D(cameraTexture, vFaceUv).rgb;
+          gl_FragColor = vec4(skin * design.rgb, design.a);
+        }`}
+      transparent
+      depthWrite={false}
+      stencilWrite
+      stencilRef={1}
+      stencilFunc={
+        maskMode === "outer-and-inner-lips" ? THREE.NotEqualStencilFunc : THREE.AlwaysStencilFunc
+      }
+      stencilFail={THREE.KeepStencilOp}
+      stencilZFail={THREE.KeepStencilOp}
+      stencilZPass={THREE.KeepStencilOp}
+    />
+  )}
+/>
+```
+
+Four complete factories (animated gloss, noise texture, iridescence, time-based
+shimmer) are documented in [Lip Shader Examples](/examples/lip-shaders) and run
+on the `/lip-effect` page.
+
+Honour `maskMode` with the stencil test shown above; that is exactly what the
+built-in `LipEffectMaterial` does through its `subtractMouth` prop. Note that
+three.js only evaluates `stencilFunc` while `stencilWrite` is true, so keep it
+on and use the keep-ops: the material then compares against the mouth stencil
+without ever writing to it. The lip triangles already exclude the mouth cavity,
+so the stencil is the guard for anything that reaches past them. It is
+exported so you can reuse the default shader with different settings:
+
+```tsx
+material={(context) => (
+  <LipEffectMaterial
+    cameraTexture={context.cameraTexture}
+    designTexture={context.designTexture}
+    settings={resolveLipEffectSettings({ ...context.settings, preset: "metallic" })}
+    lipUvBounds={context.lipUvBounds}
+    subtractMouth={context.maskMode === "outer-and-inner-lips"}
+  />
+)}
+```

package/docs/guides/lip-uv-template.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1024" height="1024" viewBox="0 0 1024 1024"><rect x="1.28" y="1.28" width="1021.44" height="1021.44" fill="none" stroke="#cbd5e1" stroke-width="2.56"/><path d="M540.93,666.01L511.98,668.19L539.77,682.19ZM483.07,666.01L484.23,682.19L511.98,668.19ZM512.02,682.22L539.77,682.19L511.98,668.19ZM512.02,682.22L511.98,668.19L484.23,682.19ZM540.93,666.01L539.77,682.19L573.66,673ZM483.07,666.01L450.34,673L484.23,682.19ZM566.45,684.57L573.66,673L539.77,682.19ZM457.55,684.57L484.23,682.19L450.34,673ZM573.66,673L566.45,684.57L599.43,682.54ZM450.34,673L424.57,682.54L457.55,684.57ZM591.09,690.06L599.43,682.54L566.45,684.57ZM432.91,690.06L457.55,684.57L424.57,682.54ZM591.09,690.06L613.64,697.41L599.43,682.54ZM432.91,690.06L424.57,682.54L410.36,697.41ZM622.18,693.97L599.43,682.54L613.64,697.41ZM401.82,693.97L410.36,697.41L424.57,682.54ZM584.94,699.08L582.49,708.98L607.44,702.13ZM439.06,699.08L416.55,702.13L441.51,708.98ZM600.69,708.98L607.44,702.13L582.49,708.98ZM423.31,708.98L441.51,708.98L416.55,702.13ZM611.29,723.5L618.39,727.26L626.58,710.62ZM412.71,723.5L397.42,710.62L405.61,727.26ZM632.86,711.38L626.58,710.62L618.39,727.26ZM391.14,711.38L405.61,727.26L397.42,710.62ZM590.68,728.93L595.65,737.34L611.29,723.5ZM433.32,728.93L412.71,723.5L428.35,737.34ZM618.39,727.26L611.29,723.5L595.65,737.34ZM405.61,727.26L428.35,737.34L412.71,723.5ZM568.49,748.33L595.65,737.34L566.16,732.99ZM455.51,748.33L457.84,732.99L428.35,737.34ZM590.68,728.93L566.16,732.99L595.65,737.34ZM433.32,728.93L428.35,737.34L457.84,732.99ZM511.98,754.71L540.34,753.9L511.98,736.65ZM511.98,754.71L511.98,736.65L483.66,753.9ZM539.56,735.09L511.98,736.65L540.34,753.9ZM484.44,735.09L483.66,753.9L511.98,736.65ZM604.54,718.67L622.17,710.86L600.88,712.09ZM419.46,718.67L423.12,712.09L401.81,710.86ZM610.68,710.61L600.88,712.09L622.17,710.86ZM413.32,710.61L401.81,710.86L423.12,712.09ZM626.58,710.62L622.17,710.86L611.29,723.5ZM397.42,710.62L412.71,723.5L401.81,710.86ZM604.54,718.67L611.29,723.5L622.17,710.86ZM419.46,718.67L401.81,710.86L412.71,723.5ZM539.77,682.19L538.47,696.52L566.45,684.57ZM484.23,682.19L457.55,684.57L485.53,696.52ZM562.82,697.2L566.45,684.57L538.47,696.52ZM461.18,697.2L485.53,696.52L457.55,684.57ZM566.45,684.57L562.82,697.2L591.09,690.06ZM457.55,684.57L432.91,690.06L461.18,697.2ZM584.94,699.08L591.09,690.06L562.82,697.2ZM439.06,699.08L461.18,697.2L432.91,690.06ZM591.09,690.06L584.94,699.08L613.64,697.41ZM432.91,690.06L410.36,697.41L439.06,699.08ZM607.44,702.13L613.64,697.41L584.94,699.08ZM416.55,702.13L439.06,699.08L410.36,697.41ZM587.29,720.42L590.68,728.93L604.54,718.67ZM436.71,720.42L419.46,718.67L433.32,728.93ZM611.29,723.5L604.54,718.67L590.68,728.93ZM412.71,723.5L433.32,728.93L419.46,718.67ZM566.16,732.99L590.68,728.93L565.23,721.54ZM457.84,732.99L458.77,721.54L433.32,728.93ZM587.29,720.42L565.23,721.54L590.68,728.93ZM436.71,720.42L433.32,728.93L458.77,721.54ZM511.98,736.65L539.56,735.09L511.98,722.88ZM511.98,736.65L511.98,722.88L484.44,735.09ZM539.52,721.54L511.98,722.88L539.56,735.09ZM484.48,721.54L484.44,735.09L511.98,722.88ZM511.98,722.88L539.52,721.54L511.98,711.96ZM511.98,722.88L511.98,711.96L484.48,721.54ZM539.61,711.96L511.98,711.96L539.52,721.54ZM484.39,711.96L484.48,721.54L511.98,711.96ZM564.57,711.96L565.23,721.54L585.79,711.96ZM459.43,711.96L438.21,711.96L458.77,721.54ZM587.29,720.42L585.79,711.96L565.23,721.54ZM436.71,720.42L458.77,721.54L438.21,711.96ZM600.88,712.09L585.79,711.96L604.54,718.67ZM423.12,712.09L419.46,718.67L438.21,711.96ZM587.29,720.42L604.54,718.67L585.79,711.96ZM436.71,720.42L438.21,711.96L419.46,718.67ZM562.82,697.2L560.97,708.98L584.94,699.08ZM461.18,697.2L439.06,699.08L463.03,708.98ZM582.49,708.98L584.94,699.08L560.97,708.98ZM441.51,708.98L463.03,708.98L439.06,699.08ZM538.47,696.52L537.2,708.98L562.82,697.2ZM485.53,696.52L461.18,697.2L486.8,708.98ZM560.97,708.98L562.82,697.2L537.2,708.98ZM463.03,708.98L486.8,708.98L461.18,697.2ZM607.44,702.13L600.69,708.98L622.17,710.86ZM416.55,702.13L401.81,710.86L423.31,708.98ZM610.68,710.61L622.17,710.86L600.69,708.98ZM413.32,710.61L423.31,708.98L401.81,710.86ZM512.02,682.22L512.02,695.53L539.77,682.19ZM512.02,682.22L484.23,682.19L512.02,695.53ZM538.47,696.52L539.77,682.19L512.02,695.53ZM485.53,696.52L512.02,695.53L484.23,682.19ZM512.02,695.53L512.02,708.96L538.47,696.52ZM512.02,695.53L485.53,696.52L512.02,708.96ZM537.2,708.98L538.47,696.52L512.02,708.96ZM486.8,708.98L512.02,708.96L485.53,696.52ZM539.52,721.54L565.23,721.54L539.61,711.96ZM484.48,721.54L484.39,711.96L458.77,721.54ZM564.57,711.96L539.61,711.96L565.23,721.54ZM459.43,711.96L458.77,721.54L484.39,711.96ZM539.56,735.09L566.16,732.99L539.52,721.54ZM484.44,735.09L484.48,721.54L457.84,732.99ZM565.23,721.54L539.52,721.54L566.16,732.99ZM458.77,721.54L457.84,732.99L484.48,721.54ZM540.34,753.9L568.49,748.33L539.56,735.09ZM483.66,753.9L484.44,735.09L455.51,748.33ZM566.16,732.99L539.56,735.09L568.49,748.33ZM457.84,732.99L455.51,748.33L484.44,735.09ZM613.64,697.41L607.44,702.13L626.58,710.62ZM410.36,697.41L397.42,710.62L416.55,702.13ZM622.17,710.86L626.58,710.62L607.44,702.13ZM401.81,710.86L416.55,702.13L397.42,710.62ZM613.64,697.41L626.58,710.62L622.18,693.97ZM410.36,697.41L401.82,693.97L397.42,710.62ZM632.86,711.38L622.18,693.97L626.58,710.62ZM391.14,711.38L397.42,710.62L401.82,693.97Z" fill="#e85d75" fill-opacity="0.08" stroke="#94a3b8" stroke-width="1.28" stroke-linejoin="round"/><path d="M610.68,710.61L600.69,708.98L600.88,712.09ZM413.32,710.61L423.12,712.09L423.31,708.98ZM511.98,711.96L539.61,711.96L512.02,708.96ZM511.98,711.96L512.02,708.96L484.39,711.96ZM537.2,708.98L512.02,708.96L539.61,711.96ZM486.8,708.98L484.39,711.96L512.02,708.96ZM539.61,711.96L564.57,711.96L537.2,708.98ZM484.39,711.96L486.8,708.98L459.43,711.96ZM560.97,708.98L537.2,708.98L564.57,711.96ZM463.03,708.98L459.43,711.96L486.8,708.98ZM564.57,711.96L585.79,711.96L560.97,708.98ZM459.43,711.96L463.03,708.98L438.21,711.96ZM582.49,708.98L560.97,708.98L585.79,711.96ZM441.51,708.98L438.21,711.96L463.03,708.98ZM585.79,711.96L600.88,712.09L582.49,708.98ZM438.21,711.96L441.51,708.98L423.12,712.09ZM600.69,708.98L582.49,708.98L600.88,712.09ZM423.31,708.98L423.12,712.09L441.51,708.98Z" fill="#2563eb" fill-opacity="0.25" stroke="none"/><polygon points="391.14,711.38 405.61,727.26 428.35,737.34 455.51,748.33 483.66,753.9 511.98,754.71 540.34,753.9 568.49,748.33 595.65,737.34 618.39,727.26 632.86,711.38 622.18,693.97 599.43,682.54 573.66,673 540.93,666.01 511.98,668.19 483.07,666.01 450.34,673 424.57,682.54 401.82,693.97" fill="none" stroke="#e85d75" stroke-width="2.56" stroke-linejoin="round"/><polygon points="413.32,710.61 423.12,712.09 438.21,711.96 459.43,711.96 484.39,711.96 511.98,711.96 539.61,711.96 564.57,711.96 585.79,711.96 600.88,712.09 610.68,710.61 600.69,708.98 582.49,708.98 560.97,708.98 537.2,708.98 512.02,708.96 486.8,708.98 463.03,708.98 441.51,708.98 423.31,708.98" fill="none" stroke="#2563eb" stroke-width="2.56" stroke-dasharray="7.68 5.12" stroke-linejoin="round"/><text x="378.85" y="710.36" text-anchor="end" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" font-size="16.38" fill="#0f172a">subject's RIGHT ▸</text><text x="645.15" y="710.36" text-anchor="start" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" font-size="16.38" fill="#0f172a">◂ subject's LEFT</text><text x="512" y="653.73" text-anchor="middle" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" font-size="16.38" fill="#0f172a">upper lip  (outer ring = painted edge)</text><text x="512" y="783.38" text-anchor="middle" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" font-size="16.38" fill="#0f172a">lower lip  ·  dashed ring = mouth interior, hidden in outer-and-inner-lips mode</text><text x="512" y="804.68" text-anchor="middle" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" font-size="16.38" fill="#0f172a">lip region: u 0.38–0.62, v 0.26–0.35  (image x 38–62%, y 65–74%)</text><text x="25.6" y="41.98" text-anchor="start" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" font-size="16.38" fill="#0f172a" font-weight="bold">Lip UV template — canonical face UV atlas</text><text x="25.6" y="63.28" text-anchor="start" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" font-size="16.38" fill="#0f172a">1024×1024 canvas, same layout as Canonical_Face_Color.png.</text><text x="25.6" y="84.58" text-anchor="start" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" font-size="16.38" fill="#0f172a">Only the lip triangles are sampled; transparent pixels leave the skin untouched.</text><text x="25.6" y="105.88" text-anchor="start" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" font-size="16.38" fill="#0f172a">Image LEFT = subject's RIGHT (screen-right on a mirrored webcam view).</text><text x="25.6" y="998.4" text-anchor="start" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" font-size="16.38" fill="#0f172a">generated from canonical_face_model.obj uv attributes</text></svg>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vincentt-xr/sdk",
-  "version": "2.0.0-alpha.7",
+  "version": "2.0.0-alpha.8",
   "description": "XR SDK by Vincentt",
   "repository": {
     "type": "git",
@@ -63,6 +63,11 @@
       "import": "./dist/internal.js",
       "require": "./dist/internal.cjs"
     },
+    "./product": {
+      "types": "./dist/entries/product.d.ts",
+      "import": "./dist/product.js",
+      "require": "./dist/product.cjs"
+    },
     "./debug-ui": {
       "types": "./dist/debug-ui/index.d.ts",
       "import": "./dist/debug-ui.js",
@@ -80,6 +85,7 @@
     }
   },
   "peerDependencies": {
+    "@google/model-viewer": "^4.0.0",
     "@mediapipe/tasks-vision": "^0.10.18",
     "@react-three/drei": "9.105.6",
     "@react-three/fiber": "8.18.0",
@@ -89,6 +95,9 @@
     "three": "0.173.0"
   },
   "peerDependenciesMeta": {
+    "@google/model-viewer": {
+      "optional": true
+    },
     "@mediapipe/tasks-vision": {
       "optional": false
     },
@@ -98,7 +107,9 @@
   },
   "devDependencies": {
     "@eslint/js": "^9.14.0",
+    "@google/model-viewer": "4.0.0",
     "@mdx-js/rollup": "^3.1.1",
+    "@playwright/test": "1.47.2",
     "@testing-library/dom": "^10",
     "@testing-library/react": "^16",
     "@types/node": "^22.9.0",
@@ -156,6 +167,7 @@
     "format:check": "prettier --check 'lib/**/*.{ts,tsx}' 'example/**/*.{ts,tsx}' '*.{json,md,mjs,ts}' '.github/**/*.{md,yml}' 'docs/**/*.{md,mdx,json}'",
     "format": "prettier --write 'lib/**/*.{js,jsx,ts,tsx}' 'example/**/*.{js,jsx,ts,tsx}'",
     "test": "vitest run",
+    "smoke": "playwright test",
     "test:watch": "vitest",
     "lint:check": "eslint lib --max-warnings 0",
     "example:build": "vite build --config example/vite.config.ts",