@laplace.live/persona-sdk 0.6.0 → 0.8.0

package/dist/{types.d.ts → wire/types.d.ts}

@@ -109,6 +109,13 @@ export interface SceneModelItem {
     instanceId: string;
     ref: ModelRef;
     visible: boolean;
+    /**
+     * Face source tracking this instance ({@link TrackingSourceConfig.id}); null = its face is untracked.
+     * A dangling or disabled id behaves as null. One source may track several instances (mirroring).
+     */
+    faceSourceId: string | null;
+    /** Body source (vmc) tracking this instance; null = its pose is untracked. New instances bind to each channel's default source. */
+    poseSourceId: string | null;
     live2d: ScreenPlacement;
     vrm: VrmPlacement;
     idleAnimation: boolean;
@@ -371,6 +378,24 @@ export interface SceneDroplets {
     /** Specular glint on drops where the frame is transparent, so rain reads over the desktop (0 to 1). */
     glints: number;
 }
+/** Compute-driven snowfall in the 3D scene: flakes drift down, settle on models and props, then melt. */
+export interface SceneSnow {
+    enabled: boolean;
+    /** How many flakes are alive at once. */
+    amount: number;
+    /** Fall and drift clock multiplier. */
+    speed: number;
+    /** Steady sideways drift, in metres per second along the stage's x axis. */
+    wind: number;
+    /** Horizontal wobble while falling. */
+    sway: number;
+    /** Flake size multiplier. */
+    size: number;
+    /** Seconds a settled flake rests before it finishes melting away. */
+    melt: number;
+    /** Flake opacity. */
+    opacity: number;
+}
 /**
  * Post-processing over the rendered 3D frame. Everything off skips the effect
  * chain entirely. Deliberately flat: every toggle-plus-numbers effect sits at
@@ -391,6 +416,7 @@ export interface SceneEffects {
     pixelate: ScenePixelate;
     glitch: SceneGlitch;
     droplets: SceneDroplets;
+    snow: SceneSnow;
 }
 /**
  * Image-based lighting for the 3D stage: an environment map, whether to show it
@@ -438,8 +464,17 @@ export interface ScenePatch {
     lights?: SceneLight[];
     environment?: SceneEnvironment;
 }
+/**
+ * App-level features a client gates on (never version-sniff): `hello` and
+ * `app.info` report them — the per-app mirror of {@link InstanceRuntime.capabilities}.
+ */
+export declare const APP_CAPABILITIES: readonly ["storage", "speech"];
+export type AppCapability = (typeof APP_CAPABILITIES)[number];
+export declare function isAppCapability(v: unknown): v is AppCapability;
 /** What a loaded model instance can do; absent capabilities answer `unsupported-for-format`. */
-export type InstanceCapability = 'motions' | 'expressions' | 'placement-2d' | 'placement-3d' | 'mtoon' | 'idle-clips' | 'pose' | 'live2d-params';
+export type InstanceCapability = 'motions' | 'expressions' | 'placement-2d' | 'placement-3d' | 'mtoon' | 'idle-clips' | 'pose' | 'live2d-params'
+/** `speech.play` lip-sync; engine-dependent, so gate on the runtime, not the format. */
+ | 'speech';
 export interface InstanceRuntime {
     instanceId: string;
     kind: 'model' | 'object';
@@ -503,10 +538,40 @@ export interface ExpressionPersistence {
     enabled: boolean;
     saved: string[];
 }
-export type TrackingSourceId = 'vts-ios' | 'vts-ios-native' | 'ifacialmocap';
-export type PoseSourceId = 'vmc';
+/** Any JSON-serializable value — what `storage.set` accepts and `storage.get` returns. */
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export declare const TRACKING_SOURCE_IDS: readonly ["vts-ios", "vts-ios-native", "ifacialmocap"];
+export type TrackingSourceId = (typeof TRACKING_SOURCE_IDS)[number];
+/** Body-pose protocols. Every one so far is UDP with a configurable port. */
+export declare const POSE_SOURCE_IDS: readonly ["vmc"];
+export type PoseSourceId = (typeof POSE_SOURCE_IDS)[number];
 export type TrackingStatus = 'off' | 'waiting' | 'tracking' | 'no-face';
 export type PoseStatus = 'off' | 'waiting' | 'tracking';
+/** Every protocol a tracking source instance can speak; face kinds plus the body (vmc) kind. */
+export declare const TRACKING_SOURCE_KINDS: readonly ["vts-ios", "vts-ios-native", "ifacialmocap", "vmc"];
+export type TrackingSourceKind = (typeof TRACKING_SOURCE_KINDS)[number];
+/** Whether a source kind feeds the face channel (vmc is the body channel). */
+export declare function isFaceSourceKind(kind: TrackingSourceKind): kind is TrackingSourceId;
+/**
+ * One configured tracking source instance. Several can run at once — one per person —
+ * and scene model instances bind to them by id (`SceneModelItem.faceSourceId`/`poseSourceId`).
+ */
+export interface TrackingSourceConfig {
+    id: string;
+    kind: TrackingSourceKind;
+    /** User label shown in lists; '' renders as the kind's own label. */
+    name: string;
+    enabled: boolean;
+    /**
+     * Face kinds: accept only this device/sender IP; null accepts any sender not claimed
+     * by a pinned instance of the same kind. Ignored by vmc (its senders pick the port).
+     */
+    phoneIp: string | null;
+    /** vmc only: the UDP port this instance listens on. Null on face kinds — they bind per protocol. */
+    port: number | null;
+}
 export declare const EFFECTS_QUALITY_LEVELS: readonly ["low", "medium", "high"];
 export type EffectsQuality = (typeof EFFECTS_QUALITY_LEVELS)[number];
 /**
@@ -529,10 +594,13 @@ export interface Settings {
         selectionOutline: boolean;
         effectsQuality: EffectsQuality;
     };
+    /** `source` mirrors the first face source's kind — the pre-multi-source field, kept for old clients. */
     tracking: {
         enabled: boolean;
         source: TrackingSourceId;
+        sources: TrackingSourceConfig[];
     };
+    /** `source`/`port` mirror the first vmc source — the pre-multi-source fields, kept for old clients. */
     pose: {
         enabled: boolean;
         source: PoseSourceId;

package/dist/{types.js → wire/types.js}

@@ -7,6 +7,25 @@
  * directional light covers with one map, so it gets the smaller of the pair.
  */
 export const SHADOW_QUALITY_LEVELS = ['off', 'low', 'medium', 'high', 'extra'];
+// ---- Runtime state -------------------------------------------------------------
+/**
+ * App-level features a client gates on (never version-sniff): `hello` and
+ * `app.info` report them — the per-app mirror of {@link InstanceRuntime.capabilities}.
+ */
+export const APP_CAPABILITIES = ['storage', 'speech'];
+export function isAppCapability(v) {
+    return typeof v === 'string' && APP_CAPABILITIES.includes(v);
+}
+// ---- Settings ------------------------------------------------------------------
+export const TRACKING_SOURCE_IDS = ['vts-ios', 'vts-ios-native', 'ifacialmocap'];
+/** Body-pose protocols. Every one so far is UDP with a configurable port. */
+export const POSE_SOURCE_IDS = ['vmc'];
+/** Every protocol a tracking source instance can speak; face kinds plus the body (vmc) kind. */
+export const TRACKING_SOURCE_KINDS = [...TRACKING_SOURCE_IDS, ...POSE_SOURCE_IDS];
+/** Whether a source kind feeds the face channel (vmc is the body channel). */
+export function isFaceSourceKind(kind) {
+    return TRACKING_SOURCE_IDS.includes(kind);
+}
 export const EFFECTS_QUALITY_LEVELS = ['low', 'medium', 'high'];
 /**
  * Accepted values for `performance.fpsLimit`; 0 = unlimited. Anything else is snapped

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@laplace.live/persona-sdk",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "TypeScript SDK and wire schema for the LAPLACE Persona plugin API",
   "license": "MIT",
   "type": "module",
@@ -28,7 +28,7 @@
   "devDependencies": {
     "rimraf": "^6.1.3",
     "typescript": "~6.0.3",
-    "vitest": "^4.1.10"
+    "vitest": "^4.1.11"
   },
   "engines": {
     "node": ">=22"