@laplace.live/persona-sdk 1.12.0 → 1.14.0

package/dist/index.d.ts

@@ -17,6 +17,7 @@ export * from './values/limits.ts';
 export * from './values/lipsync.ts';
 export * from './values/locale.ts';
 export * from './values/model-info.ts';
+export * from './values/mouse.ts';
 export * from './values/scene-transition.ts';
 export * from './values/stage-info.ts';
 export * from './values/terms.ts';

package/dist/index.js

@@ -19,6 +19,7 @@ export * from "./values/limits.js";
 export * from "./values/lipsync.js";
 export * from "./values/locale.js";
 export * from "./values/model-info.js";
+export * from "./values/mouse.js";
 export * from "./values/scene-transition.js";
 export * from "./values/stage-info.js";
 export * from "./values/terms.js";

package/dist/values/bindings.d.ts

@@ -1,3 +1,4 @@
+import type { BindingInput } from '../wire/types.ts';
 import type { Curve } from './curve.ts';
 import type { BindingTerm } from './terms.ts';
 /** A saved input-to-parameter rule shared by the rig editor and plugin API. */
@@ -21,6 +22,13 @@ export interface BindableParameter {
     max: number;
     default: number;
 }
+/** The editor's live readout, polled as one sample. */
+export interface BindingLiveValues {
+    /** What each tracking input reads right now; empty while nothing is measured. */
+    inputs: Partial<Record<BindingInput, number>>;
+    /** What each bound parameter reads on the model right now, by output id; empty for a host that cannot read it back. */
+    outputs: Record<string, number>;
+}
 /** Metadata read from a rig's display and physics sidecars. */
 export interface BindingEditorData {
     connections: Binding[];

package/dist/values/labels.d.ts

@@ -7,6 +7,11 @@ export declare function fileBasename(path: string): string;
  * so the basename is the only identifier there is.
  */
 export declare function motionLabel(file: string): string;
+/**
+ * Label for one motion of a group: the group alone when the file just repeats it (a VRM clip
+ * group named for its file, or a loose VTS file whose group is its basename), else both.
+ */
+export declare function motionSlotLabel(group: string, file: string): string;
 /** Playable entries of a `MotionGroup` with their authored indices; an empty string is a missing file and keeps its slot. */
 export declare function motionSlots(files: readonly string[]): {
     file: string;

package/dist/values/labels.js

@@ -13,6 +13,14 @@ export function motionLabel(file) {
     const base = fileBasename(file);
     return base.replace(/\.motion3\.json$|\.exp3\.json$|\.vrma$|\.json$/i, '') || base;
 }
+/**
+ * Label for one motion of a group: the group alone when the file just repeats it (a VRM clip
+ * group named for its file, or a loose VTS file whose group is its basename), else both.
+ */
+export function motionSlotLabel(group, file) {
+    const name = motionLabel(file);
+    return group === file || name === group ? group : `${group} · ${name}`;
+}
 /** Playable entries of a `MotionGroup` with their authored indices; an empty string is a missing file and keeps its slot. */
 export function motionSlots(files) {
     return files.flatMap((file, index) => (file === '' ? [] : [{ file, index }]));

package/dist/values/limits.d.ts

@@ -81,6 +81,8 @@ export interface CameraDistanceLimits {
 export declare function cameraDistanceLimits(env: Pick<SceneEnvironment, 'modelAssetId' | 'modelPlace'>, setRadius: number | null): CameraDistanceLimits;
 /** ×2 doubles Cubism's own breath amplitude — past that the head sway reads as a nod, not a breath. */
 export declare const BREATH_DEPTH_MAX = 2;
+/** Seconds; a minute without a face is well past any dropout worth waiting out. */
+export declare const TRACKING_LOST_DELAY_MAX = 60;
 export declare const MTOON_NORMAL_SCALE_MAX = 2;
 export declare const MTOON_RIM_MAX = 2;
 /** ×0 flattens the Fresnel to a flood fill, ×4 tightens a default power-5 rim to a hairline. */

package/dist/values/limits.js

@@ -112,6 +112,8 @@ export function cameraDistanceLimits(env, setRadius) {
 }
 /** ×2 doubles Cubism's own breath amplitude — past that the head sway reads as a nod, not a breath. */
 export const BREATH_DEPTH_MAX = 2;
+/** Seconds; a minute without a face is well past any dropout worth waiting out. */
+export const TRACKING_LOST_DELAY_MAX = 60;
 export const MTOON_NORMAL_SCALE_MAX = 2;
 export const MTOON_RIM_MAX = 2;
 /** ×0 flattens the Fresnel to a flood fill, ×4 tightens a default power-5 rim to a hairline. */

package/dist/values/mouse.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The OS cursor as a tracking input, in VTS's own names and span: −1..1 across the display the
+ * cursor is on, x growing rightward and y growing upward like `FacePositionY`.
+ */
+export declare const MOUSE_INPUT_RANGES: {
+    readonly MousePositionX: readonly [-1, 1];
+    readonly MousePositionY: readonly [-1, 1];
+};
+export declare const MOUSE_INPUT_NAMES: readonly MouseInputName[];
+export type MouseInputName = keyof typeof MOUSE_INPUT_RANGES;
+export type MouseInputs = Partial<Record<MouseInputName, number>>;
+export declare function isMouseInputName(v: string): v is MouseInputName;

package/dist/values/mouse.js

@@ -0,0 +1,14 @@
+import { keysOf } from "./guards.js";
+/**
+ * The OS cursor as a tracking input, in VTS's own names and span: −1..1 across the display the
+ * cursor is on, x growing rightward and y growing upward like `FacePositionY`.
+ */
+export const MOUSE_INPUT_RANGES = {
+    MousePositionX: [-1, 1],
+    MousePositionY: [-1, 1],
+};
+export const MOUSE_INPUT_NAMES = keysOf(MOUSE_INPUT_RANGES);
+const MOUSE_INPUT_SET = new Set(MOUSE_INPUT_NAMES);
+export function isMouseInputName(v) {
+    return MOUSE_INPUT_SET.has(v);
+}

package/dist/wire/methods.d.ts

@@ -1,10 +1,10 @@
-import type { Binding, BindingEditorData } from '../values/bindings.ts';
+import type { Binding, BindingEditorData, BindingLiveValues } from '../values/bindings.ts';
 import type { ControllerMovementConfig, ControllerState } from '../values/controller.ts';
 import type { SpawnTransition } from '../values/item-transition.ts';
 import type { LipSyncCalibrationCommand, LipSyncConfig, LipSyncMode, LipSyncState } from '../values/lipsync.ts';
 import type { SceneInspection } from '../values/stage-info.ts';
 import type { EventName } from './events.ts';
-import type { AnchorOption, AppCapability, AssetKind, AssetRef, Attach, AttachHeadAngle, AutomationInfo, BindingInput, Expression, ExpressionPersistence, HandTrackingMode, HotkeyConfig, HotkeyState, InjectEntry, InjectTarget, InstanceRuntime, JsonValue, LayerEffectKey, LayerEffects, LayerEffectsPatch, MediaPipeConfig, ModelInfo, ModelRef, MotionGroup, MToonTuning, ObjectContent, ObjectLightOverride, ObjectSpace, Place2D, Place3D, PlayingMotion, PoseSourceId, PoseStatus, Scene, SceneItem, SceneLight, SceneLightCameraFollowOptions, ScenePatch, SceneState, ScreenPlacement, Settings, SettingsPatch, TrackingSourceConfig, TrackingSourceId, TrackingSourceKind, TrackingStatus, VrmPlacement } from './types.ts';
+import type { AnchorOption, AppCapability, AssetKind, AssetRef, Attach, AttachHeadAngle, AutomationInfo, BindingInput, Expression, ExpressionPersistence, HandTrackingMode, HotkeyConfig, HotkeyState, InjectEntry, InjectTarget, InstanceRuntime, JsonValue, LayerEffectKey, LayerEffects, LayerEffectsPatch, MediaPipeConfig, ModelInfo, ModelRef, MotionGroup, MToonTuning, ObjectContent, ObjectLightOverride, ObjectSpace, Place2D, Place3D, PlayingMotion, PoseSourceId, PoseStatus, Scene, SceneItem, SceneLight, SceneLightCameraFollowOptions, ScenePatch, SceneState, ScreenPlacement, Settings, SettingsPatch, TrackingLostBehavior, TrackingSourceConfig, TrackingSourceId, TrackingSourceKind, TrackingStatus, VrmPlacement } from './types.ts';
 /** Marker for methods that take no parameters; the client lets you omit the argument. */
 export type EmptyRequest = Record<never, never>;
 /** Marker for methods whose success response carries no data. */
@@ -157,7 +157,16 @@ export type InstanceSetMToonResponse = EmptyResponse;
 export interface InstanceSetIdleRequest {
     instanceId?: string;
     idleAnimation?: boolean;
+    /** VRM only. */
     idleClip?: string;
+    /** Live2D only: a motion file from `motion.list`, or null for the model's `Idle` group. */
+    idleMotion?: string | null;
+    /** The `tracking-lost` app capability carries these three. */
+    trackingLostBehavior?: TrackingLostBehavior;
+    /** Live2D only: a motion file from `motion.list`, or null for none. */
+    trackingLostMotion?: string | null;
+    /** Seconds, 0 to `TRACKING_LOST_DELAY_MAX`. */
+    trackingLostDelay?: number;
 }
 export type InstanceSetIdleResponse = EmptyResponse;
 export interface InstanceInfoRequest {
@@ -581,9 +590,7 @@ export interface BindingSetResponse {
     saved: boolean;
 }
 export type BindingInputsRequest = BindingTarget;
-export interface BindingInputsResponse {
-    inputs: Partial<Record<BindingInput, number>>;
-}
+export type BindingInputsResponse = BindingLiveValues;
 export interface BindingOverrideRequest extends BindingTarget {
     input: BindingInput;
     value: number | null;

package/dist/wire/types.d.ts

@@ -7,6 +7,7 @@ import { type ArkitInputName } from '../values/arkit.ts';
 import { type BaseControllerInputName, type ControllerInputName, type ControllerMovementConfig } from '../values/controller.ts';
 import { type HandInputName } from '../values/hands.ts';
 import { type LipSyncMode, type VoiceInputName } from '../values/lipsync.ts';
+import { type MouseInputName } from '../values/mouse.ts';
 export type ModelFormat = 'live2d' | 'vrm';
 /** Where an item came from: shipped with the app, or added by the user. */
 export type ContentOrigin = 'bundled' | 'user';
@@ -166,8 +167,28 @@ export interface SceneModelItem {
     controllerMovement: ControllerMovementConfig;
     live2d: ScreenPlacement;
     vrm: VrmPlacement;
+    /** Whether the idle base animation plays: VRM loops `idleClip`, Live2D `idleMotion`. */
     idleAnimation: boolean;
+    /** VRM: a bundled `.vrma` filename or `asset:<id>`. Kept while the instance shows a Live2D model. */
     idleClip: string;
+    /**
+     * Live2D: a motion file the model lists (as `motion.list` names it), looped beneath every
+     * other motion, or null for the model's own `Idle` group at random. A file the model no
+     * longer lists degrades to that group. Kept while the instance shows a VRM.
+     */
+    idleMotion: string | null;
+    /**
+     * What the tracked parameters do while the face is lost: keep the last pose until it is
+     * found again (`hold`), or ease back to the idle over ~0.3 s and return the same way (`idle`).
+     */
+    trackingLostBehavior: TrackingLostBehavior;
+    /**
+     * Live2D: a listed motion that replaces the idle once the face has been lost for
+     * `trackingLostDelay` seconds, until it is found again; null keeps the idle playing.
+     */
+    trackingLostMotion: string | null;
+    /** Seconds without a face before `trackingLostMotion` takes over. */
+    trackingLostDelay: number;
     /**
      * Live2D only: the engine's built-in idle breath. Beyond `ParamBreath` it also sways
      * `ParamAngle*`/`ParamBodyAngleX`, so a rig whose head ranges are tuned tightly may want it off.
@@ -984,11 +1005,13 @@ export interface ScenePatch {
  * 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", "automations", "controllers", "model-editing", "asset-inspection", "layer-effects", "scene-transitions", "area-lights", "spot-lights", "camera-follow-lights", "shadow-filters", "environment-map-model", "spawn"];
+export declare const APP_CAPABILITIES: readonly ["storage", "speech", "automations", "controllers", "model-editing", "asset-inspection", "layer-effects", "scene-transitions", "area-lights", "spot-lights", "camera-follow-lights", "shadow-filters", "environment-map-model", "spawn", "tracking-lost"];
 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'
+/** `instance.setIdle` with `idleMotion`: one of the model's motions loops as its idle. Live2D only. */
+ | 'idle-motions' | 'pose' | 'live2d-params'
 /** `instance.setBreath`; the idle breathing loop is Cubism's, so VRM lacks it. */
  | 'breath'
 /** `expression.setWeight`; Cubism expressions carry no user-settable weight, so Live2D lacks it. */
@@ -1114,6 +1137,9 @@ export declare const TRACKING_CHANNEL_FIELDS: {
 };
 export declare const TRACKING_CHANNELS: readonly TrackingChannel[];
 export declare const HAND_TRACKING_MODES: readonly ["arms", "fingers"];
+/** How the face drivers react to a dropout; see `SceneModelInstance.trackingLostBehavior`. */
+export declare const TRACKING_LOST_BEHAVIORS: readonly ["hold", "idle"];
+export type TrackingLostBehavior = (typeof TRACKING_LOST_BEHAVIORS)[number];
 export type HandTrackingMode = (typeof HAND_TRACKING_MODES)[number];
 export declare function isHandTrackingMode(v: unknown): v is HandTrackingMode;
 export declare const MEDIAPIPE_DELEGATES: readonly ["CPU", "GPU"];
@@ -1226,11 +1252,12 @@ declare const VTS_INPUT_RANGES: {
 };
 type VtsInputName = keyof typeof VTS_INPUT_RANGES;
 /**
- * Default input vocabulary: face and hand inputs, raw ARKit channels and controller profile 1.
- * Additional controller profile ids are accepted by isInputName without appearing in this list.
+ * Default input vocabulary: face, hand and cursor inputs, raw ARKit channels and controller
+ * profile 1. Additional controller profile ids are accepted by isInputName without appearing
+ * in this list.
  */
-export declare const INPUT_NAMES: readonly (VtsInputName | HandInputName | VoiceInputName | ArkitInputName | BaseControllerInputName)[];
-export type InputName = VtsInputName | HandInputName | VoiceInputName | ArkitInputName | ControllerInputName;
+export declare const INPUT_NAMES: readonly (VtsInputName | HandInputName | VoiceInputName | MouseInputName | ArkitInputName | BaseControllerInputName)[];
+export type InputName = VtsInputName | HandInputName | VoiceInputName | MouseInputName | ArkitInputName | ControllerInputName;
 /** Whether an untrusted string names a tracking input — the guard every wire boundary needs. */
 export declare function isInputName(v: string): v is InputName;
 /**
@@ -1258,7 +1285,7 @@ export declare function arkitTwinOf(input: InputName): BindingInput;
  * Default inputs' natural spans. Use getInputRange for a dynamically numbered controller input.
  * Head angles are degrees; the rest are unitless.
  */
-export declare const INPUT_RANGES: Record<VtsInputName | HandInputName | VoiceInputName | ArkitInputName | BaseControllerInputName, readonly [number, number]>;
+export declare const INPUT_RANGES: Record<VtsInputName | HandInputName | VoiceInputName | MouseInputName | ArkitInputName | BaseControllerInputName, readonly [number, number]>;
 /** Natural span of any valid input, including dynamically numbered controller profiles. */
 export declare function getInputRange(name: InputName): readonly [number, number];
 /**

package/dist/wire/types.js

@@ -6,6 +6,7 @@ import { BASE_CONTROLLER_INPUT_NAMES, BASE_CONTROLLER_INPUT_RANGES, controllerIn
 import { isOneOf, keysOf } from "../values/guards.js";
 import { HAND_INPUT_NAMES, HAND_INPUT_RANGES } from "../values/hands.js";
 import { VOICE_INPUT_NAMES, VOICE_INPUT_RANGES } from "../values/lipsync.js";
+import { MOUSE_INPUT_NAMES, MOUSE_INPUT_RANGES } from "../values/mouse.js";
 /**
  * How a registered file is labelled. Wider than an object's content kinds: `.hdr` is only
  * ever an environment map, and a `.vmd` splits by content — `cameraMotion` for one that
@@ -46,6 +47,8 @@ export const APP_CAPABILITIES = [
     'shadow-filters',
     'environment-map-model',
     'spawn',
+    /** `instance.setIdle` takes `trackingLostBehavior`, `trackingLostMotion` and `trackingLostDelay`. */
+    'tracking-lost',
 ];
 export function isAppCapability(v) {
     return isOneOf(v, APP_CAPABILITIES);
@@ -91,6 +94,8 @@ export const TRACKING_CHANNEL_FIELDS = {
 };
 export const TRACKING_CHANNELS = keysOf(TRACKING_CHANNEL_FIELDS);
 export const HAND_TRACKING_MODES = ['arms', 'fingers'];
+/** How the face drivers react to a dropout; see `SceneModelInstance.trackingLostBehavior`. */
+export const TRACKING_LOST_BEHAVIORS = ['hold', 'idle'];
 export function isHandTrackingMode(v) {
     return isOneOf(v, HAND_TRACKING_MODES);
 }
@@ -185,13 +190,15 @@ const VTS_INPUT_RANGES = {
 /** VTS's input vocabulary, plus `JawOpen` — the derived half of {@link INPUT_NAMES}. */
 const VTS_INPUT_NAMES = keysOf(VTS_INPUT_RANGES);
 /**
- * Default input vocabulary: face and hand inputs, raw ARKit channels and controller profile 1.
- * Additional controller profile ids are accepted by isInputName without appearing in this list.
+ * Default input vocabulary: face, hand and cursor inputs, raw ARKit channels and controller
+ * profile 1. Additional controller profile ids are accepted by isInputName without appearing
+ * in this list.
  */
 export const INPUT_NAMES = [
     ...VTS_INPUT_NAMES,
     ...VOICE_INPUT_NAMES,
     ...HAND_INPUT_NAMES,
+    ...MOUSE_INPUT_NAMES,
     ...ARKIT_INPUT_NAMES,
     ...BASE_CONTROLLER_INPUT_NAMES,
 ];
@@ -231,6 +238,7 @@ export const INPUT_RANGES = {
     ...VTS_INPUT_RANGES,
     ...VOICE_INPUT_RANGES,
     ...HAND_INPUT_RANGES,
+    ...MOUSE_INPUT_RANGES,
     ...BASE_CONTROLLER_INPUT_RANGES,
     // `fromEntries` widens the key type back to `string`; the annotation above is what keeps
     // this exhaustive, and it fails to typecheck if a name ever lacks a range.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@laplace.live/persona-sdk",
-  "version": "1.12.0",
+  "version": "1.14.0",
   "description": "TypeScript SDK and wire schema for the LAPLACE Persona plugin API",
   "license": "MIT",
   "type": "module",