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

package/docs/api/runtime-3d.mdx

@@ -0,0 +1,311 @@
+---
+title: "Runtime 3D API"
+description: "Core runtime components for serialized 3D scene objects: Transform3D, MeshRenderer, LightObject, LookAt, PinToMesh, VideoBackground, and SceneObjectRenderer."
+sidebarTitle: "Runtime 3D"
+icon: "cube"
+---
+
+Import runtime components from `@vincentt-xr/sdk`.
+
+```tsx
+import {
+  DEFAULT_MESH_RENDERER,
+  DEFAULT_MESH_RENDERER_RENDER_STATE,
+  LightObject,
+  LookAt,
+  MeshRenderer,
+  PinToMesh,
+  SceneObjectRenderer,
+  Transform3D,
+  VideoBackground,
+} from "@vincentt-xr/sdk";
+```
+
+`DEFAULT_MESH_RENDERER` and `DEFAULT_MESH_RENDERER_RENDER_STATE` are exported
+for serialized scene construction and editor defaults.
+
+## `Transform3D`
+
+Applies authored 3D transform state to its children.
+
+```ts
+type Transform3DSettings = {
+  enabled: boolean;
+  visible: boolean;
+  position: { x: number; y: number; z: number };
+  rotation: { x: number; y: number; z: number }; // degrees
+  scale: { x: number; y: number; z: number };
+  showTransformControls?: boolean;
+  transformControlMode?: "translate" | "rotate" | "scale";
+  transformControlSpace?: "local" | "world";
+};
+```
+
+```tsx
+<Transform3D value={transformSettings} onChange={setTransformSettings}>
+  <MeshRenderer value={meshRendererSettings} />
+</Transform3D>
+```
+
+## `MeshRenderer`
+
+Renders a primitive mesh or GLTF/GLB asset.
+
+```ts
+type MeshRendererSettings = {
+  enabled: boolean;
+  visible: boolean;
+  mesh: "cube" | "sphere" | "plane";
+  assetUrl?: string;
+  assetNodeName?: string;
+  material: {
+    type: "standard" | "basic";
+    color: string;
+    opacity: number;
+    wireframe: boolean;
+    roughness: number;
+    metalness: number;
+    renderState?: Partial<MeshRendererRenderState>;
+  };
+  shadowMode: "off" | "cast" | "receive" | "castReceive";
+};
+```
+
+```tsx
+<MeshRenderer
+  value={{
+    ...DEFAULT_MESH_RENDERER,
+    mesh: "plane",
+    material: {
+      ...DEFAULT_MESH_RENDERER.material,
+      color: "#1b2733",
+      renderState: {
+        depthTest: true,
+        depthWrite: true,
+        cullMode: "off",
+      },
+    },
+    shadowMode: "receive",
+  }}
+/>
+```
+
+### `MeshRendererRenderState`
+
+Render-state fields map to Three.js material or scoped WebGL draw state.
+
+```ts
+type MeshRendererRenderState = {
+  depthTest: boolean;
+  depthWrite: boolean;
+  depthFunc:
+    | "never"
+    | "less"
+    | "equal"
+    | "lessEqual"
+    | "greater"
+    | "notEqual"
+    | "greaterEqual"
+    | "always";
+  colorWrite: boolean;
+  colorMask: { r: boolean; g: boolean; b: boolean; a: boolean };
+  cullMode: "back" | "front" | "off";
+  blendMode: "normal" | "additive" | "subtractive" | "multiply" | "none";
+  polygonOffset: {
+    enabled: boolean;
+    factor: number;
+    units: number;
+  };
+};
+```
+
+Defaults preserve standard Three.js behavior:
+
+```ts
+{
+  depthTest: true,
+  depthWrite: true,
+  depthFunc: "lessEqual",
+  colorWrite: true,
+  colorMask: { r: true, g: true, b: true, a: true },
+  cullMode: "back",
+  blendMode: "normal",
+  polygonOffset: { enabled: false, factor: 0, units: 0 },
+}
+```
+
+Notes:
+
+- `wireframe` belongs to material state, not geometry state.
+- `colorMask` is per-channel RGBA write control. It is applied around each mesh
+  draw and restored after render.
+- GLTF materials are cloned before SDK material overrides are applied.
+- `instanceCount` is not material state; it belongs to a future instanced-mesh
+  API.
+
+## `VideoBackground`
+
+Renders the camera feed as a flat background. It intentionally does not expose
+depth-test/depth-write props.
+
+```tsx
+<VideoBackground
+  segmentationMask={maskTexture}
+  segmentation="portrait"
+  customBackground="#6366f1"
+  renderOrder={-999}
+/>
+```
+
+Use the debug-ui `XRSceneViewport` when the camera feed should behave as a real
+3D plane in an editor. That viewport owns a separate depth-writing
+camera-texture plane without changing `VideoBackground` semantics.
+
+## `LightObject`
+
+Renders a light from serialized settings plus a `Transform3D` position/rotation.
+
+```ts
+type LightSettings = {
+  enabled: boolean;
+  type: "ambient" | "directional" | "point" | "spot";
+  color: string;
+  intensity: number;
+  castShadow: boolean;
+  distance: number;
+  angle: number;
+  penumbra: number;
+  decay: number;
+  showHelper: boolean;
+};
+```
+
+Default `showHelper` is `false`; editor pages can enable it explicitly.
+
+## `LookAt`
+
+Partial-stage behavior component. Rotates its child toward a target object.
+
+```ts
+type LookAtSettings = {
+  enabled: boolean;
+  targetObjectId: string | null;
+  mode: "point" | "direction";
+  inheritChildren: boolean;
+  offsetRotation: { x: number; y: number; z: number };
+};
+```
+
+```tsx
+<LookAt target={targetObject} settings={lookAtSettings}>
+  <MeshRenderer value={meshRendererSettings} />
+</LookAt>
+```
+
+In `SceneObjectRenderer`, nested child objects do not inherit the parent's
+LookAt rotation by default. Set `inheritChildren: true` when children should
+rigidly follow the parent's look-at facing.
+
+## `PinToMesh`
+
+Partial-stage behavior component. Pins a runtime wrapper to a target mesh
+surface.
+
+```ts
+type PinToMeshSettings = {
+  enabled: boolean;
+  targetObjectId: string | null;
+  orientation: "none" | "position" | "positionAndDirection";
+  uv: { x: number; y: number };
+  vertexNormal: boolean;
+  offsetSpace: "local" | "world";
+  offsetPosition: { x: number; y: number; z: number };
+  offsetRotation: { x: number; y: number; z: number };
+};
+```
+
+Default values:
+
+```ts
+{
+  enabled: false,
+  targetObjectId: null,
+  orientation: "none",
+  uv: { x: 0.5, y: 0.5 },
+  vertexNormal: false,
+  offsetSpace: "local",
+  offsetPosition: { x: 0, y: 0, z: 0 },
+  offsetRotation: { x: 0, y: 0, z: 0 },
+}
+```
+
+Runtime behavior:
+
+- Disabled PinToMesh resets its wrapper to local position `0,0,0` and identity
+  rotation.
+- Missing target also resets the wrapper.
+- `Transform3D` remains the authored transform source of truth.
+- `orientation: "positionAndDirection"` aligns to the target surface normal.
+- `offsetRotation` is reapplied from a clean base each frame; it must not
+  compound.
+
+```tsx
+<PinToMesh target={targetObject} settings={pinToMeshSettings}>
+  <Transform3D value={transformSettings}>
+    <MeshRenderer value={meshRendererSettings} />
+  </Transform3D>
+</PinToMesh>
+```
+
+## `SceneObjectRenderer`
+
+Renders serialized scene-object data through runtime components.
+
+```ts
+type SceneObjectRendererProps = {
+  objectId: string;
+  store: SceneObjectStore;
+  editorMode?: boolean;
+  renderOrder?: number;
+  renderLayer?: number;
+  onComponentChange?: (component: SceneComponent) => void;
+  fallback?: (message: string) => ReactNode;
+};
+```
+
+Supported combinations:
+
+| Components                                 | Runtime result                  |
+| ------------------------------------------ | ------------------------------- |
+| `Transform`                                | invisible 3D null/container     |
+| `Transform` + `MeshRenderer`               | 3D object                       |
+| `Transform` + `MeshRenderer` + `LookAt`    | 3D object with look-at behavior |
+| `Transform` + `MeshRenderer` + `PinToMesh` | 3D object with pin behavior     |
+| `Transform` + `Light`                      | light object                    |
+| `ScreenTransform`                          | invisible 2D null/container     |
+| `ScreenTransform` + `ScreenImage`          | screen image                    |
+| `ScreenTransform` + `ScreenText`           | screen text                     |
+
+Nested scene objects are resolved from `SceneObjectStore` data. Root objects
+come from `createRenderPlan`; children are rendered recursively inside their
+parent runtime object, so child transforms inherit parent transforms.
+
+## `ScreenImage` architecture and ownership
+
+`ScreenImage` is a thin screen-space orchestrator. Its implementation is split
+by responsibility:
+
+- `components/ScreenImageBody.tsx` owns the cloned UV texture and generated
+  matcap, selects unlit/PBR/matcap/advanced-blend materials, and renders the
+  core mesh.
+- `components/ScreenImageFrame.tsx` resolves anchor-based layout.
+- `components/ScreenImageTransformFrame.tsx` owns editor drag listeners,
+  transform math, and guide rendering.
+- `materials/` contains GLSL blend materials and procedural matcap generation.
+- `source.ts`, `fit.ts`, `types.ts`, and `utils/` contain reusable pure models,
+  source resolution, fitting, defaults, and mapping helpers.
+
+Consumer-provided textures remain consumer-owned and are never disposed by
+`ScreenImage`. Internally cloned UV textures and generated matcaps are disposed
+on replacement or unmount. Dynamic video/canvas textures keep their per-frame
+update behavior.

package/docs/api/scene-object-store.mdx

@@ -0,0 +1,213 @@
+---
+title: "Scene Object Store API"
+description: "Definitions and helpers for serialized scene data, components, defaults, and immutable store updates."
+sidebarTitle: "Scene Object Store"
+icon: "database"
+---
+
+Import scene-object APIs from `@vincentt-xr/sdk/scene-object`.
+
+Internal source layout: scene-object store helpers stay in `lib/scene-object/`;
+render-group helpers live in `lib/render/`; serialized `ScreenImage` and
+`ScreenText` settings live in `lib/screen-image/` and `lib/screen-text/`. Public
+imports stay unchanged.
+
+```ts
+import {
+  createRenderPlan,
+  createDefaultComponent,
+  createSceneObject,
+  migrateToRenderGroups,
+  moveObjectToGroup,
+  replaceSceneComponent,
+  replaceSceneObject,
+  reorderObjectWithinGroup,
+  reorderRenderGroup,
+  setSceneObjectVisible,
+  validateGroupCompatibility,
+  type RenderGroupSceneObjectStore,
+  type SceneObjectStore,
+} from "@vincentt-xr/sdk/scene-object";
+```
+
+## Core types
+
+```ts
+type SceneObject = {
+  id: string;
+  name: string;
+  enabled: boolean;
+  parentObjectId?: string | null;
+  childObjectIds?: string[];
+  renderGroupId?: string;
+  componentIds: string[];
+};
+
+type SceneComponent<TType extends SceneComponentType = SceneComponentType> = {
+  id: string;
+  objectId: string;
+  type: TType;
+  enabled: boolean;
+  settings: ComponentRegistry[TType];
+};
+
+type SceneObjectStore = {
+  objects: Record<string, SceneObject>;
+  components: Record<string, SceneComponent>;
+};
+```
+
+## `ComponentRegistry`
+
+```ts
+type ComponentRegistry = {
+  Transform: Transform3DSettings;
+  ScreenTransform: ScreenTransform2DSettings;
+  ScreenImage: ScreenImageSettings;
+  ScreenText: ScreenTextSettings;
+  MeshRenderer: MeshRendererSettings;
+  FaceMeshRenderer: FaceMeshRendererSettings;
+  Material: MaterialSettings;
+  Texture: TextureSettings;
+  Light: LightSettings;
+  LookAt: LookAtSettings;
+  PinToMesh: PinToMeshSettings;
+};
+```
+
+## Create an object
+
+```ts
+const object = createSceneObject({
+  id: "mic",
+  name: "Mic",
+  renderGroupId: "scene3d",
+});
+
+const transform = createDefaultComponent("Transform", object.id);
+const meshRenderer = createDefaultComponent("MeshRenderer", object.id);
+
+const store: SceneObjectStore = {
+  objects: {
+    [object.id]: {
+      ...object,
+      componentIds: [transform.id, meshRenderer.id],
+    },
+  },
+  components: {
+    [transform.id]: transform,
+    [meshRenderer.id]: meshRenderer,
+  },
+};
+```
+
+## Default components
+
+```ts
+createDefaultComponent("Transform", objectId);
+createDefaultComponent("MeshRenderer", objectId);
+createDefaultComponent("FaceMeshRenderer", objectId);
+createDefaultComponent("Light", objectId);
+createDefaultComponent("LookAt", objectId);
+createDefaultComponent("PinToMesh", objectId);
+createDefaultComponent("ScreenTransform", objectId);
+createDefaultComponent("ScreenImage", objectId);
+createDefaultComponent("ScreenText", objectId);
+```
+
+Defaults are cloned before return, so callers can safely mutate the returned
+settings while constructing serialized scene data.
+
+Null/container objects are component combinations, not separate runtime classes:
+
+```ts
+// 3D null/container
+const transform = createDefaultComponent("Transform", object.id);
+
+// 2D null/container
+const screenTransform = createDefaultComponent("ScreenTransform", object.id);
+```
+
+They render no visible mesh/text/image by themselves, but they can parent child
+objects and expose their transform in the debug inspector.
+
+## Immutable updates
+
+Use these helpers when wiring inspectors or editor panels.
+
+```ts
+setStore((current) => replaceSceneComponent(current, nextComponent));
+setStore((current) => replaceSceneObject(current, nextObject));
+setStore((current) => setSceneObjectVisible(current, objectId, false));
+setStore((current) => setSceneObjectParent(current, "child", "parent"));
+```
+
+Rules:
+
+- component edits flow through `replaceSceneComponent`
+- object name/enabled/render-group edits flow through `replaceSceneObject`
+- hierarchy visibility edits flow through `setSceneObjectVisible`
+- hierarchy parent edits flow through `setSceneObjectParent`
+- editor panels should not keep separate transform/material/light/pin state
+
+## Nested scene objects
+
+3D and 2D scene objects can be nested with `parentObjectId` and
+`childObjectIds`. A child transform is local to its parent transform: the child
+can still move freely, and moving/rotating/scaling the parent affects all
+descendants. Parenting does not rewrite the child's Transform component; the
+existing Transform values become the child's local offset from the parent. A
+child with position `{ x: 0, y: 0, z: 0 }` sits at the parent origin.
+
+```ts
+const next = setSceneObjectParent(store, "mic", "emoji");
+```
+
+`setSceneObjectParent` updates both sides of the relationship, preserves
+ordering through `childObjectIds`, rejects cycles, and does not preserve world
+position by rewriting Transform values. `createRenderPlan` emits only root
+objects; `SceneObjectRenderer` renders children inside their parent runtime
+object so inherited transforms work.
+
+Editor-style parent changes should use
+`setSceneObjectParentPreserveWorldTransform`. That helper updates the hierarchy
+and recalculates the child's local Transform so the object does not visually
+jump at the moment it is nested or un-nested.
+
+## Render-group store
+
+Grouped scene editors use `RenderGroupSceneObjectStore`.
+
+```ts
+type RenderGroupSceneObjectStore = SceneObjectStore & {
+  renderGroups: Record<string, RenderGroup>;
+  renderGroupOrder: string[];
+};
+```
+
+Use `createRenderPlan(store)` to derive render entries for
+`SceneObjectRenderer`.
+
+```ts
+const grouped: RenderGroupSceneObjectStore = migrateToRenderGroups(store);
+const plan = createRenderPlan(grouped);
+```
+
+Common render-group helpers:
+
+```ts
+reorderRenderGroup(grouped, "scene3d", 0);
+reorderObjectWithinGroup(grouped, "scene3d", "mic", 1);
+
+if (validateGroupCompatibility(grouped, "mic", "scene3d")) {
+  moveObjectToGroup(grouped, "mic", "scene3d", 0);
+}
+```
+
+`createRenderPlan` returns entries with `objectId`, `renderOrder`, and
+`renderLayer`. Feed those entries to `SceneObjectRenderer` and derive pass layers
+from the plan:
+
+```ts
+const passLayers = Array.from(new Set(plan.map((entry) => entry.renderLayer)));
+```

package/docs/api/screen-image.mdx

@@ -0,0 +1,41 @@
+---
+title: "Screen Image"
+description: "Author screen-space images with shared transforms, fitting, materials, and editor settings."
+sidebarTitle: "Screen Image"
+icon: "image"
+---
+
+Use `ScreenImage` for logos, stickers, frames, badges, and photo placeholders.
+It owns its screen transform; prefer `position`, `size`, and `rotation` for
+normal authoring.
+
+```tsx
+import { ScreenImage, ScreenSpaceUI } from "@vincentt-xr/sdk";
+
+<ScreenSpaceUI>
+  <ScreenImage
+    name="logo"
+    source={{ kind: "image", src: logoUrl }}
+    coordinateSpace="canvas"
+    canvasSize={{ width: 720, height: 1280 }}
+    position={[-180, 464]}
+    size={[216, 160]}
+    stretchMode="fit"
+    opacity={0.95}
+  />
+</ScreenSpaceUI>;
+```
+
+Sources are `{ kind: "default" }`, `{ kind: "image", src }`, or an existing
+`{ kind: "texture", texture }`. `fit` supports `stretch`, `contain`, and
+`cover`. Canvas coordinates use center origin and positive Y upward.
+
+The authored size is the bounding rectangle, not the image's natural size.
+Fit changes content inside that rectangle and never changes the rigid
+transform. Keep visibility, opacity, tint, flips, pivot, overlay, render order,
+transparency, alpha test, position, size, and rotation in one source of truth.
+
+For scene objects, combine `ScreenTransform` + `ScreenImage` and use
+`mapScreenImageSettingsToProps`. Use `ScreenImageSettingsPanel` from
+`@vincentt-xr/sdk/debug-ui`; wire `onScreenTransformChange` so drag editing
+updates the same mounted object.

package/docs/api/screen-shape.mdx

@@ -0,0 +1,64 @@
+---
+title: "Screen Shape"
+description: "Verified screen-space vector shapes with solid, gradient, and glass fills."
+sidebarTitle: "Screen Shape"
+icon: "shapes"
+---
+
+`ScreenShape` renders editable vector primitives in SDK design pixels. Use it
+instead of generating raster assets for circles, ellipses, rectangles, rounded
+rectangles, polygons, stars, and lines.
+
+```tsx
+import { ScreenShape, ScreenSpaceUI } from "@vincentt-xr/sdk";
+
+<ScreenSpaceUI>
+  <ScreenShape
+    transform={{ position: { x: 0, y: 0 }, size: { width: 220, height: 220 } }}
+    settings={{
+      kind: "star",
+      fillMode: "gradient",
+      fillOpacity: 0.9,
+      gradient: {
+        type: "angular",
+        stops: [
+          { offset: 0, color: "#fb7185" },
+          { offset: 0.5, color: "#8b5cf6" },
+          { offset: 1, color: "#38bdf8" },
+        ],
+      },
+      strokeColor: "#ffffff",
+      strokeWidth: 3,
+      sides: 5,
+      innerRadiusRatio: 0.45,
+    }}
+  />
+</ScreenSpaceUI>;
+```
+
+## Settings
+
+- `kind`: `circle`, `ellipse`, `rectangle`, `roundedRectangle`, `polygon`,
+  `star`, or `line`
+- `fillMode`: `solid`, `gradient`, or `glass`
+- `fillColor`, `fillOpacity`, `strokeColor`, `strokeOpacity`, `strokeWidth`
+- `cornerRadius`, `sides`, `innerRadiusRatio`, and `dashed`
+- normalized `lineStart` and `lineEnd` coordinates for lines
+
+Regular circles, polygons, and stars preserve equal axes in non-square bounds.
+Ellipses and rectangles fill their bounds.
+
+## Gradient and glass
+
+Gradients support `linear`, `radial`, and `angular` (conic) modes with 2–8
+color stops. Configure `angle`, `center`, and `radius` as needed. The reusable
+`ScreenGradientMaterial` and `normalizeScreenGradient` exports live in core.
+
+Glass uses `tint`, `opacity`, `frost`, and `highlight`. It is a lightweight
+translucent shader, not backdrop blur or refraction. `fillOpacity` multiplies
+the glass opacity. The reusable `ScreenGlassMaterial` is also exported from
+core.
+
+For serialized scenes, pair `ScreenTransform` with `ScreenShape`. Use
+`ScreenShapeSettingsPanel` from `@vincentt-xr/sdk/debug-ui` for live editing.
+The verified example is `/screen-shapes`.

package/docs/api/screen-space-coordinates.mdx

@@ -0,0 +1,41 @@
+---
+title: "Screen-Space Coordinates"
+description: "Convert between SDK design pixels, normalized points, media, DOM clients, rays, and world positions."
+sidebarTitle: "Screen Coordinates"
+icon: "ruler"
+---
+
+Import screen-coordinate helpers from `@vincentt-xr/sdk`. SDK screen pixels use
+a `720x1280` design canvas by default, center origin, and positive Y upward.
+They are not Three.js world units.
+
+```ts
+import {
+  clientToScreenPixels,
+  normalizedToScreenPixels,
+  screenPixelsToUnits,
+  screenPointToRay,
+  screenUnitsToPixels,
+  worldToScreenPixels,
+} from "@vincentt-xr/sdk";
+
+const units = screenPixelsToUnits(120, { parentSize });
+const pixels = screenUnitsToPixels(units, { parentSize });
+const label = worldToScreenPixels({ point: worldPoint, camera, viewportSize });
+const ray = screenPointToRay({ point: tapPoint, camera, viewportSize });
+```
+
+- `clientToScreenPixels` / `screenPixelsToClient`: pointer events and DOM overlays
+- `normalizedToScreenPixels` / `screenPixelsToNormalized`: top-left-origin normalized points
+- `mediaToScreenPixels` / `screenPixelsToMedia`: cover/contain layout and mirroring
+- `worldToScreenPixels`: labels and indicators over tracked 3D points
+- `screenPointToRay`: hit testing and 3D placement from design pixels
+- `smoothNumber`, `smoothVector2`, `smoothVector3`: frame-rate-independent tracked motion
+
+Hide world projections whose `depth` is outside `[-1, 1]`. Reuse optional output
+vectors inside frame loops. Use Three.js `localToWorld`, `worldToLocal`,
+`project`, and `unproject` directly instead of adding SDK wrappers.
+
+Use `mergeScreenTransform2D` to fill defaults and `resolveScreenTransform2D` to
+resolve authored position, size, scale, rotation, and pivot. Do not copy the
+default root size or reference-pixel constants into custom renderers.