@laplace.live/persona-sdk 0.18.1 → 1.1.0

package/dist/values/hands.d.ts

@@ -0,0 +1,53 @@
+/** VTube Studio hand inputs, extended with nizima LIVE's wrist Y rotation. */
+export declare const HAND_INPUT_NAMES: readonly ["HandLeftFound", "HandLeftPositionX", "HandLeftPositionY", "HandLeftPositionZ", "HandLeftAngleX", "HandLeftAngleY", "HandLeftAngleZ", "HandLeftOpen", "HandLeftFinger_1_Thumb", "HandLeftFinger_2_Index", "HandLeftFinger_3_Middle", "HandLeftFinger_4_Ring", "HandLeftFinger_5_Pinky", "HandRightFound", "HandRightPositionX", "HandRightPositionY", "HandRightPositionZ", "HandRightAngleX", "HandRightAngleY", "HandRightAngleZ", "HandRightOpen", "HandRightFinger_1_Thumb", "HandRightFinger_2_Index", "HandRightFinger_3_Middle", "HandRightFinger_4_Ring", "HandRightFinger_5_Pinky", "BothHandsFound", "HandDistance"];
+export type HandInputName = (typeof HAND_INPUT_NAMES)[number];
+export type HandInputs = Partial<Record<HandInputName, number>>;
+/** Whether an input uses the canonical hand vocabulary. */
+export declare function isHandInputName(input: string): input is HandInputName;
+/** Names nizima uses for VTS's numbered fingers and both-hands detection. */
+export declare const NIZIMA_HAND_ALIASES: {
+    readonly HandLeftFingerThumb: "HandLeftFinger_1_Thumb";
+    readonly HandLeftFingerIndex: "HandLeftFinger_2_Index";
+    readonly HandLeftFingerMiddle: "HandLeftFinger_3_Middle";
+    readonly HandLeftFingerRing: "HandLeftFinger_4_Ring";
+    readonly HandLeftFingerPinky: "HandLeftFinger_5_Pinky";
+    readonly HandRightFingerThumb: "HandRightFinger_1_Thumb";
+    readonly HandRightFingerIndex: "HandRightFinger_2_Index";
+    readonly HandRightFingerMiddle: "HandRightFinger_3_Middle";
+    readonly HandRightFingerRing: "HandRightFinger_4_Ring";
+    readonly HandRightFingerPinky: "HandRightFinger_5_Pinky";
+    readonly HandBothFound: "BothHandsFound";
+};
+/** Canonicalize a hand name; aliases share canonical units on the plugin API. */
+export declare function canonicalHandInputName(input: string): HandInputName | null;
+/** Angles are degrees; positions and distance use VTS's ten-unit scale. */
+export declare const HAND_INPUT_RANGES: {
+    readonly HandLeftFound: readonly [0, 1];
+    readonly HandLeftPositionX: readonly [-10, 10];
+    readonly HandLeftPositionY: readonly [-10, 10];
+    readonly HandLeftPositionZ: readonly [-10, 10];
+    readonly HandLeftAngleX: readonly [-180, 180];
+    readonly HandLeftAngleY: readonly [-90, 90];
+    readonly HandLeftAngleZ: readonly [-180, 180];
+    readonly HandLeftOpen: readonly [0, 1];
+    readonly HandLeftFinger_1_Thumb: readonly [0, 1];
+    readonly HandLeftFinger_2_Index: readonly [0, 1];
+    readonly HandLeftFinger_3_Middle: readonly [0, 1];
+    readonly HandLeftFinger_4_Ring: readonly [0, 1];
+    readonly HandLeftFinger_5_Pinky: readonly [0, 1];
+    readonly HandRightFound: readonly [0, 1];
+    readonly HandRightPositionX: readonly [-10, 10];
+    readonly HandRightPositionY: readonly [-10, 10];
+    readonly HandRightPositionZ: readonly [-10, 10];
+    readonly HandRightAngleX: readonly [-180, 180];
+    readonly HandRightAngleY: readonly [-90, 90];
+    readonly HandRightAngleZ: readonly [-180, 180];
+    readonly HandRightOpen: readonly [0, 1];
+    readonly HandRightFinger_1_Thumb: readonly [0, 1];
+    readonly HandRightFinger_2_Index: readonly [0, 1];
+    readonly HandRightFinger_3_Middle: readonly [0, 1];
+    readonly HandRightFinger_4_Ring: readonly [0, 1];
+    readonly HandRightFinger_5_Pinky: readonly [0, 1];
+    readonly BothHandsFound: readonly [0, 1];
+    readonly HandDistance: readonly [0, 10];
+};

package/dist/values/hands.js

@@ -0,0 +1,89 @@
+/** VTube Studio hand inputs, extended with nizima LIVE's wrist Y rotation. */
+export const HAND_INPUT_NAMES = [
+    'HandLeftFound',
+    'HandLeftPositionX',
+    'HandLeftPositionY',
+    'HandLeftPositionZ',
+    'HandLeftAngleX',
+    'HandLeftAngleY',
+    'HandLeftAngleZ',
+    'HandLeftOpen',
+    'HandLeftFinger_1_Thumb',
+    'HandLeftFinger_2_Index',
+    'HandLeftFinger_3_Middle',
+    'HandLeftFinger_4_Ring',
+    'HandLeftFinger_5_Pinky',
+    'HandRightFound',
+    'HandRightPositionX',
+    'HandRightPositionY',
+    'HandRightPositionZ',
+    'HandRightAngleX',
+    'HandRightAngleY',
+    'HandRightAngleZ',
+    'HandRightOpen',
+    'HandRightFinger_1_Thumb',
+    'HandRightFinger_2_Index',
+    'HandRightFinger_3_Middle',
+    'HandRightFinger_4_Ring',
+    'HandRightFinger_5_Pinky',
+    'BothHandsFound',
+    'HandDistance',
+];
+const HAND_INPUT_SET = new Set(HAND_INPUT_NAMES);
+/** Whether an input uses the canonical hand vocabulary. */
+export function isHandInputName(input) {
+    return HAND_INPUT_SET.has(input);
+}
+/** Names nizima uses for VTS's numbered fingers and both-hands detection. */
+export const NIZIMA_HAND_ALIASES = {
+    HandLeftFingerThumb: 'HandLeftFinger_1_Thumb',
+    HandLeftFingerIndex: 'HandLeftFinger_2_Index',
+    HandLeftFingerMiddle: 'HandLeftFinger_3_Middle',
+    HandLeftFingerRing: 'HandLeftFinger_4_Ring',
+    HandLeftFingerPinky: 'HandLeftFinger_5_Pinky',
+    HandRightFingerThumb: 'HandRightFinger_1_Thumb',
+    HandRightFingerIndex: 'HandRightFinger_2_Index',
+    HandRightFingerMiddle: 'HandRightFinger_3_Middle',
+    HandRightFingerRing: 'HandRightFinger_4_Ring',
+    HandRightFingerPinky: 'HandRightFinger_5_Pinky',
+    HandBothFound: 'BothHandsFound',
+};
+/** Canonicalize a hand name; aliases share canonical units on the plugin API. */
+export function canonicalHandInputName(input) {
+    if (isHandInputName(input))
+        return input;
+    return Object.hasOwn(NIZIMA_HAND_ALIASES, input)
+        ? NIZIMA_HAND_ALIASES[input]
+        : null;
+}
+/** Angles are degrees; positions and distance use VTS's ten-unit scale. */
+export const HAND_INPUT_RANGES = {
+    HandLeftFound: [0, 1],
+    HandLeftPositionX: [-10, 10],
+    HandLeftPositionY: [-10, 10],
+    HandLeftPositionZ: [-10, 10],
+    HandLeftAngleX: [-180, 180],
+    HandLeftAngleY: [-90, 90],
+    HandLeftAngleZ: [-180, 180],
+    HandLeftOpen: [0, 1],
+    HandLeftFinger_1_Thumb: [0, 1],
+    HandLeftFinger_2_Index: [0, 1],
+    HandLeftFinger_3_Middle: [0, 1],
+    HandLeftFinger_4_Ring: [0, 1],
+    HandLeftFinger_5_Pinky: [0, 1],
+    HandRightFound: [0, 1],
+    HandRightPositionX: [-10, 10],
+    HandRightPositionY: [-10, 10],
+    HandRightPositionZ: [-10, 10],
+    HandRightAngleX: [-180, 180],
+    HandRightAngleY: [-90, 90],
+    HandRightAngleZ: [-180, 180],
+    HandRightOpen: [0, 1],
+    HandRightFinger_1_Thumb: [0, 1],
+    HandRightFinger_2_Index: [0, 1],
+    HandRightFinger_3_Middle: [0, 1],
+    HandRightFinger_4_Ring: [0, 1],
+    HandRightFinger_5_Pinky: [0, 1],
+    BothHandsFound: [0, 1],
+    HandDistance: [0, 10],
+};

package/dist/values/hotkeys.d.ts

@@ -1,2 +1,8 @@
 /** True when the combo carries a command modifier and so may be registered globally. */
 export declare function hasCommandModifier(accelerator: string | null): boolean;
+/**
+ * True when `global` can apply: a command-modifier combo registers with the OS, and a controller
+ * combo is observed directly, so neither needs Persona focused. Classifies stored combos, which
+ * every writer canonicalizes; it does not validate one.
+ */
+export declare function canRunInBackground(accelerator: string | null): boolean;

package/dist/values/hotkeys.js

@@ -1,5 +1,6 @@
 // Hotkey rules every consumer must agree on: main decides OS registration by them, and a
 // client reading `Hotkey.global` off the wire needs the same rule to know the flag can apply.
+import { isControllerTriggerName } from "./controller.js";
 // Shift is deliberately absent: Shift+letter is how text is typed, and a global
 // registration consumes the combo system-wide (VTS can allow it because it observes).
 const COMMAND_MODIFIERS = ['Control', 'Alt', 'Super'];
@@ -9,3 +10,13 @@ export function hasCommandModifier(accelerator) {
         return false;
     return accelerator.split('+').some(t => COMMAND_MODIFIERS.includes(t));
 }
+/**
+ * True when `global` can apply: a command-modifier combo registers with the OS, and a controller
+ * combo is observed directly, so neither needs Persona focused. Classifies stored combos, which
+ * every writer canonicalizes; it does not validate one.
+ */
+export function canRunInBackground(accelerator) {
+    if (accelerator === null)
+        return false;
+    return hasCommandModifier(accelerator) || accelerator.split('+').every(isControllerTriggerName);
+}

package/dist/values/labels.d.ts

@@ -1,4 +1,6 @@
 import type { ShortcutInfo } from '../wire/types.ts';
+/** Last path segment, tolerating both `/` and `\` separators. */
+export declare function fileBasename(path: string): string;
 /**
  * Display label for a model-relative motion/expression/animation file: the
  * basename with its format extension stripped. Cubism entries carry no `Name`,

package/dist/values/labels.js

@@ -1,10 +1,14 @@
+/** Last path segment, tolerating both `/` and `\` separators. */
+export function fileBasename(path) {
+    return path.split(/[/\\]/).at(-1) ?? path;
+}
 /**
  * Display label for a model-relative motion/expression/animation file: the
  * basename with its format extension stripped. Cubism entries carry no `Name`,
  * so the basename is the only identifier there is.
  */
 export function motionLabel(file) {
-    const base = file.split(/[\\/]/).pop() ?? file;
+    const base = fileBasename(file);
     return base.replace(/\.motion3\.json$|\.exp3\.json$|\.vrma$|\.json$/i, '') || base;
 }
 // English fallbacks; localizing clients keep their own map and use these for unknown kinds.

package/dist/values/limits.d.ts

@@ -2,6 +2,8 @@ import type { AssetRef, Attach, EnvironmentLook, ModelFormat, MToonTuning, Objec
 export declare function clamp(v: number, min: number, max: number): number;
 /** Clamp to the unit interval. */
 export declare function clamp01(v: number): number;
+/** Wrap an angle into (-π, π]. */
+export declare function wrapAngle(a: number): number;
 export declare const DEFAULT_LIVE2D_PLACEMENT: ScreenPlacement;
 export declare const DEFAULT_VRM_PLACEMENT: VrmPlacement;
 /** Scene colors heal to 6-digit hex. */
@@ -142,3 +144,20 @@ export declare const STORAGE_VALUE_MAX_LENGTH: number;
 export declare const STORAGE_KEYS_MAX = 256;
 /** `speech.play` URL ceiling — sized for a ~40 s WAV as a base64 `data:audio/*` payload. */
 export declare const SPEECH_URL_MAX_LENGTH = 8000000;
+/**
+ * Narrowest the panel's field column still reads at: the three-up axis fields divide the width,
+ * they never wrap. The window's own floor, and the detail column's beside a dragged outliner.
+ */
+export declare const CONTROL_MIN_WIDTH = 360;
+/** Narrowest the outliner column drags to: the scene picker and a layer row's affordances still fit. */
+export declare const OUTLINER_MIN_WIDTH = 260;
+/** Width the outliner column opens at before anyone drags it, and the one a double-click restores. */
+export declare const OUTLINER_DEFAULT_WIDTH = 288;
+/**
+ * Where the panel splits in two: below it the detail follows the outliner in one scroller, at or
+ * above it each column scrolls on its own. `OUTLINER_MIN_WIDTH + CONTROL_MIN_WIDTH` and the 1 px
+ * split must fit inside it, or no layout satisfies both floors and the group clips instead.
+ */
+export declare const TWO_COLUMN_WIDTH = 672;
+/** 3D-stage resolution multipliers offered by both performance pickers. */
+export declare const RENDER_SCALE_PRESETS: readonly [1, 0.85, 0.75, 0.66, 0.5];

package/dist/values/limits.js

@@ -6,6 +6,16 @@ export function clamp(v, min, max) {
 export function clamp01(v) {
     return v < 0 ? 0 : v > 1 ? 1 : v;
 }
+/** Wrap an angle into (-π, π]. */
+export function wrapAngle(a) {
+    const TAU = Math.PI * 2;
+    let r = a % TAU;
+    if (r > Math.PI)
+        r -= TAU;
+    if (r <= -Math.PI)
+        r += TAU;
+    return r;
+}
 export const DEFAULT_LIVE2D_PLACEMENT = { x: 0, y: 0, scale: 1, rotation: 0 };
 export const DEFAULT_VRM_PLACEMENT = { x: 0, y: 0, z: 0, rotX: 0, rotY: 0, rotZ: 0, scale: 1 };
 /** Scene colors heal to 6-digit hex. */
@@ -239,3 +249,20 @@ export const STORAGE_VALUE_MAX_LENGTH = 64 * 1024;
 export const STORAGE_KEYS_MAX = 256;
 /** `speech.play` URL ceiling — sized for a ~40 s WAV as a base64 `data:audio/*` payload. */
 export const SPEECH_URL_MAX_LENGTH = 8_000_000;
+/**
+ * Narrowest the panel's field column still reads at: the three-up axis fields divide the width,
+ * they never wrap. The window's own floor, and the detail column's beside a dragged outliner.
+ */
+export const CONTROL_MIN_WIDTH = 360;
+/** Narrowest the outliner column drags to: the scene picker and a layer row's affordances still fit. */
+export const OUTLINER_MIN_WIDTH = 260;
+/** Width the outliner column opens at before anyone drags it, and the one a double-click restores. */
+export const OUTLINER_DEFAULT_WIDTH = 288;
+/**
+ * Where the panel splits in two: below it the detail follows the outliner in one scroller, at or
+ * above it each column scrolls on its own. `OUTLINER_MIN_WIDTH + CONTROL_MIN_WIDTH` and the 1 px
+ * split must fit inside it, or no layout satisfies both floors and the group clips instead.
+ */
+export const TWO_COLUMN_WIDTH = 672;
+/** 3D-stage resolution multipliers offered by both performance pickers. */
+export const RENDER_SCALE_PRESETS = [1, 0.85, 0.75, 0.66, 0.5];

package/dist/values/lipsync.d.ts

@@ -0,0 +1,106 @@
+export declare const LIP_SYNC_VOWELS: readonly ["A", "I", "U", "E", "O"];
+export type LipSyncVowel = (typeof LIP_SYNC_VOWELS)[number];
+export declare const LIP_SYNC_PHONEMES: readonly ["A", "I", "U", "E", "O", "S"];
+export type LipSyncPhoneme = (typeof LIP_SYNC_PHONEMES)[number];
+export declare const LIP_SYNC_MODES: readonly ["off", "always", "when-untracked"];
+export type LipSyncMode = (typeof LIP_SYNC_MODES)[number];
+/** Public limits, shared by the settings healer, the wire schema, and the panel sliders. */
+export declare const LIP_SYNC_GAIN_MAX = 30;
+export declare const LIP_SYNC_NOISE_GATE_MIN = -60;
+export declare const LIP_SYNC_SMOOTHING_MAX = 0.3;
+/** Local microphone calibration; each sample is a 12-coefficient MFCC vector. */
+export interface LipSyncProfile {
+    deviceId: string;
+    deviceLabel: string;
+    updatedAt: number;
+    samples: Record<LipSyncPhoneme, number[][]>;
+}
+/** Calibration steps that carry no phoneme; `record` is the sixth action and takes one. */
+export declare const LIP_SYNC_CALIBRATION_ACTIONS: readonly ["start", "cancel", "preview", "save", "reset"];
+export type LipSyncCalibrationCommand = {
+    action: (typeof LIP_SYNC_CALIBRATION_ACTIONS)[number];
+} | {
+    action: 'record';
+    phoneme: LipSyncPhoneme;
+};
+export interface LipSyncCalibrationState {
+    phase: 'ready' | 'recording' | 'verifying';
+    phoneme: LipSyncPhoneme | null;
+    progress: number;
+    completed: LipSyncPhoneme[];
+    error: 'too-quiet' | 'insufficient-data' | null;
+}
+/** One desktop microphone, shared by the scene's participating models. */
+export interface LipSyncConfig {
+    enabled: boolean;
+    /** Empty selects the system's default input. */
+    deviceId: string;
+    /** Input gain in dB, 0..30. */
+    gain: number;
+    /** Silence threshold in dBFS, -60..0. */
+    noiseGate: number;
+    /** Volume and vowel smoothing in seconds, 0..0.3. */
+    smoothing: number;
+}
+export declare const DEFAULT_LIP_SYNC_CONFIG: Readonly<LipSyncConfig>;
+/** Analyzer output before model-specific mapping. */
+export interface LipSyncSample {
+    /** Mouth-open envelope, 0..1. */
+    volume: number;
+    /** Smoothed vowel weights sum to at most one; the remainder represents non-vowel audio. */
+    vowels: Record<LipSyncVowel, number>;
+}
+export interface LipSyncState {
+    config: LipSyncConfig;
+    status: 'off' | 'starting' | 'listening' | 'error';
+    error: 'permission' | 'device' | 'analysis' | null;
+    devices: {
+        deviceId: string;
+        label: string;
+    }[];
+    sample: LipSyncSample | null;
+    microphone: {
+        deviceId: string;
+        label: string;
+    } | null;
+    profile: Omit<LipSyncProfile, 'samples'> | null;
+    calibration: LipSyncCalibrationState | null;
+}
+/** Drop incomplete or malformed calibrations rather than feeding them to the analyzer. */
+export declare function healLipSyncProfile(raw: unknown): LipSyncProfile | null;
+/** Heal persisted configuration, retaining supported values within their public limits. */
+export declare function healLipSyncConfig(raw: unknown): LipSyncConfig;
+/** Whether a persisted per-model mode is supported. */
+export declare function isLipSyncMode(value: unknown): value is LipSyncMode;
+export declare const VOICE_INPUT_NAMES: readonly ["VoiceVolume", "VoiceFrequency", "VoiceVolumePlusMouthOpen", "VoiceFrequencyPlusMouthSmile", "VoiceA", "VoiceI", "VoiceU", "VoiceE", "VoiceO", "VoiceSilence", "VoiceMouthOpen", "VoiceMouthSpread"];
+export type VoiceInputName = (typeof VOICE_INPUT_NAMES)[number];
+export declare const VOICE_INPUT_RANGES: {
+    readonly VoiceVolume: readonly [0, 1];
+    readonly VoiceFrequency: readonly [0, 1];
+    readonly VoiceVolumePlusMouthOpen: readonly [0, 2];
+    readonly VoiceFrequencyPlusMouthSmile: readonly [0, 1];
+    readonly VoiceA: readonly [0, 1];
+    readonly VoiceI: readonly [0, 1];
+    readonly VoiceU: readonly [0, 1];
+    readonly VoiceE: readonly [0, 1];
+    readonly VoiceO: readonly [0, 1];
+    readonly VoiceSilence: readonly [0, 1];
+    readonly VoiceMouthOpen: readonly [0, 1];
+    readonly VoiceMouthSpread: readonly [-1, 1];
+};
+/** Semantic import aliases; source analyzer amplitudes need not match Persona's. */
+export declare const NIZIMA_VOICE_ALIASES: {
+    readonly LipSyncVolume: "VoiceVolume";
+    readonly LipSyncMouthOpen: "VoiceMouthOpen";
+    readonly LipSyncMouthSpread: "VoiceMouthSpread";
+    readonly LipSyncMouthA: "VoiceA";
+    readonly LipSyncMouthI: "VoiceI";
+    readonly LipSyncMouthU: "VoiceU";
+    readonly LipSyncMouthE: "VoiceE";
+    readonly LipSyncMouthO: "VoiceO";
+};
+/**
+ * VTS-compatible binding inputs. Frequency projects vowel weights onto its conventional
+ * mouth-form axis; composite sums retain over-range values for the authored binding to clamp.
+ */
+export declare function voiceInputs(sample: LipSyncSample, faceInputs?: Readonly<Partial<Record<'MouthOpen' | 'MouthSmile', number>>>): Record<VoiceInputName, number>;

package/dist/values/lipsync.js

@@ -0,0 +1,120 @@
+import { finiteOr, isFiniteNumber, isRecord, nonEmptyString } from "./guards.js";
+import { clamp } from "./limits.js";
+export const LIP_SYNC_VOWELS = ['A', 'I', 'U', 'E', 'O'];
+export const LIP_SYNC_PHONEMES = [...LIP_SYNC_VOWELS, 'S'];
+export const LIP_SYNC_MODES = ['off', 'always', 'when-untracked'];
+/** Public limits, shared by the settings healer, the wire schema, and the panel sliders. */
+export const LIP_SYNC_GAIN_MAX = 30;
+export const LIP_SYNC_NOISE_GATE_MIN = -60;
+export const LIP_SYNC_SMOOTHING_MAX = 0.3;
+/** Calibration steps that carry no phoneme; `record` is the sixth action and takes one. */
+export const LIP_SYNC_CALIBRATION_ACTIONS = ['start', 'cancel', 'preview', 'save', 'reset'];
+export const DEFAULT_LIP_SYNC_CONFIG = {
+    enabled: false,
+    deviceId: '',
+    gain: 0,
+    noiseGate: -45,
+    smoothing: 0.08,
+};
+/** Drop incomplete or malformed calibrations rather than feeding them to the analyzer. */
+export function healLipSyncProfile(raw) {
+    if (!isRecord(raw))
+        return null;
+    const deviceId = nonEmptyString(raw.deviceId);
+    if (deviceId === null ||
+        typeof raw.deviceLabel !== 'string' ||
+        !isFiniteNumber(raw.updatedAt) ||
+        raw.updatedAt < 0 ||
+        !isRecord(raw.samples)) {
+        return null;
+    }
+    const samples = { A: [], I: [], U: [], E: [], O: [], S: [] };
+    for (const phoneme of LIP_SYNC_PHONEMES) {
+        const vectors = raw.samples[phoneme];
+        if (!Array.isArray(vectors) || vectors.length < 12 || vectors.length > 40)
+            return null;
+        for (const vector of vectors) {
+            if (!Array.isArray(vector) || vector.length !== 12 || !vector.every(isFiniteNumber))
+                return null;
+            samples[phoneme].push([...vector]);
+        }
+    }
+    return { deviceId, deviceLabel: raw.deviceLabel, updatedAt: raw.updatedAt, samples };
+}
+/** Heal persisted configuration, retaining supported values within their public limits. */
+export function healLipSyncConfig(raw) {
+    const value = isRecord(raw) ? raw : {};
+    return {
+        enabled: typeof value.enabled === 'boolean' ? value.enabled : DEFAULT_LIP_SYNC_CONFIG.enabled,
+        deviceId: typeof value.deviceId === 'string' ? value.deviceId : DEFAULT_LIP_SYNC_CONFIG.deviceId,
+        gain: clamp(finiteOr(value.gain, DEFAULT_LIP_SYNC_CONFIG.gain), 0, LIP_SYNC_GAIN_MAX),
+        noiseGate: clamp(finiteOr(value.noiseGate, DEFAULT_LIP_SYNC_CONFIG.noiseGate), LIP_SYNC_NOISE_GATE_MIN, 0),
+        smoothing: clamp(finiteOr(value.smoothing, DEFAULT_LIP_SYNC_CONFIG.smoothing), 0, LIP_SYNC_SMOOTHING_MAX),
+    };
+}
+/** Whether a persisted per-model mode is supported. */
+export function isLipSyncMode(value) {
+    return LIP_SYNC_MODES.some(mode => mode === value);
+}
+export const VOICE_INPUT_NAMES = [
+    'VoiceVolume',
+    'VoiceFrequency',
+    'VoiceVolumePlusMouthOpen',
+    'VoiceFrequencyPlusMouthSmile',
+    'VoiceA',
+    'VoiceI',
+    'VoiceU',
+    'VoiceE',
+    'VoiceO',
+    'VoiceSilence',
+    'VoiceMouthOpen',
+    'VoiceMouthSpread',
+];
+export const VOICE_INPUT_RANGES = {
+    VoiceVolume: [0, 1],
+    VoiceFrequency: [0, 1],
+    VoiceVolumePlusMouthOpen: [0, 2],
+    VoiceFrequencyPlusMouthSmile: [0, 1],
+    VoiceA: [0, 1],
+    VoiceI: [0, 1],
+    VoiceU: [0, 1],
+    VoiceE: [0, 1],
+    VoiceO: [0, 1],
+    VoiceSilence: [0, 1],
+    VoiceMouthOpen: [0, 1],
+    VoiceMouthSpread: [-1, 1],
+};
+/** Semantic import aliases; source analyzer amplitudes need not match Persona's. */
+export const NIZIMA_VOICE_ALIASES = {
+    LipSyncVolume: 'VoiceVolume',
+    LipSyncMouthOpen: 'VoiceMouthOpen',
+    LipSyncMouthSpread: 'VoiceMouthSpread',
+    LipSyncMouthA: 'VoiceA',
+    LipSyncMouthI: 'VoiceI',
+    LipSyncMouthU: 'VoiceU',
+    LipSyncMouthE: 'VoiceE',
+    LipSyncMouthO: 'VoiceO',
+};
+/**
+ * VTS-compatible binding inputs. Frequency projects vowel weights onto its conventional
+ * mouth-form axis; composite sums retain over-range values for the authored binding to clamp.
+ */
+export function voiceInputs(sample, faceInputs) {
+    const { volume, vowels } = sample;
+    // Vowel projection, not measured pitch: https://github.com/DenchiSoft/VTubeStudio/wiki/Lipsync
+    const frequency = 0.5 + (volume * (-0.9 * vowels.A - 0.7 * vowels.I - 0.6 * vowels.U + vowels.E + 0.9 * vowels.O)) / 2;
+    return {
+        VoiceVolume: volume,
+        VoiceFrequency: frequency,
+        VoiceVolumePlusMouthOpen: volume + (faceInputs?.MouthOpen ?? 0),
+        VoiceFrequencyPlusMouthSmile: faceInputs?.MouthSmile === undefined ? frequency : faceInputs.MouthSmile + (frequency - 0.5) * 2,
+        VoiceA: volume * vowels.A,
+        VoiceI: volume * vowels.I,
+        VoiceU: volume * vowels.U,
+        VoiceE: volume * vowels.E,
+        VoiceO: volume * vowels.O,
+        VoiceSilence: 1 - volume,
+        VoiceMouthOpen: volume * (vowels.A + 0.4 * vowels.I + 0.4 * vowels.U + 0.7 * vowels.E + vowels.O),
+        VoiceMouthSpread: volume * (vowels.A + vowels.I - vowels.U + vowels.E - vowels.O),
+    };
+}

package/dist/values/locale.d.ts

@@ -3,6 +3,8 @@ export declare const LOCALES: readonly ["en", "ja", "zh-CN", "zh-TW"];
 export type Locale = (typeof LOCALES)[number];
 /** `ui.language` setting: an explicit locale, or follow the OS language. */
 export type LanguageSetting = 'system' | Locale;
+/** `ui.theme` setting: an explicit appearance, or follow the OS. */
+export type ThemeSetting = 'system' | 'light' | 'dark';
 /** Native-language display names for the language picker (deliberately untranslated). */
 export declare const LOCALE_LABELS: Record<Locale, string>;
 /** Best supported locale for a BCP 47-ish tag: exact match first, then fuzzy per language. */

package/dist/values/model-info.d.ts

@@ -0,0 +1,66 @@
+import type { ContentOrigin } from '../wire/types.ts';
+/** Which VRM specification the file declares. */
+export type VrmSpec = '0.x' | '1.0';
+/** Everything the panel reports about a Live2D model on stage. */
+export interface Live2DModelInfo {
+    format: 'live2d';
+    name: string;
+    origin: ContentOrigin;
+    file: string;
+    /** Config sidecars found next to the entry file (`*.vtube.json`, `*.persona.json`). */
+    configFiles: string[];
+    canvas: {
+        width: number;
+        height: number;
+    };
+    /** `csmMocVersion` of the model's own moc3, or null when the header couldn't be read. */
+    mocVersion: number | null;
+    /** Highest `csmMocVersion` the vendored Core can load (`csmGetLatestMocVersion()`). */
+    coreMocVersion: number;
+    /** Packed uint32 from `csmGetVersion()`; 0 when the Core global is missing. */
+    coreVersion: number;
+    params: number;
+    parts: number;
+    /** Pixel size of each loaded texture atlas. */
+    textureSizes: {
+        width: number;
+        height: number;
+    }[];
+    motionGroups: number;
+    motionTotal: number;
+    expressions: number;
+    /** Param ids the auto eye-blink drives (the engine falls back to standard params when undeclared). */
+    eyeBlinkParams: string[];
+    /** Param ids of the model's `LipSync` group; empty means lip sync cannot move the mouth. */
+    lipSyncParams: string[];
+    /** How many distinct raw ARKit channels the rig's bindings read; 52 is full perfect sync. */
+    arkitInputs: number;
+    /** Optional subsystems that loaded, e.g. `['physics', 'pose']`. */
+    extras: string[];
+    /** Wall-clock ms the stage spent loading the model. */
+    loadMs: number;
+}
+/** What the panel reports about a VRM on stage. */
+export interface VrmModelInfo {
+    format: 'vrm';
+    name: string;
+    origin: ContentOrigin;
+    file: string;
+    spec: VrmSpec;
+    specVersion: string;
+    /** Every glTF extension the file declares, in file order; the rows split them by stage support. */
+    extensions: string[];
+    humanBones: number;
+    springGroups: number;
+    expressions: number;
+    /** How many of the 52 ARKit shapes the expressions cover; 52 enables perfect-sync tracking. */
+    arkitExpressions: number;
+    authors: string[];
+    licenseUrl: string | null;
+    /** VRM 1.0 `creditNotation === 'required'`; always false for 0.x. */
+    creditRequired: boolean;
+    /** Wall-clock ms the stage spent loading the model. */
+    loadMs: number;
+}
+/** Everything the panel reports about the model currently on stage. */
+export type ModelInfo = Live2DModelInfo | VrmModelInfo;

package/dist/values/model-info.js

@@ -0,0 +1 @@
+export {};

package/dist/values/stage-info.d.ts

@@ -0,0 +1,27 @@
+/** Decoded image/video pixels, or a web object's configured viewport pixels, before placement. */
+export interface ObjectMediaSize {
+    width: number;
+    height: number;
+}
+/** One light baked into a prop asset, as the panel lists it. `index` is the override key. */
+export interface BakedLightInfo {
+    index: number;
+    /** Node name from the asset; may be empty. */
+    name: string;
+    type: 'point' | 'spot' | 'directional';
+    /** The asset's own intensity after normalization, in scene-slider units. */
+    defaultIntensity: number;
+}
+/** Loaded asset metadata; absent dimensions/extensions mean the asset has not reported them yet. */
+export interface SceneAssetInfo {
+    assetId: string | null;
+    lights: BakedLightInfo[];
+    extensions: string[] | null;
+    mediaSize: ObjectMediaSize | null;
+}
+/** Metadata for the active scene, tagged so a response from a previous scene can be discarded. */
+export interface SceneInspection {
+    sceneId: string;
+    environment: Omit<SceneAssetInfo, 'mediaSize'>;
+    objects: Record<string, SceneAssetInfo>;
+}

package/dist/values/stage-info.js

@@ -0,0 +1 @@
+export {};

package/dist/values/vrm-bindings.d.ts

@@ -0,0 +1,14 @@
+/** Where a VRM binding target lands; expressions are the model's own, the rest are pose offsets. */
+export type VrmBindingGroup = 'head' | 'body' | 'gaze' | 'expressions';
+export interface VrmPoseTarget {
+    id: string;
+    group: Exclude<VrmBindingGroup, 'expressions'>;
+    /** Symmetric range in degrees. */
+    range: number;
+}
+/** The generated VRM binding targets, in degrees; each is an offset layered over the current pose. */
+export declare const VRM_POSE_TARGETS: readonly VrmPoseTarget[];
+/** The binding target id for a VRM expression, keeping the model author's spelling. */
+export declare function vrmExpressionTarget(name: string): string;
+/** The expression behind a VRM binding target id; null for a pose target. */
+export declare function vrmExpressionName(id: string): string | null;

package/dist/values/vrm-bindings.js

@@ -0,0 +1,20 @@
+/** The generated VRM binding targets, in degrees; each is an offset layered over the current pose. */
+export const VRM_POSE_TARGETS = [
+    { id: 'HeadYaw', group: 'head', range: 30 },
+    { id: 'HeadPitch', group: 'head', range: 30 },
+    { id: 'HeadRoll', group: 'head', range: 30 },
+    { id: 'BodyYaw', group: 'body', range: 15 },
+    { id: 'BodyPitch', group: 'body', range: 15 },
+    { id: 'BodyRoll', group: 'body', range: 15 },
+    { id: 'GazeYaw', group: 'gaze', range: 90 },
+    { id: 'GazePitch', group: 'gaze', range: 90 },
+];
+const VRM_EXPRESSION_PREFIX = 'Expression:';
+/** The binding target id for a VRM expression, keeping the model author's spelling. */
+export function vrmExpressionTarget(name) {
+    return `${VRM_EXPRESSION_PREFIX}${name}`;
+}
+/** The expression behind a VRM binding target id; null for a pose target. */
+export function vrmExpressionName(id) {
+    return id.startsWith(VRM_EXPRESSION_PREFIX) ? id.slice(VRM_EXPRESSION_PREFIX.length) : null;
+}

package/dist/wire/events.d.ts

@@ -14,7 +14,7 @@ export interface EventMap {
     'shortcut.state': {
         shortcuts: ShortcutInfo[];
     };
-    /** `sources` maps source id → status; optional so pre-multi-source servers still parse. */
+    /** Network channel aggregates; `sources` includes webcam status and is optional for older servers. */
     'tracking.status': {
         tracking: TrackingStatus;
         pose: PoseStatus;