@laplace.live/persona-sdk 1.3.0 → 1.5.0

package/dist/client/client.d.ts

@@ -47,6 +47,7 @@ export interface PersonaClientOptions {
     reconnect?: boolean;
     reconnectDelayMs?: number;
     reconnectDelayMaxMs?: number;
+    /** Override every request timeout; defaults to 10 seconds, or 120 seconds for scene activation. */
     requestTimeoutMs?: number;
     /** Bound each awaited {@link PersonaClient.connect} — on expiry it rejects while the attempt keeps going. */
     connectTimeoutMs?: number;

package/dist/client/client.js

@@ -1,6 +1,6 @@
 import { parseServerMessage } from "../wire/envelope.js";
 import { PersonaApiError } from "../wire/errors.js";
-import { CLOSE_FORCE_DISCONNECTED, CLOSE_KEY_REVOKED, INJECT_HEARTBEAT_MS, injectTargetKey, PROTOCOL_VERSION, } from "../wire/protocol.js";
+import { CLOSE_FORCE_DISCONNECTED, CLOSE_KEY_REVOKED, INJECT_HEARTBEAT_MS, injectTargetKey, PROTOCOL_VERSION, SCENE_ACTIVATION_TIMEOUT_MS, } from "../wire/protocol.js";
 import { personaWsUrl } from "./address.js";
 const DEFAULTS = {
     url: personaWsUrl(),
@@ -107,7 +107,8 @@ export class PersonaClient {
             const timer = setTimeout(() => {
                 this.pending.delete(id);
                 reject(new Error(`request timed out: ${method}`));
-            }, this.opts.requestTimeoutMs ?? DEFAULTS.requestTimeoutMs);
+            }, this.opts.requestTimeoutMs ??
+                (method === 'scene.activate' ? SCENE_ACTIVATION_TIMEOUT_MS : DEFAULTS.requestTimeoutMs));
             this.pending.set(id, { resolve: resolve, reject, timer });
             ws.send(JSON.stringify({ kind: 'request', id, method, ...(params === undefined ? {} : { params }) }));
         });

package/dist/index.d.ts

@@ -15,6 +15,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/scene-transition.ts';
 export * from './values/stage-info.ts';
 export * from './values/terms.ts';
 export * from './values/vrm-bindings.ts';

package/dist/index.js

@@ -17,6 +17,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/scene-transition.js";
 export * from "./values/stage-info.js";
 export * from "./values/terms.js";
 export * from "./values/vrm-bindings.js";

package/dist/values/controller.d.ts

@@ -2,17 +2,6 @@
 export type ControllerSlot = number;
 /** Whether a value can identify a persistent controller profile. */
 export declare function isControllerSlot(value: unknown): value is ControllerSlot;
-/** Standard gamepad controls, using VTS's parameter names for the first controller. */
-export declare const BASE_CONTROLLER_INPUT_NAMES: readonly ["ControllerStickLeftX", "ControllerStickLeftY", "ControllerStickRightX", "ControllerStickRightY", "ControllerStickPressLeft", "ControllerStickPressRight", "ControllerDPadX", "ControllerDPadY", "ControllerCross", "ControllerCircle", "ControllerSquare", "ControllerTriangle", "ControllerShoulderLeft", "ControllerShoulderRight", "ControllerTriggerLeft", "ControllerTriggerRight", "ControllerOptionLeft", "ControllerOptionRight", "ControllerHome"];
-export type BaseControllerInputName = (typeof BASE_CONTROLLER_INPUT_NAMES)[number];
-type NumberedControllerName<T extends string> = T extends `Controller${infer Control}` ? `Controller${number}${Control}` : never;
-export type ControllerInputName = BaseControllerInputName | NumberedControllerName<BaseControllerInputName>;
-/** Address a parameter on one controller; slot 1 retains its original VTS name. */
-export declare function controllerInputName(base: BaseControllerInputName, slot: ControllerSlot): ControllerInputName;
-/** Remove a controller parameter's slot prefix for shared labels and ranges. */
-export declare function baseControllerInputName(full: ControllerInputName): BaseControllerInputName;
-/** Whether an input names a supported controller parameter. */
-export declare function isControllerInputName(v: string): v is ControllerInputName;
 /** Stick and D-pad axes are signed, with positive Y pointing up; other controls are 0..1. */
 export declare const BASE_CONTROLLER_INPUT_RANGES: {
     readonly ControllerStickLeftX: readonly [-1, 1];
@@ -35,6 +24,17 @@ export declare const BASE_CONTROLLER_INPUT_RANGES: {
     readonly ControllerOptionRight: readonly [0, 1];
     readonly ControllerHome: readonly [0, 1];
 };
+/** Standard gamepad controls, using VTS's parameter names for the first controller. */
+export declare const BASE_CONTROLLER_INPUT_NAMES: readonly BaseControllerInputName[];
+export type BaseControllerInputName = keyof typeof BASE_CONTROLLER_INPUT_RANGES;
+type NumberedControllerName<T extends string> = T extends `Controller${infer Control}` ? `Controller${number}${Control}` : never;
+export type ControllerInputName = BaseControllerInputName | NumberedControllerName<BaseControllerInputName>;
+/** Address a parameter on one controller; slot 1 retains its original VTS name. */
+export declare function controllerInputName(base: BaseControllerInputName, slot: ControllerSlot): ControllerInputName;
+/** Remove a controller parameter's slot prefix for shared labels and ranges. */
+export declare function baseControllerInputName(full: ControllerInputName): BaseControllerInputName;
+/** Whether an input names a supported controller parameter. */
+export declare function isControllerInputName(v: string): v is ControllerInputName;
 /** Natural parameter range, shared by every controller profile. */
 export declare function controllerInputRange(name: ControllerInputName): readonly [number, number];
 /** VTS shortcut names differ from parameter names, especially shoulders, clicks and D-pad. */

package/dist/values/controller.js

@@ -1,31 +1,33 @@
-import { finiteOr, isRecord, nonEmptyString } from "./guards.js";
+import { finiteOr, isRecord, keysOf, nonEmptyString } from "./guards.js";
 import { clamp } from "./limits.js";
 /** Whether a value can identify a persistent controller profile. */
 export function isControllerSlot(value) {
     return typeof value === 'number' && Number.isSafeInteger(value) && value > 0;
 }
+/** Stick and D-pad axes are signed, with positive Y pointing up; other controls are 0..1. */
+export const BASE_CONTROLLER_INPUT_RANGES = {
+    ControllerStickLeftX: [-1, 1],
+    ControllerStickLeftY: [-1, 1],
+    ControllerStickRightX: [-1, 1],
+    ControllerStickRightY: [-1, 1],
+    ControllerStickPressLeft: [0, 1],
+    ControllerStickPressRight: [0, 1],
+    ControllerDPadX: [-1, 1],
+    ControllerDPadY: [-1, 1],
+    ControllerCross: [0, 1],
+    ControllerCircle: [0, 1],
+    ControllerSquare: [0, 1],
+    ControllerTriangle: [0, 1],
+    ControllerShoulderLeft: [0, 1],
+    ControllerShoulderRight: [0, 1],
+    ControllerTriggerLeft: [0, 1],
+    ControllerTriggerRight: [0, 1],
+    ControllerOptionLeft: [0, 1],
+    ControllerOptionRight: [0, 1],
+    ControllerHome: [0, 1],
+};
 /** Standard gamepad controls, using VTS's parameter names for the first controller. */
-export const BASE_CONTROLLER_INPUT_NAMES = [
-    'ControllerStickLeftX',
-    'ControllerStickLeftY',
-    'ControllerStickRightX',
-    'ControllerStickRightY',
-    'ControllerStickPressLeft',
-    'ControllerStickPressRight',
-    'ControllerDPadX',
-    'ControllerDPadY',
-    'ControllerCross',
-    'ControllerCircle',
-    'ControllerSquare',
-    'ControllerTriangle',
-    'ControllerShoulderLeft',
-    'ControllerShoulderRight',
-    'ControllerTriggerLeft',
-    'ControllerTriggerRight',
-    'ControllerOptionLeft',
-    'ControllerOptionRight',
-    'ControllerHome',
-];
+export const BASE_CONTROLLER_INPUT_NAMES = keysOf(BASE_CONTROLLER_INPUT_RANGES);
 /** Slot 1 keeps the bare VTS name; every other slot inserts its number after `Controller`. */
 function slotPrefixed(base, slot) {
     if (!isControllerSlot(slot))
@@ -56,28 +58,6 @@ export function isControllerInputName(v) {
     const parts = controllerParts(v);
     return parts !== null && CONTROLLER_INPUT_SET.has(parts.base);
 }
-/** Stick and D-pad axes are signed, with positive Y pointing up; other controls are 0..1. */
-export const BASE_CONTROLLER_INPUT_RANGES = {
-    ControllerStickLeftX: [-1, 1],
-    ControllerStickLeftY: [-1, 1],
-    ControllerStickRightX: [-1, 1],
-    ControllerStickRightY: [-1, 1],
-    ControllerStickPressLeft: [0, 1],
-    ControllerStickPressRight: [0, 1],
-    ControllerDPadX: [-1, 1],
-    ControllerDPadY: [-1, 1],
-    ControllerCross: [0, 1],
-    ControllerCircle: [0, 1],
-    ControllerSquare: [0, 1],
-    ControllerTriangle: [0, 1],
-    ControllerShoulderLeft: [0, 1],
-    ControllerShoulderRight: [0, 1],
-    ControllerTriggerLeft: [0, 1],
-    ControllerTriggerRight: [0, 1],
-    ControllerOptionLeft: [0, 1],
-    ControllerOptionRight: [0, 1],
-    ControllerHome: [0, 1],
-};
 /** Natural parameter range, shared by every controller profile. */
 export function controllerInputRange(name) {
     return BASE_CONTROLLER_INPUT_RANGES[baseControllerInputName(name)];

package/dist/values/curve.d.ts

@@ -8,7 +8,7 @@
  * `outRange` is what puts it in Cubism units.
  */
 /** Governs the segment *leaving* a keyframe; the last keyframe's is never read. */
-export type Interpolation = 'linear' | 'step' | 'invertStep' | 'bezier';
+export type Interpolation = (typeof INTERPOLATIONS)[number];
 export interface Point {
     x: number;
     y: number;
@@ -137,7 +137,7 @@ export declare function insertAnchor(keyframes: Keyframe[], at: Point): {
     index: number;
 };
 /** Every {@link Interpolation}, in the order an editor lists them. */
-export declare const INTERPOLATIONS: readonly Interpolation[];
+export declare const INTERPOLATIONS: readonly ["linear", "step", "invertStep", "bezier"];
 /**
  * A curve from an untrusted document — a config file or an IPC caller — or null when it
  * cannot be made into one. Anchors are clamped into the unit square and sorted by x, which is
@@ -154,8 +154,8 @@ export declare function sanitizeCurve(v: unknown): Curve | null;
  */
 export declare function identityCurve(): Curve;
 /** A ready-made response shape that replaces the whole curve; `linear` is the identity. */
-export type CurvePresetId = 'linear' | 'step' | 'invertStep' | 'bezier' | 'easeIn' | 'easeOut' | 'sCurve' | 'threshold' | 'steps';
-export declare const CURVE_PRESET_IDS: readonly CurvePresetId[];
+export type CurvePresetId = (typeof CURVE_PRESET_IDS)[number];
+export declare const CURVE_PRESET_IDS: readonly ["linear", "step", "invertStep", "bezier", "easeIn", "easeOut", "sCurve", "threshold", "steps"];
 /**
  * Fresh whole-curve shapes: endpoint holds, a Bezier ease-in-out, and shapes from VBridger's presets.
  * The remaining shapes are transcribed from its Unity curves

package/dist/values/effect-schema.d.ts

@@ -6,6 +6,8 @@ export declare const EFFECT_SCOPES: {
     readonly colorWheels: readonly ["scene", "layer"];
     readonly colorShift: readonly ["scene", "layer"];
     readonly selectColors: readonly ["scene", "layer"];
+    readonly gradient: readonly ["scene", "layer"];
+    readonly flare: readonly ["scene"];
     readonly blur: readonly ["scene", "layer"];
     readonly bloom: readonly ["scene", "layer"];
     readonly diffusion: readonly ["scene", "layer"];
@@ -66,6 +68,8 @@ export declare const EFFECT_SPECS: Record<EffectKey, Readonly<Record<string, Eff
 export declare const EFFECT_COLOR_SPECS: Partial<Record<EffectKey, Readonly<Record<string, EffectColorSpec>>>>;
 /** Boolean defaults, validated alongside numeric and color parameters. */
 export declare const EFFECT_BOOLEAN_SPECS: Partial<Record<EffectKey, Readonly<Record<string, EffectBooleanSpec>>>>;
+/** Blend-mode order shared by effect editors and shader uniforms. */
+export declare const EFFECT_BLEND_MODES: readonly ["normal", "darken", "multiply", "colorBurn", "linearBurn", "add", "lighten", "screen", "colorDodge", "overlay", "softLight", "hardLight", "vividLight", "linearLight", "pinLight", "hardMix", "difference", "exclusion", "subtract", "divide", "hue", "saturation", "color", "luminosity"];
 /** Enum defaults and allowed values. */
 export declare const EFFECT_ENUM_SPECS: Partial<Record<EffectKey, Readonly<Record<string, EffectEnumSpec>>>>;
 /** Select the layer effects from any value set containing them. */

package/dist/values/effect-schema.js

@@ -1,5 +1,5 @@
 // Scope and parameter metadata are plain data; labels and rendering stay with their consumers.
-import { finiteOr, isRecord } from "./guards.js";
+import { finiteOr, isOneOf, isRecord } from "./guards.js";
 import { clamp, hexColorOr } from "./limits.js";
 /** Supported owners of each toggle effect; scene and layer membership are independent. */
 export const EFFECT_SCOPES = {
@@ -8,6 +8,8 @@ export const EFFECT_SCOPES = {
     colorWheels: ['scene', 'layer'],
     colorShift: ['scene', 'layer'],
     selectColors: ['scene', 'layer'],
+    gradient: ['scene', 'layer'],
+    flare: ['scene'],
     blur: ['scene', 'layer'],
     bloom: ['scene', 'layer'],
     diffusion: ['scene', 'layer'],
@@ -26,7 +28,7 @@ export const EFFECT_SCOPES = {
 };
 export const EFFECT_KEYS = Object.keys(EFFECT_SCOPES);
 function keysForScope(scope) {
-    return EFFECT_KEYS.filter((key) => EFFECT_SCOPES[key].includes(scope));
+    return EFFECT_KEYS.filter((key) => isOneOf(scope, EFFECT_SCOPES[key]));
 }
 /** Older hosts advertise effect availability through the values present in their payload. */
 export function availableEffectKeys(scope, effects) {
@@ -122,6 +124,25 @@ export const EFFECT_SPECS = {
         saturation: { default: -1, min: -1, max: 1, step: 0.01 },
         blend: { default: 1, min: 0, max: 1, step: 0.01 },
     },
+    gradient: {
+        radius: { default: 1, min: 0, max: 3, step: 0.01 },
+        smoothness: { default: 1, min: 0, max: 5, step: 0.01 },
+        centerX: { default: 0, min: -1, max: 1, step: 0.01 },
+        centerY: { default: 0, min: -1, max: 1, step: 0.01 },
+        angle: { default: 0, min: -180, max: 180, step: 1, unit: '°' },
+        scaleX: { default: 1, min: 0, max: 2, step: 0.01 },
+        scaleY: { default: 0.5, min: 0, max: 2, step: 0.01 },
+        opacity: { default: 1, min: 0, max: 1, step: 0.01 },
+    },
+    flare: {
+        intensity: { default: 0, min: 0, max: 1, step: 0.01 },
+        size: { default: 0, min: 0, max: 2, step: 0.01 },
+        angle: { default: 0, min: -180, max: 180, step: 1, unit: '°' },
+        glowOpacity: { default: 1, min: 0, max: 1, step: 0.01 },
+        raysScale: { default: 0, min: 0, max: 1, step: 0.01 },
+        raysIntensity: { default: 0, min: 0, max: 1, step: 0.01 },
+        raysOpacity: { default: 1, min: 0, max: 1, step: 0.01 },
+    },
     blur: {
         radius: { default: 8, min: 0, max: 64, step: 0.5, unit: 'px' },
     },
@@ -240,6 +261,14 @@ export const EFFECT_SPECS = {
  * string param appear.
  */
 export const EFFECT_COLOR_SPECS = {
+    gradient: {
+        color: { default: '#ffffff' },
+        backgroundColor: { default: '#000000' },
+    },
+    flare: {
+        color: { default: '#ffffff' },
+        raysColor: { default: '#ffffff' },
+    },
     colorWheels: {
         liftColor: { default: '#ffffff' },
         gammaColor: { default: '#ffffff' },
@@ -280,6 +309,11 @@ export const EFFECT_COLOR_SPECS = {
 };
 /** Boolean defaults, validated alongside numeric and color parameters. */
 export const EFFECT_BOOLEAN_SPECS = {
+    flare: { rays: { default: false } },
+    gradient: {
+        invert: { default: false },
+        transparentBackground: { default: false },
+    },
     blur: { highQuality: { default: false } },
     bloom: {
         selectColors: { default: false },
@@ -306,40 +340,50 @@ export const EFFECT_BOOLEAN_SPECS = {
         color10Enabled: { default: false },
     },
 };
+/** Blend-mode order shared by effect editors and shader uniforms. */
+export const EFFECT_BLEND_MODES = [
+    'normal',
+    'darken',
+    'multiply',
+    'colorBurn',
+    'linearBurn',
+    'add',
+    'lighten',
+    'screen',
+    'colorDodge',
+    'overlay',
+    'softLight',
+    'hardLight',
+    'vividLight',
+    'linearLight',
+    'pinLight',
+    'hardMix',
+    'difference',
+    'exclusion',
+    'subtract',
+    'divide',
+    'hue',
+    'saturation',
+    'color',
+    'luminosity',
+];
 /** Enum defaults and allowed values. */
 export const EFFECT_ENUM_SPECS = {
+    flare: {
+        mode: { default: 'add', values: ['add', 'screen', 'colorDodge'] },
+        raysMode: { default: 'sun', values: ['sun', 'shine', 'god'] },
+    },
+    gradient: {
+        type: { default: 'circle', values: ['solid', 'linear', 'circle', 'ellipse'] },
+        blendMode: { default: 'normal', values: EFFECT_BLEND_MODES },
+    },
     blur: { mode: { default: 'gaussian', values: ['gaussian', 'bokeh'] } },
     bloom: { mode: { default: 'normal', values: ['normal', 'streak', 'star'] } },
     rim: {
         mode: { default: 'single', values: ['single', 'double', 'sharpenSingle', 'sharpenDouble'] },
         blendMode: {
             default: 'overlay',
-            values: [
-                'normal',
-                'darken',
-                'multiply',
-                'colorBurn',
-                'linearBurn',
-                'add',
-                'lighten',
-                'screen',
-                'colorDodge',
-                'overlay',
-                'softLight',
-                'hardLight',
-                'vividLight',
-                'linearLight',
-                'pinLight',
-                'hardMix',
-                'difference',
-                'exclusion',
-                'subtract',
-                'divide',
-                'hue',
-                'saturation',
-                'color',
-                'luminosity',
-            ],
+            values: EFFECT_BLEND_MODES,
         },
     },
     outline: { quality: { default: 'medium', values: ['low', 'medium', 'high'] } },
@@ -396,7 +440,9 @@ export const ALL_EFFECT_STACK_ORDER = [
     'colorWheels',
     'colorShift',
     'selectColors',
+    'gradient',
     'blur',
+    'flare',
     'pixelate',
     'glitch',
     'droplets',
@@ -404,9 +450,9 @@ export const ALL_EFFECT_STACK_ORDER = [
     'vignette',
 ];
 /** Scene composition order, retained under its existing SDK name. */
-export const EFFECT_STACK_ORDER = ALL_EFFECT_STACK_ORDER.filter((key) => SCENE_EFFECT_KEYS.includes(key));
+export const EFFECT_STACK_ORDER = ALL_EFFECT_STACK_ORDER.filter((key) => isOneOf(key, SCENE_EFFECT_KEYS));
 /** Layer composition order before the result joins the scene. */
-export const LAYER_EFFECT_STACK_ORDER = ALL_EFFECT_STACK_ORDER.filter((key) => LAYER_EFFECT_KEYS.includes(key));
+export const LAYER_EFFECT_STACK_ORDER = ALL_EFFECT_STACK_ORDER.filter((key) => isOneOf(key, LAYER_EFFECT_KEYS));
 /** Heal only the requested effect keys, using the same parameter kinds as defaults and editors. */
 export function healEffectValues(raw, keys) {
     const src = isRecord(raw) ? raw : {};

package/dist/values/guards.d.ts

@@ -1,5 +1,17 @@
 /** Plain-object check: object, non-null, and not an array. */
 export declare function isRecord(v: unknown): v is Record<string, unknown>;
+/**
+ * Membership test that narrows. `list.includes(v)` cannot take an `unknown`, and widening the
+ * list to `readonly string[]` to get there throws the narrowing away — so every caller ended up
+ * asserting the result back. Comparing element-wise keeps `T` in hand.
+ */
+export declare function isOneOf<T extends string>(v: unknown, list: readonly T[]): v is T;
+/**
+ * `Object.keys` typed to the record's own keys. TS widens to `string[]` because a value can
+ * carry keys its type never listed — true of an open object, not of the closed literal tables
+ * this is for, so callers own that the record is exactly its type.
+ */
+export declare function keysOf<T extends object>(o: T): (keyof T & string)[];
 /** Finite-number type guard (rejects NaN and ±Infinity). */
 export declare function isFiniteNumber(v: unknown): v is number;
 /** The value when it is a finite number, else `fallback`. */

package/dist/values/guards.js

@@ -3,6 +3,22 @@
 export function isRecord(v) {
     return typeof v === 'object' && v !== null && !Array.isArray(v);
 }
+/**
+ * Membership test that narrows. `list.includes(v)` cannot take an `unknown`, and widening the
+ * list to `readonly string[]` to get there throws the narrowing away — so every caller ended up
+ * asserting the result back. Comparing element-wise keeps `T` in hand.
+ */
+export function isOneOf(v, list) {
+    return list.some(item => item === v);
+}
+/**
+ * `Object.keys` typed to the record's own keys. TS widens to `string[]` because a value can
+ * carry keys its type never listed — true of an open object, not of the closed literal tables
+ * this is for, so callers own that the record is exactly its type.
+ */
+export function keysOf(o) {
+    return Object.keys(o);
+}
 /** Finite-number type guard (rejects NaN and ±Infinity). */
 export function isFiniteNumber(v) {
     return typeof v === 'number' && Number.isFinite(v);

package/dist/values/hands.d.ts

@@ -1,25 +1,3 @@
-/** 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];
@@ -51,3 +29,25 @@ export declare const HAND_INPUT_RANGES: {
     readonly BothHandsFound: readonly [0, 1];
     readonly HandDistance: readonly [0, 10];
 };
+/** VTube Studio hand inputs, extended with nizima LIVE's wrist Y rotation. */
+export declare const HAND_INPUT_NAMES: readonly HandInputName[];
+export type HandInputName = keyof typeof HAND_INPUT_RANGES;
+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;

package/dist/values/hands.js

@@ -1,61 +1,4 @@
-/** 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;
-}
+import { keysOf } from "./guards.js";
 /** Angles are degrees; positions and distance use VTS's ten-unit scale. */
 export const HAND_INPUT_RANGES = {
     HandLeftFound: [0, 1],
@@ -87,3 +30,32 @@ export const HAND_INPUT_RANGES = {
     BothHandsFound: [0, 1],
     HandDistance: [0, 10],
 };
+/** VTube Studio hand inputs, extended with nizima LIVE's wrist Y rotation. */
+export const HAND_INPUT_NAMES = keysOf(HAND_INPUT_RANGES);
+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;
+}

package/dist/values/hotkeys.d.ts

@@ -9,6 +9,20 @@ export declare function hasCommandModifier(accelerator: string | null): boolean;
 export declare function canRunInBackground(accelerator: string | null): boolean;
 /** True when a model hotkey is meant to fire while Persona sits in the background — what main registers on, and what the globe shows. */
 export declare function hotkeyRunsInBackground(h: Hotkey): boolean;
+/** Automations are enabled unless explicitly paused. */
+export declare function automationEnabled(s: {
+    enabled?: boolean;
+}): boolean;
+/**
+ * True when an automation claims its combo — what main registers with the OS and what the
+ * renderer binds controllers to. The two must agree or a combo fires nothing, or nothing owns it.
+ */
+export declare function automationBindable<T extends {
+    enabled?: boolean;
+    accelerator: string | null;
+}>(s: T): s is T & {
+    accelerator: string;
+};
 /** Accelerators bound by more than one entry — the warning every shortcut list raises. */
 export declare function duplicateAccelerators(bindings: readonly {
     accelerator: string | null;

package/dist/values/hotkeys.js

@@ -1,6 +1,7 @@
 // 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";
+import { isOneOf } from "./guards.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'];
@@ -8,7 +9,7 @@ const COMMAND_MODIFIERS = ['Control', 'Alt', 'Super'];
 export function hasCommandModifier(accelerator) {
     if (accelerator === null)
         return false;
-    return accelerator.split('+').some(t => COMMAND_MODIFIERS.includes(t));
+    return accelerator.split('+').some(t => isOneOf(t, COMMAND_MODIFIERS));
 }
 /**
  * True when `global` can apply: a command-modifier combo registers with the OS, and a controller
@@ -24,6 +25,17 @@ export function canRunInBackground(accelerator) {
 export function hotkeyRunsInBackground(h) {
     return h.global && h.active && h.action !== null && canRunInBackground(h.accelerator);
 }
+/** Automations are enabled unless explicitly paused. */
+export function automationEnabled(s) {
+    return s.enabled !== false;
+}
+/**
+ * True when an automation claims its combo — what main registers with the OS and what the
+ * renderer binds controllers to. The two must agree or a combo fires nothing, or nothing owns it.
+ */
+export function automationBindable(s) {
+    return automationEnabled(s) && s.accelerator !== null;
+}
 /** Accelerators bound by more than one entry — the warning every shortcut list raises. */
 export function duplicateAccelerators(bindings) {
     const seen = new Set();