@vincentt-xr/sdk 2.0.0-alpha.4 → 2.0.0-alpha.5

package/README.md

@@ -1,85 +1,118 @@
-# RTX AR Tracking SDK
+# Vincentt XR SDK
 
-This SDK is intended for implementing AI-powered tracking for WebAR projects by rangoon.tech.
+`@vincentt-xr/sdk` is the AR runtime for Vincentt projects. It gives a React +
+react-three-fiber app a camera session, face/hand/body tracking, and the
+screen-space layout primitives that most AR effects are built from.
 
-## Installation
-First, install the library by running the command
+Your JSX renders directly — in local preview and in the published bundle at
+`<slug>.vincentt.app`.
+
+## Install
+
+The SDK is installed for you when you scaffold a project from the Vincentt
+template, which pins a known-good version alongside its peers:
 
 ```
-npm install @rangoon/track
+vincentt create my-app
 ```
 
-If you're using yarn,
+To add it to an existing project:
 
 ```
-yarn add @rangoon/track
+pnpm add @vincentt-xr/sdk
 ```
 
-## How to use
-The usage of `@rangoon/track` usually involves two steps.
+It expects `react`, `react-dom`, `three`, `@react-three/fiber`,
+`@react-three/drei`, and `@mediapipe/tasks-vision` as peers. The template
+already pins compatible versions of all of them; mismatched copies of React or
+three.js are the most common source of runtime errors.
 
-### 1. Start a video stream
-Initialize the SDK by attaching the `@rangoon/track`'s `Webcam` component to your React Project. 
-The `Webcam` component will start a video stream which will be used for tracking. 
+## Quick start
 
-```ts
-import { Webcam } from "@rangoon/track"
-import { useRef } from "react"
+Wrap your app in `XRProvider`, mount an `XRScene`, and add content. Trackers
+self-register when mounted — there is no pipeline to wire up by hand.
 
-function App() {
+```tsx
+import { ScreenSpaceUI, ScreenText, XRProvider, XRScene } from "@vincentt-xr/sdk";
+import { useFaceDetection } from "@vincentt-xr/sdk/tracking";
 
-  const videoRef = useRef<HTMLVideoElement>(null)
+function Effect() {
+  const detection = useFaceDetection({ numFaces: 1 });
+
+  if (detection.face) return null;
 
   return (
-    <div>
-      <Webcam videoReference={videoRef}/>
-    </div>
-  )
+    <ScreenSpaceUI>
+      <ScreenText
+        text="SHOW A FACE TO THE CAMERA"
+        screenTransform={{ position: { x: 0, y: 0 }, size: { width: 400, height: 52 } }}
+        fontSize={24}
+      />
+    </ScreenSpaceUI>
+  );
 }
 
-export default App
-
+export default function App() {
+  return (
+    <XRProvider>
+      <XRScene>
+        <Effect />
+      </XRScene>
+    </XRProvider>
+  );
+}
 ```
 
-### 2. Initiate a tracking model
+## Import doors
 
-Currently, `@rangoon/track` supports three types of tracking models.
-* Hand Tracking (Landmarks)
-* Hand Gesture Tracking (Landmarks + Gestures)
-* Face Tracking
+The API is split by task domain. Import each symbol from the door that owns it.
 
-By calling the Hook associated with the respective model, you can obtain the tracking data.
+| Entry point                      | What lives there                                                                |
+| -------------------------------- | ------------------------------------------------------------------------------- |
+| `@vincentt-xr/sdk`               | Providers, scene root, screen-space layout, renderers, text, capture, audio       |
+| `@vincentt-xr/sdk/tracking`      | Face / hand / gesture / body / segmentation trackers, anchors, triggers            |
+| `@vincentt-xr/sdk/face-effects`  | Face mesh materials, retouch, canonical mesh, head binding                        |
+| `@vincentt-xr/sdk/scene-object`  | Scene-object types, factories, selectors, immutable store operations              |
+| `@vincentt-xr/sdk/low-level`     | Raw model-node reads and custom-tracker plumbing — the escape hatch               |
+| `@vincentt-xr/sdk/debug-ui`      | Dev-only inspector panels; not for shipping surfaces                              |
 
-Below is an example of obtaining hand-tracking data with `useHandTracking` Hook.
-```ts
-import { Webcam, useHandTracking } from "@rangoon/track"
-import { useEffect, useRef } from "react"
+## Documentation
 
-function App() {
+**[`GROUNDING.md`](./GROUNDING.md) is the authoritative API reference** — every
+component, hook, and prop, plus the composition conventions. Read it before
+reaching into `node_modules` or inventing props. It ships inside the package, so
+it travels with the version you actually installed.
 
-  const videoRef = useRef<HTMLVideoElement>(null)
+Longer-form guides live in [`docs/`](./docs):
 
-  //Initiate the model by passing the webcam reference
-  const handData = useHandTracking({
-    videoReference: videoRef
-  })
+- [`docs/introduction.mdx`](./docs/introduction.mdx) — the scene-object authoring model
+- [`docs/guides/`](./docs/guides) — task guides
+- [`docs/api/`](./docs/api) — API pages
+- [`docs/MIGRATION_GUIDE.md`](./docs/MIGRATION_GUIDE.md) — upgrading from 1.x
 
-  //Watch the data changes with useEffect
-  useEffect(() => {
-    console.log(handData)
-  }, [handData])
+## Local development
 
-  return (
-    <div>
-      <Webcam videoReference={videoRef}/>
-    </div>
-  )
-}
-
-export default App
 ```
+pnpm install
+pnpm dev            # example app
+pnpm preview:tunnel # example app, reachable on a phone
+pnpm build
+pnpm test
+pnpm typecheck
+```
+
+The example app under `example/` is the development surface for the SDK itself.
+Experiments start there; once one becomes a real app it graduates to its own
+repo built against the packaged SDK.
+
+Release steps are in [`RELEASING.md`](./RELEASING.md).
+
+## License
 
+Proprietary. See [`LICENSE`](./LICENSE) — the published package is for use with
+the Vincentt platform only.
 
 ## Feedback
 
-If you have any feedback, please reach out to us at waing@rangoon.tech
+Report friction and bugs to the Vincentt team through the beta reporting flow,
+or open an issue on this repository.

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@vincentt-xr/sdk",
-  "version": "2.0.0-alpha.4",
+  "version": "2.0.0-alpha.5",
   "description": "XR SDK by Vincentt",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/rangoon-x/vincentt-xr-sdk.git"
+    "url": "git+https://github.com/vincentt-xr/sdk.git"
   },
   "license": "UNLICENSED",
   "keywords": [