@realnation/builder-shared-sdk 1.0.4 → 1.1.0

package/dist/runtime/vue/index.d.ts

@@ -0,0 +1,26 @@
+import type { Ref } from 'vue';
+import type { CreateRuntimeOptions, Runtime } from '../index.js';
+import type { ConnectStatus } from '../capability.js';
+import type { ReactivePlayer } from './player.js';
+export { createPlayerHandle, PLAYER_JOINTS } from './player.js';
+export type { ReactivePlayer, ReactiveJoint, PlayerHandle } from './player.js';
+/**
+ * Attaches a reactive player facade to an existing runtime and disposes it when
+ * the component unmounts. Call inside setup().
+ */
+export declare function useRuntimePlayer(runtime: Runtime): ReactivePlayer;
+export interface UseRuntimeResult {
+    runtime: Runtime;
+    /** Null until connect() resolves; then the runtime's verdict. */
+    status: Ref<ConnectStatus | null>;
+    player: ReactivePlayer;
+    connect: () => Promise<ConnectStatus>;
+}
+/**
+ * Creates a runtime, a player facade, and ties both to the component lifetime.
+ *
+ * `status` is a shallowRef because it is replaced wholesale on each handshake —
+ * unlike the player, whose deep fields are mutated in place every frame.
+ */
+export declare function useRuntime(options?: CreateRuntimeOptions): UseRuntimeResult;
+//# sourceMappingURL=index.d.ts.map

package/dist/runtime/vue/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/runtime/vue/index.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,KAAK,CAAC;AAE/B,OAAO,KAAK,EAAE,oBAAoB,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AACjE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEtD,OAAO,KAAK,EAAgB,cAAc,EAAE,MAAM,aAAa,CAAC;AAEhE,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAChE,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE/E;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,cAAc,CAIjE;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB,iEAAiE;IACjE,MAAM,EAAE,GAAG,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC;IAClC,MAAM,EAAE,cAAc,CAAC;IACvB,OAAO,EAAE,MAAM,OAAO,CAAC,aAAa,CAAC,CAAC;CACvC;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,OAAO,GAAE,oBAAyB,GAAG,gBAAgB,CAoB/E"}

package/dist/runtime/vue/index.js

@@ -0,0 +1,47 @@
+/**
+ * Vue 3 adapter for the runtime SDK.
+ *
+ * Import from '@realnation/builder-shared-sdk/runtime/vue'. The core SDK at
+ * '/runtime' has no framework dependency; everything Vue-specific is here.
+ *
+ * `vue` is an optional peerDependency — consumers that never import this
+ * subpath do not need it installed.
+ */
+import { onUnmounted, shallowRef } from 'vue';
+import { createRuntime } from '../index.js';
+import { createPlayerHandle } from './player.js';
+export { createPlayerHandle, PLAYER_JOINTS } from './player.js';
+/**
+ * Attaches a reactive player facade to an existing runtime and disposes it when
+ * the component unmounts. Call inside setup().
+ */
+export function useRuntimePlayer(runtime) {
+    const handle = createPlayerHandle(runtime);
+    onUnmounted(() => handle.dispose());
+    return handle.primary();
+}
+/**
+ * Creates a runtime, a player facade, and ties both to the component lifetime.
+ *
+ * `status` is a shallowRef because it is replaced wholesale on each handshake —
+ * unlike the player, whose deep fields are mutated in place every frame.
+ */
+export function useRuntime(options = {}) {
+    const runtime = createRuntime(options);
+    const status = shallowRef(null);
+    const handle = createPlayerHandle(runtime);
+    onUnmounted(() => {
+        handle.dispose();
+        runtime.close();
+    });
+    return {
+        runtime,
+        status,
+        player: handle.primary(),
+        connect: async () => {
+            const s = await runtime.connect();
+            status.value = s;
+            return s;
+        },
+    };
+}

package/dist/runtime/vue/player.d.ts

@@ -0,0 +1,49 @@
+import type { RuntimeFacade } from '../facade.js';
+export interface ReactiveJoint {
+    position: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    confidence: number;
+    valid: boolean;
+}
+export interface ReactivePlayer {
+    isTracked: boolean;
+    /** Which runtime player index this facade currently follows. */
+    index: number;
+    center: {
+        x: number;
+        y: number;
+    };
+    depth: number;
+    ts: number;
+    head: ReactiveJoint;
+    neck: ReactiveJoint;
+    leftShoulder: ReactiveJoint;
+    rightShoulder: ReactiveJoint;
+    leftElbow: ReactiveJoint;
+    rightElbow: ReactiveJoint;
+    leftHand: ReactiveJoint;
+    rightHand: ReactiveJoint;
+    leftHip: ReactiveJoint;
+    rightHip: ReactiveJoint;
+    leftKnee: ReactiveJoint;
+    rightKnee: ReactiveJoint;
+    leftFoot: ReactiveJoint;
+    rightFoot: ReactiveJoint;
+    [joint: string]: unknown;
+}
+export declare const PLAYER_JOINTS: readonly ["head", "neck", "leftShoulder", "rightShoulder", "leftElbow", "rightElbow", "leftHand", "rightHand", "leftHip", "rightHip", "leftKnee", "rightKnee", "leftFoot", "rightFoot"];
+export interface PlayerHandle {
+    /**
+     * The primary player. A STABLE reference: when the tracked player changes,
+     * the same object is repointed in place, so a component that captured it at
+     * setup() keeps working without re-fetching.
+     */
+    primary(): ReactivePlayer;
+    /** Stops updating the facade. */
+    dispose(): void;
+}
+export declare function createPlayerHandle(runtime: RuntimeFacade): PlayerHandle;
+//# sourceMappingURL=player.d.ts.map

package/dist/runtime/vue/player.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"player.d.ts","sourceRoot":"","sources":["../../../src/runtime/vue/player.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,aAAa,EAAe,MAAM,cAAc,CAAC;AAE/D,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9C,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,OAAO,CAAC;IACnB,gEAAgE;IAChE,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,aAAa,CAAC;IACpB,IAAI,EAAE,aAAa,CAAC;IACpB,YAAY,EAAE,aAAa,CAAC;IAC5B,aAAa,EAAE,aAAa,CAAC;IAC7B,SAAS,EAAE,aAAa,CAAC;IACzB,UAAU,EAAE,aAAa,CAAC;IAC1B,QAAQ,EAAE,aAAa,CAAC;IACxB,SAAS,EAAE,aAAa,CAAC;IACzB,OAAO,EAAE,aAAa,CAAC;IACvB,QAAQ,EAAE,aAAa,CAAC;IACxB,QAAQ,EAAE,aAAa,CAAC;IACxB,SAAS,EAAE,aAAa,CAAC;IACzB,QAAQ,EAAE,aAAa,CAAC;IACxB,SAAS,EAAE,aAAa,CAAC;IACzB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1B;AAED,eAAO,MAAM,aAAa,yLAIhB,CAAC;AAmDX,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,OAAO,IAAI,cAAc,CAAC;IAC1B,iCAAiC;IACjC,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,aAAa,GAAG,YAAY,CAgCvE"}

package/dist/runtime/vue/player.js

@@ -0,0 +1,95 @@
+/**
+ * The Game API: a reactive player facade.
+ *
+ * This is the ONLY file in the runtime SDK that imports 'vue'. Everything under
+ * src/runtime/ outside this directory is framework-free, so Canvas/WebGL games,
+ * tooling and non-Vue hosts can use the SDK without a reactivity system.
+ *
+ * ⚠️ This facade is for UI — scores, status text, debug panels. A game loop
+ * rendering at 30–60fps should subscribe to runtime.body.onUpdate() and draw
+ * from the raw data instead. Binding a skeleton into a Vue template makes Vue
+ * run dependency tracking and patching every frame, which is a natural but
+ * expensive mistake.
+ */
+import { reactive } from 'vue';
+export const PLAYER_JOINTS = [
+    'head', 'neck', 'leftShoulder', 'rightShoulder', 'leftElbow', 'rightElbow',
+    'leftHand', 'rightHand', 'leftHip', 'rightHip', 'leftKnee', 'rightKnee',
+    'leftFoot', 'rightFoot',
+];
+function blankJoint() {
+    return { position: { x: 0, y: 0, z: 0 }, confidence: 0, valid: false };
+}
+function blankPlayer() {
+    const p = {
+        isTracked: false,
+        index: -1,
+        center: { x: 0.5, y: 0.5 },
+        depth: 0,
+        ts: 0,
+    };
+    for (const name of PLAYER_JOINTS)
+        p[name] = blankJoint();
+    return p;
+}
+/**
+ * Copies a frame into the existing reactive tree.
+ *
+ * Assigns leaf fields only. Replacing `player.leftHand = {...}` would make Vue
+ * rebuild that proxy subtree every frame; at 60fps that is the difference
+ * between a facade you can leave mounted and one that shows up in a profile.
+ */
+function applyBody(player, body) {
+    player.isTracked = true;
+    player.index = body.player;
+    player.ts = body.ts;
+    if (body.center) {
+        player.center.x = body.center.x ?? player.center.x;
+        player.center.y = body.center.y ?? player.center.y;
+    }
+    if (typeof body.depth === 'number')
+        player.depth = body.depth;
+    for (const name of PLAYER_JOINTS) {
+        const target = player[name];
+        const src = body.skeleton?.[name];
+        if (!src) {
+            target.valid = false;
+            target.confidence = 0;
+            continue;
+        }
+        target.position.x = src.x;
+        target.position.y = src.y;
+        target.position.z = src.z;
+        target.confidence = src.c;
+        target.valid = src.valid;
+    }
+}
+export function createPlayerHandle(runtime) {
+    const player = reactive(blankPlayer());
+    let primaryIndex = null;
+    const disposers = [];
+    disposers.push(runtime.body.onUpdate((body) => {
+        // First body seen wins; it stays primary until the player is lost, so a
+        // second person walking through frame cannot steal control mid-game.
+        if (primaryIndex === null)
+            primaryIndex = body.player;
+        if (body.player !== primaryIndex)
+            return;
+        applyBody(player, body);
+    }));
+    disposers.push(runtime.device.onPlayerLost(() => {
+        primaryIndex = null;
+        player.isTracked = false;
+        for (const name of PLAYER_JOINTS) {
+            player[name].valid = false;
+        }
+    }));
+    return {
+        primary: () => player,
+        dispose: () => {
+            for (const d of disposers)
+                d();
+            disposers.length = 0;
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@realnation/builder-shared-sdk",
-  "version": "1.0.4",
+  "version": "1.1.0",
   "type": "module",
   "private": false,
   "exports": {
@@ -8,6 +8,14 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./runtime": {
+      "types": "./dist/runtime/index.d.ts",
+      "import": "./dist/runtime/index.js"
+    },
+    "./runtime/vue": {
+      "types": "./dist/runtime/vue/index.d.ts",
+      "import": "./dist/runtime/vue/index.js"
     }
   },
   "files": [
@@ -16,16 +24,29 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "clean": "rimraf dist",
-    "prepublishOnly": "npm run clean && npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run clean && npm run test && npm run build",
     "prepare": "npm run clean && npm run build"
   },
   "dependencies": {
     "ali-oss": "^6.23.0",
     "axios": "^1.7.7"
   },
+  "peerDependencies": {
+    "vue": "^3.4.0"
+  },
+  "peerDependenciesMeta": {
+    "vue": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@types/ali-oss": "^6.16.11",
+    "@types/node": "^26.1.2",
     "rimraf": "^5.0.5",
-    "typescript": "^5.4.5"
+    "typescript": "^5.4.5",
+    "vitest": "^2.1.0",
+    "vue": "^3.4.0"
   }
 }