@laplace.live/persona-sdk 1.18.0 → 1.20.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/model-movement.ts';
 export * from './values/mouse.ts';
 export * from './values/scene-transition.ts';
 export * from './values/stage-info.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/model-movement.js";
 export * from "./values/mouse.js";
 export * from "./values/scene-transition.js";
 export * from "./values/stage-info.js";

package/dist/values/hotkeys.d.ts

@@ -9,6 +9,17 @@ 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;
+/**
+ * Why a `hold` hotkey toggles instead of holding, or null when it can hold. A combo registered with
+ * the OS reaches Persona as a press alone — Electron reports no key-up for it — and one registration
+ * serves every hotkey on the combo: `'own'` when this hotkey asks for the background itself,
+ * `'shared'` when only another one on its combo does, which `registered` (main's list) alone can tell.
+ */
+export declare function holdBlockedBy(h: Pick<Hotkey, 'hold' | 'global' | 'accelerator'>, registered: boolean): 'own' | 'shared' | null;
+/** VTS's editor limits for a hotkey's fade and auto-off times, in seconds; healing clamps API input to them. */
+export declare const HOTKEY_FADE_SECONDS_MAX = 2;
+export declare const HOTKEY_DEACTIVATE_SECONDS_MIN = 0.1;
+export declare const HOTKEY_DEACTIVATE_SECONDS_MAX = 3600;
 /** Automations are enabled unless explicitly paused. */
 export declare function automationEnabled(s: {
     enabled?: boolean;
@@ -27,3 +38,25 @@ export declare function automationBindable<T extends {
 export declare function duplicateAccelerators(bindings: readonly {
     accelerator: string | null;
 }[]): Set<string>;
+/** The slice of a scene model item the ordering reads; a full `SceneModelItem` comes back as itself. */
+interface HotkeyModelLike {
+    kind: 'model';
+    instanceId: string;
+    ref: {
+        id: string;
+    };
+}
+/**
+ * The models whose hotkeys are live — every model in the scene, the primary first, one per model id
+ * (a model on two layers lists once). The desktop fires all of them, VTS-style, and every shortcut
+ * list shows them in this order; `hotkey.list`/`hotkey.trigger` take each one's `ref.id` as `modelId`.
+ * Generic over the item union so a scene document and the desktop's loaded runtimes both infer.
+ */
+export declare function hotkeyModels<T extends HotkeyModelLike | {
+    kind: 'object';
+    instanceId: string;
+}>(scene: {
+    items: readonly T[];
+    primaryInstanceId: string | null;
+}): Extract<T, HotkeyModelLike>[];
+export {};

package/dist/values/hotkeys.js

@@ -25,6 +25,23 @@ export function canRunInBackground(accelerator) {
 export function hotkeyRunsInBackground(h) {
     return h.global && h.active && h.action !== null && canRunInBackground(h.accelerator);
 }
+/**
+ * Why a `hold` hotkey toggles instead of holding, or null when it can hold. A combo registered with
+ * the OS reaches Persona as a press alone — Electron reports no key-up for it — and one registration
+ * serves every hotkey on the combo: `'own'` when this hotkey asks for the background itself,
+ * `'shared'` when only another one on its combo does, which `registered` (main's list) alone can tell.
+ */
+export function holdBlockedBy(h, registered) {
+    if (h.hold !== true)
+        return null;
+    if (h.global && hasCommandModifier(h.accelerator))
+        return 'own';
+    return registered ? 'shared' : null;
+}
+/** VTS's editor limits for a hotkey's fade and auto-off times, in seconds; healing clamps API input to them. */
+export const HOTKEY_FADE_SECONDS_MAX = 2;
+export const HOTKEY_DEACTIVATE_SECONDS_MIN = 0.1;
+export const HOTKEY_DEACTIVATE_SECONDS_MAX = 3600;
 /** Automations are enabled unless explicitly paused. */
 export function automationEnabled(s) {
     return s.enabled !== false;
@@ -49,3 +66,22 @@ export function duplicateAccelerators(bindings) {
     }
     return dupes;
 }
+/**
+ * The models whose hotkeys are live — every model in the scene, the primary first, one per model id
+ * (a model on two layers lists once). The desktop fires all of them, VTS-style, and every shortcut
+ * list shows them in this order; `hotkey.list`/`hotkey.trigger` take each one's `ref.id` as `modelId`.
+ * Generic over the item union so a scene document and the desktop's loaded runtimes both infer.
+ */
+export function hotkeyModels(scene) {
+    const models = scene.items.filter((i) => i.kind === 'model');
+    const primary = models.find(i => i.instanceId === scene.primaryInstanceId);
+    const out = [];
+    const seen = new Set();
+    for (const item of primary ? [primary, ...models] : models) {
+        if (seen.has(item.ref.id))
+            continue;
+        seen.add(item.ref.id);
+        out.push(item);
+    }
+    return out;
+}

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

@@ -0,0 +1,29 @@
+/**
+ * VTube Studio's Movement Config: how far tracked face position slides (`x`, `y`) and scales (`z`)
+ * a whole Live2D model. It moves the model itself and never writes a parameter, so it stacks with
+ * a rig that binds `FacePositionZ` to a parameter of its own. Amounts are signed — a negative one
+ * inverts its axis, 0 switches it off.
+ */
+export interface ModelMovementConfig {
+    enabled: boolean;
+    x: number;
+    y: number;
+    z: number;
+    /** Smoothing levels 0–100, read once when the model loads; file-only, as in VTS. */
+    smoothingX: number;
+    smoothingY: number;
+    smoothingZ: number;
+}
+/** VTS's slider limit (`MAX_MOVEMENT`): an edited amount is a whole number within ±20. */
+export declare const MODEL_MOVEMENT_MAX = 20;
+/** VTS's `ModelPositionMovement` field initializers — a model nobody configured moves by default. */
+export declare const DEFAULT_MODEL_MOVEMENT: Readonly<ModelMovementConfig>;
+/**
+ * A stored or relayed configuration, read per field over the defaults. Amounts are taken as
+ * written: VTS clamps its sliders to ±20, never what a file holds.
+ */
+export declare function healModelMovement(raw: unknown): ModelMovementConfig;
+/** What the Movement Config editor changes; a file's smoothing levels are left as they are. */
+export type ModelMovementEdit = Partial<Pick<ModelMovementConfig, 'enabled' | 'x' | 'y' | 'z'>>;
+/** An edit healed to the editor's limits; an absent or unusable field is dropped, not defaulted. */
+export declare function healModelMovementEdit(raw: unknown): ModelMovementEdit;

package/dist/values/model-movement.js

@@ -0,0 +1,44 @@
+import { finiteOr, isFiniteNumber, isRecord } from "./guards.js";
+import { clamp } from "./limits.js";
+/** VTS's slider limit (`MAX_MOVEMENT`): an edited amount is a whole number within ±20. */
+export const MODEL_MOVEMENT_MAX = 20;
+/** VTS's `ModelPositionMovement` field initializers — a model nobody configured moves by default. */
+export const DEFAULT_MODEL_MOVEMENT = {
+    enabled: true,
+    x: 6,
+    y: 8,
+    z: 11,
+    smoothingX: 10,
+    smoothingY: 10,
+    smoothingZ: 10,
+};
+/**
+ * A stored or relayed configuration, read per field over the defaults. Amounts are taken as
+ * written: VTS clamps its sliders to ±20, never what a file holds.
+ */
+export function healModelMovement(raw) {
+    const r = isRecord(raw) ? raw : {};
+    const d = DEFAULT_MODEL_MOVEMENT;
+    return {
+        enabled: typeof r.enabled === 'boolean' ? r.enabled : d.enabled,
+        x: finiteOr(r.x, d.x),
+        y: finiteOr(r.y, d.y),
+        z: finiteOr(r.z, d.z),
+        smoothingX: finiteOr(r.smoothingX, d.smoothingX),
+        smoothingY: finiteOr(r.smoothingY, d.smoothingY),
+        smoothingZ: finiteOr(r.smoothingZ, d.smoothingZ),
+    };
+}
+/** An edit healed to the editor's limits; an absent or unusable field is dropped, not defaulted. */
+export function healModelMovementEdit(raw) {
+    const r = isRecord(raw) ? raw : {};
+    const edit = {};
+    if (typeof r.enabled === 'boolean')
+        edit.enabled = r.enabled;
+    for (const axis of ['x', 'y', 'z']) {
+        const v = r[axis];
+        if (isFiniteNumber(v))
+            edit[axis] = clamp(Math.round(v), -MODEL_MOVEMENT_MAX, MODEL_MOVEMENT_MAX);
+    }
+    return edit;
+}

package/dist/wire/events.d.ts

@@ -1,3 +1,4 @@
+import type { ModelMovementConfig } from '../values/model-movement.ts';
 import type { AutomationInfo, ExpressionPersistence, HotkeyState, ModelFormat, PoseStatus, SceneState, Settings, TrackingStatus } from './types.ts';
 /** Every push event a session can subscribe to, with its payload. */
 export interface EventMap {
@@ -6,6 +7,10 @@ export interface EventMap {
     'settings.changed': {
         settings: Settings;
     };
+    /**
+     * One model's live hotkey set changed — every model on stage has one, and a model that just left the
+     * stage arrives empty. Older hosts sent `modelId: null` for an empty stage instead.
+     */
     'hotkey.state': {
         modelId: string | null;
         config: HotkeyState;
@@ -66,6 +71,11 @@ export interface EventMap {
         modelId: string;
         persistence: ExpressionPersistence;
     };
+    /** A model's Movement Config changed, from any editor; every instance of the model follows it. */
+    'model.movement': {
+        modelId: string;
+        movement: ModelMovementConfig;
+    };
 }
 export type EventName = keyof EventMap;
 export type EventData<E extends EventName = EventName> = EventMap[E];

package/dist/wire/events.js

@@ -17,6 +17,7 @@ export const EVENT_NAMES = Object.keys({
     'selection.changed': true,
     'registry.changed': true,
     'expression.persistence': true,
+    'model.movement': true,
 });
 export function isEventName(v) {
     return isOneOf(v, EVENT_NAMES);

package/dist/wire/methods.d.ts

@@ -2,6 +2,7 @@ import type { Binding, BindingEditorData, BindingLiveValues } from '../values/bi
 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 { ModelMovementConfig, ModelMovementEdit } from '../values/model-movement.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, TrackingLostBehavior, TrackingSourceConfig, TrackingSourceId, TrackingSourceKind, TrackingStatus, VrmPlacement } from './types.ts';
@@ -340,6 +341,8 @@ export interface HotkeySetRequest {
 export type HotkeySetResponse = HotkeyState;
 export interface HotkeyTriggerRequest {
     hotkeyId: string;
+    /** The model that owns the hotkey — every model on stage has a live set; defaults to the primary. */
+    modelId?: string;
 }
 export type HotkeyTriggerResponse = EmptyResponse;
 export type AutomationListRequest = EmptyRequest;
@@ -631,6 +634,23 @@ export interface BindingOverrideRequest extends BindingTarget {
     value: number | null;
 }
 export type BindingOverrideResponse = EmptyResponse;
+/** `modelId` defaults to the primary model's; movement is Live2D-only. */
+export interface ModelGetMovementRequest {
+    modelId?: string;
+}
+export interface ModelGetMovementResponse {
+    movement: ModelMovementConfig;
+}
+export interface ModelSetMovementRequest {
+    modelId?: string;
+    movement: ModelMovementEdit;
+}
+export interface ModelSetMovementResponse {
+    /** The configuration now moving the model, whether or not it reached the file. */
+    movement: ModelMovementConfig;
+    /** False when nothing reached the file: a refused write (read-only, unreadable), or no usable field. */
+    saved: boolean;
+}
 export interface InstanceSetBreathRequest {
     instanceId: string;
     breath?: boolean;
@@ -972,6 +992,14 @@ export interface MethodMap {
         request: ModelRegisterRequest;
         response: ModelRegisterResponse;
     };
+    'model.getMovement': {
+        request: ModelGetMovementRequest;
+        response: ModelGetMovementResponse;
+    };
+    'model.setMovement': {
+        request: ModelSetMovementRequest;
+        response: ModelSetMovementResponse;
+    };
     'asset.register': {
         request: AssetRegisterRequest;
         response: AssetRegisterResponse;

package/dist/wire/methods.js

@@ -60,6 +60,8 @@ export const METHOD_NAMES = Object.keys({
     'automation.run': true,
     'model.list': true,
     'model.register': true,
+    'model.getMovement': true,
+    'model.setMovement': true,
     'asset.list': true,
     'asset.register': true,
     'registry.thumbnail': true,

package/dist/wire/schemas/requests.d.ts

@@ -163,6 +163,7 @@ export declare const requestSchemas: {
     }, z.core.$strip>;
     'hotkey.trigger': z.ZodObject<{
         hotkeyId: z.ZodString;
+        modelId: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
     'automation.run': z.ZodObject<{
         automationId: z.ZodString;
@@ -215,6 +216,13 @@ export declare const requestSchemas: {
     'model.register': z.ZodObject<{
         path: z.ZodString;
     }, z.core.$strip>;
+    'model.getMovement': z.ZodObject<{
+        modelId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    'model.setMovement': z.ZodObject<{
+        modelId: z.ZodOptional<z.ZodString>;
+        movement: z.ZodCustom<Partial<Pick<import("../../index.ts").ModelMovementConfig, "enabled" | "x" | "y" | "z">>, Partial<Pick<import("../../index.ts").ModelMovementConfig, "enabled" | "x" | "y" | "z">>>;
+    }, z.core.$strip>;
     'asset.register': z.ZodObject<{
         path: z.ZodString;
         want: z.ZodOptional<z.ZodEnum<{

package/dist/wire/schemas/requests.js

@@ -107,7 +107,7 @@ export const requestSchemas = {
         modelId: nonEmpty.optional(),
         config: z.custom(isRecord, 'config must be a hotkey config'),
     }),
-    'hotkey.trigger': z.object({ hotkeyId: nonEmpty }),
+    'hotkey.trigger': z.object({ hotkeyId: nonEmpty, modelId: nonEmpty.optional() }),
     'automation.run': z.object({ automationId: nonEmpty }),
     'tracking.addSource': z.object({
         // Straight off the kind registry, for the same reason as ASSET_KINDS below: a schema
@@ -128,6 +128,12 @@ export const requestSchemas = {
     }),
     'tracking.removeSource': z.object({ id: nonEmpty }),
     'model.register': z.object({ path: nonEmpty }),
+    'model.getMovement': z.object({ modelId: nonEmpty.optional() }),
+    // Healed by the host like the desktop editor's own edits, so only the shape is checked here.
+    'model.setMovement': z.object({
+        modelId: nonEmpty.optional(),
+        movement: z.custom(isRecord, 'movement must be an object'),
+    }),
     // Straight off ASSET_KINDS: a kind added there has to reach the wire gate too, or
     // `want` answers invalid-params for a kind the registry already knows how to take.
     'asset.register': z.object({ path: nonEmpty, want: z.enum(ASSET_KINDS).optional() }),

package/dist/wire/types.d.ts

@@ -1011,7 +1011,7 @@ export interface Scene {
     name: string;
     /** Models and objects in one list; array order = z-order (bottom to top) within each space. */
     items: SceneItem[];
-    /** Hotkey target and the default instance for model-scoped methods. null only when `items` holds no model. */
+    /** The default hotkey target and the default instance for model-scoped methods. null only when `items` holds no model. */
     primaryInstanceId: string | null;
     background: SceneBackground;
     vrmCamera: SceneCamera;
@@ -1041,7 +1041,7 @@ 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", "tracking-lost", "motion-stop", "stage-capture"];
+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", "motion-stop", "stage-capture", "model-movement"];
 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`. */
@@ -1115,13 +1115,21 @@ export interface Hotkey {
     accelerator: string | null;
     global: boolean;
     active: boolean;
+    /** Expression: on only while the combo is held down (VTS `DeactivateAfterKeyUp`). Default false. */
+    hold?: boolean;
+    /** Fade time in seconds, in and out, of the expression or motion; null uses the file's own. 0–2. */
+    fadeSeconds?: number | null;
+    /** Expression: switches itself off after this many seconds. Motion: plays at most this long. null is off. 0.1–3600. */
+    deactivateAfterSeconds?: number | null;
+    /** Motion: holds its last frame until the hotkey fires again (VTS `StopsOnLastFrame`). Default false. */
+    stopsOnLastFrame?: boolean;
 }
 export interface HotkeyConfig {
     keyboardEnabled: boolean;
     hotkeys: Hotkey[];
 }
 export interface HotkeyState extends HotkeyConfig {
-    /** Hotkey ids currently registered with the OS (active model only). */
+    /** Hotkey ids currently registered with the OS (models on stage only). */
     registered: string[];
 }
 /** Action kinds an app automation can carry today; servers may send kinds newer than this list. */

package/dist/wire/types.js

@@ -53,6 +53,8 @@ export const APP_CAPABILITIES = [
     'motion-stop',
     /** `stage.capture`. */
     'stage-capture',
+    /** `model.getMovement` / `model.setMovement` and the `model.movement` event. */
+    'model-movement',
 ];
 export function isAppCapability(v) {
     return isOneOf(v, APP_CAPABILITIES);

package/package.json

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