@laplace.live/persona-sdk 1.4.0 → 1.6.0

package/dist/wire/types.d.ts

@@ -1,5 +1,6 @@
 import type { ControllerConfig } from '../values/controller.ts';
-import type { EFFECT_SCOPES } from '../values/effect-schema.ts';
+import type { EFFECT_BLEND_MODES, EFFECT_SCOPES } from '../values/effect-schema.ts';
+import type { SCENE_TRANSITION_TYPES } from '../values/scene-transition.ts';
 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';
@@ -175,7 +176,8 @@ export interface SceneModelItem {
     /** MToon material fine-tuning, VRM only. */
     mtoon: MToonTuning;
 }
-export type ObjectSpace = '2d' | '3d';
+export declare const OBJECT_SPACES: readonly ["2d", "3d"];
+export type ObjectSpace = (typeof OBJECT_SPACES)[number];
 /** Where a webpage overlay renders relative to the stage. */
 export type WebLayer = 'behind' | 'front';
 export type CaptureKind = 'display' | 'window';
@@ -333,6 +335,8 @@ export type ShadowQuality = (typeof SHADOW_QUALITY_LEVELS)[number];
 export interface SceneLight {
     id: string;
     type: SceneLightType;
+    /** Mutes illumination and shadows. Defaults to true; omitted by hosts without light toggles. */
+    enabled?: boolean;
     color: string;
     intensity: number;
     azimuth: number;
@@ -608,7 +612,7 @@ export interface SceneDroplets {
     glints: number;
 }
 /** Blend modes shared by Shoost's rim light and gradient. */
-export type EffectBlendMode = 'normal' | 'darken' | 'multiply' | 'colorBurn' | 'linearBurn' | 'add' | 'lighten' | 'screen' | 'colorDodge' | 'overlay' | 'softLight' | 'hardLight' | 'vividLight' | 'linearLight' | 'pinLight' | 'hardMix' | 'difference' | 'exclusion' | 'subtract' | 'divide' | 'hue' | 'saturation' | 'color' | 'luminosity';
+export type EffectBlendMode = (typeof EFFECT_BLEND_MODES)[number];
 /** Solid, linear, or radial color overlay in scene or source coordinates. */
 export interface EffectGradient {
     enabled: boolean;
@@ -840,6 +844,23 @@ export interface SceneEnvironment {
      */
     effectLayers: ToggleEffectKey[];
 }
+/** An effect played when this destination scene becomes active. */
+export interface SceneTransition {
+    type: (typeof SCENE_TRANSITION_TYPES)[number];
+    /** Total animation time in milliseconds, 100–10,000; cuts are immediate. */
+    durationMs: number;
+    color: string;
+    /** A registered image/video id; filesystem paths never cross the wire. */
+    assetId: string | null;
+    /** Fraction of the animation where the scene changes, 0.05–0.95. */
+    switchPoint: number;
+    /** Fade a video's opacity at its start and end; false preserves the clip's authored alpha. */
+    autoFade: boolean;
+    /** Video fade-in playback time in milliseconds, 0–10,000, capped at the switch point; requires autoFade. */
+    fadeInMs: number;
+    /** Video fade-out playback time in milliseconds, 0–10,000, capped after the switch point; requires autoFade. */
+    fadeOutMs: number;
+}
 export interface Scene {
     id: string;
     name: string;
@@ -852,14 +873,12 @@ export interface Scene {
     /** Array order is display order only; live lights are keyed by id. */
     lights: SceneLight[];
     environment: SceneEnvironment;
-    /** Electron accelerator that applies this scene, or null. */
-    shortcut: string | null;
+    /** Absent on older hosts; gate editing on the `scene-transitions` capability. */
+    transition?: SceneTransition;
 }
 export interface SceneState {
     scenes: Scene[];
     activeSceneId: string;
-    /** Scene ids whose shortcut is currently registered with the OS. */
-    registeredSceneIds: string[];
 }
 /**
  * Editable sections of the active scene. Items are deliberately absent — they
@@ -871,12 +890,13 @@ export interface ScenePatch {
     vrmCamera?: SceneCamera;
     lights?: SceneLight[];
     environment?: SceneEnvironment;
+    transition?: SceneTransition;
 }
 /**
  * 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", "shortcuts", "controllers", "model-editing", "asset-inspection", "layer-effects"];
+export declare const APP_CAPABILITIES: readonly ["storage", "speech", "automations", "controllers", "model-editing", "asset-inspection", "layer-effects", "scene-transitions"];
 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`. */
@@ -948,23 +968,32 @@ export interface HotkeyState extends HotkeyConfig {
     /** Hotkey ids currently registered with the OS (active model only). */
     registered: string[];
 }
-/** Action kinds an app shortcut can carry today; servers may send kinds newer than this list. */
-export declare const SHORTCUT_ACTION_KINDS: readonly ["effect-toggle", "effect-params", "camera-pose", "reset-camera", "layer-visibility", "stream-mode"];
-export type ShortcutActionKind = (typeof SHORTCUT_ACTION_KINDS)[number];
+/** Action kinds an app automation can carry today; servers may send kinds newer than this list. */
+export declare const AUTOMATION_ACTION_KINDS: readonly ["effect-toggle", "effect-params", "camera-pose", "reset-camera", "layer-visibility", "stream-mode", "switch-scene", "delay"];
+export type AutomationActionKind = (typeof AUTOMATION_ACTION_KINDS)[number];
+/** Kinds that end an action batch: the actions after one wait until it finishes. */
+export declare const AUTOMATION_BOUNDARY_KINDS: readonly ["switch-scene", "delay"];
+export type AutomationBoundaryKind = (typeof AUTOMATION_BOUNDARY_KINDS)[number];
 /**
- * One app-level global shortcut (a multi-action macro) as clients see it. Action
- * payloads stay app-side — `actionKinds` is what drives derived labels.
+ * One app automation as clients see it. Action kinds and scene targets drive derived
+ * labels; other action payloads stay app-side.
  */
-export interface ShortcutInfo {
+export interface AutomationInfo {
     id: string;
-    /** User-given name, or null — derive a label from `actionKinds` (see `shortcutLabel`). */
+    /** User-given name, or null — derive a label from `actionKinds` (see `automationLabel`). */
     title: string | null;
-    /** Bound key combo, or null for a trigger-only shortcut (`shortcut.trigger` still fires it). */
+    /** Bound key combo, or null when the automation has no keyboard/controller trigger. */
     accelerator: string | null;
     /** May include kinds newer than this SDK; label those generically. */
     actionKinds: string[];
+    /** Scene targets aligned with `actionKinds`; null for other actions. Older hosts omit this field. */
+    actionSceneIds?: (string | null)[];
     /** Whether the combo is currently registered with the OS. */
     registered: boolean;
+    /** Whether this automation can run. */
+    enabled: boolean;
+    /** Additional event trigger kinds. Trigger settings stay desktop-side. */
+    triggerKinds: string[];
 }
 export interface ExpressionPersistence {
     supported: boolean;
@@ -975,6 +1004,8 @@ export interface ExpressionPersistence {
 export type JsonValue = string | number | boolean | null | JsonValue[] | {
     [key: string]: JsonValue;
 };
+export declare const LIVE2D_ENGINES: readonly ["pixi", "three"];
+export type Live2DEngine = (typeof LIVE2D_ENGINES)[number];
 export declare const TRACKING_SOURCE_IDS: readonly ["persona-ios", "ifacialmocap", "vts-ios"];
 export type TrackingSourceId = (typeof TRACKING_SOURCE_IDS)[number];
 /** Body-pose protocols. Every one so far is UDP with a configurable port. */
@@ -985,17 +1016,18 @@ export type PoseStatus = 'off' | 'waiting' | 'tracking';
 /** Every protocol a tracking source instance can speak; face and body kinds. */
 export declare const TRACKING_SOURCE_KINDS: readonly ["persona-ios", "ifacialmocap", "vts-ios", "vmc", "mocopi", "mediapipe"];
 export type TrackingSourceKind = (typeof TRACKING_SOURCE_KINDS)[number];
-export declare const TRACKING_CHANNELS: readonly ["face", "pose", "hands"];
-export type TrackingChannel = (typeof TRACKING_CHANNELS)[number];
+export type TrackingChannel = keyof typeof TRACKING_CHANNEL_FIELDS;
 /** The scene-item binding each channel reads and writes. */
 export declare const TRACKING_CHANNEL_FIELDS: {
     readonly face: "faceSourceId";
     readonly pose: "poseSourceId";
     readonly hands: "handSourceId";
 };
+export declare const TRACKING_CHANNELS: readonly TrackingChannel[];
 export declare const HAND_TRACKING_MODES: readonly ["arms", "fingers"];
 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"];
 /** The shared webcam source's enabled inference tasks and camera configuration. */
 export interface MediaPipeConfig {
     deviceId: string;
@@ -1003,7 +1035,7 @@ export interface MediaPipeConfig {
     face: boolean;
     hands: boolean;
     body: boolean;
-    delegate: 'CPU' | 'GPU';
+    delegate: (typeof MEDIAPIPE_DELEGATES)[number];
 }
 export declare const DEFAULT_MEDIAPIPE_CONFIG: Readonly<MediaPipeConfig>;
 /** Whether a source kind uses a network face receiver. */
@@ -1084,11 +1116,10 @@ export interface Settings {
     performance: {
         showFps: boolean;
         fpsLimit: number;
-        selectionOutline: boolean;
         effectsQuality: EffectsQuality;
         /** Absent on older hosts. */
         renderScale?: number;
-        live2dEngine?: 'pixi' | 'three';
+        live2dEngine?: Live2DEngine;
     };
     /** `enabled` gates network face sources; `source` mirrors the first one's kind for old clients. */
     tracking: {
@@ -1115,15 +1146,45 @@ export interface SettingsPatch {
     performance?: {
         showFps?: boolean;
         fpsLimit?: number;
-        selectionOutline?: boolean;
         effectsQuality?: EffectsQuality;
         renderScale?: number;
-        live2dEngine?: 'pixi' | 'three';
+        live2dEngine?: Live2DEngine;
     };
 }
-/** VTS's input vocabulary, plus `JawOpen` — the derived half of {@link INPUT_NAMES}. */
-declare const VTS_INPUT_NAMES: readonly ["FaceAngleX", "FaceAngleY", "FaceAngleZ", "FacePositionX", "FacePositionY", "FacePositionZ", "EyeOpenLeft", "EyeOpenRight", "EyeLeftX", "EyeLeftY", "EyeRightX", "EyeRightY", "Brows", "BrowLeftY", "BrowRightY", "MouthSmile", "MouthOpen", "MouthX", "CheekPuff", "JawOpen", "TongueOut"];
-type VtsInputName = (typeof VTS_INPUT_NAMES)[number];
+/**
+ * From VTS's own registry (`FaceTrackingParamInfo.paramNameDictionary`), which is both the
+ * range its editor seeds a new parameter with and what every `.vtube.json` was authored
+ * against. Two families differ deliberately:
+ *
+ * - **the brow inputs** are signed here. VTS lists them `0..1`; we derive them as
+ *   `brow-up − brow-down`, so a frown needs the lower half.
+ * - **`JawOpen`** is absent from VTS's registry — it exists there only as a plugin-created
+ *   parameter, which VTS then special-cases — so its span is the ARKit channel's.
+ */
+declare const VTS_INPUT_RANGES: {
+    readonly FaceAngleX: readonly [-30, 30];
+    readonly FaceAngleY: readonly [-30, 30];
+    readonly FaceAngleZ: readonly [-90, 90];
+    readonly FacePositionX: readonly [-15, 15];
+    readonly FacePositionY: readonly [-15, 15];
+    readonly FacePositionZ: readonly [-10, 10];
+    readonly EyeOpenLeft: readonly [0, 1];
+    readonly EyeOpenRight: readonly [0, 1];
+    readonly EyeLeftX: readonly [-1, 1];
+    readonly EyeLeftY: readonly [-1, 1];
+    readonly EyeRightX: readonly [-1, 1];
+    readonly EyeRightY: readonly [-1, 1];
+    readonly Brows: readonly [-1, 1];
+    readonly BrowLeftY: readonly [-1, 1];
+    readonly BrowRightY: readonly [-1, 1];
+    readonly MouthSmile: readonly [0, 1];
+    readonly MouthOpen: readonly [0, 1];
+    readonly MouthX: readonly [-1, 1];
+    readonly CheekPuff: readonly [0, 1];
+    readonly JawOpen: readonly [0, 1];
+    readonly TongueOut: readonly [0, 1];
+};
+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.
@@ -1168,7 +1229,8 @@ export declare function getInputRange(name: InputName): readonly [number, number
  * - `vrm-expression` — reserved, not implemented yet; the server answers
  *   `unsupported-for-format`.
  */
-export type InjectTargetType = 'input' | 'live2d-param' | 'vrm-expression';
+export declare const INJECT_TARGET_TYPES: readonly ["input", "live2d-param", "vrm-expression"];
+export type InjectTargetType = (typeof INJECT_TARGET_TYPES)[number];
 export interface InjectTarget {
     type: InjectTargetType;
     id: string;

package/dist/wire/types.js

@@ -3,6 +3,7 @@
 // filesystem-shaped — model refs are sanitized to ids, never directories.
 import { ARKIT_INPUT_NAMES } from "../values/arkit.js";
 import { BASE_CONTROLLER_INPUT_NAMES, BASE_CONTROLLER_INPUT_RANGES, controllerInputRange, isControllerInputName, } from "../values/controller.js";
+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";
 /**
@@ -13,8 +14,10 @@ import { VOICE_INPUT_NAMES, VOICE_INPUT_RANGES, } from "../values/lipsync.js";
 export const ASSET_KINDS = ['image', 'video', 'prop', 'ibl', 'lut', 'animation', 'cameraMotion'];
 /** Narrow a kind string to the set the asset registry owns — models and effects have their own. */
 export function isAssetKind(v) {
-    return typeof v === 'string' && ASSET_KINDS.includes(v);
+    return isOneOf(v, ASSET_KINDS);
 }
+// ---- Objects -------------------------------------------------------------------
+export const OBJECT_SPACES = ['2d', '3d'];
 /**
  * Per-light shadow tier. `off` is the old `castShadow: false`; the rest raise
  * shadow-map resolution. A point light pays 6 cube faces for the same tier a
@@ -29,42 +32,49 @@ export const SHADOW_QUALITY_LEVELS = ['off', 'low', 'medium', 'high', 'ultra'];
 export const APP_CAPABILITIES = [
     'storage',
     'speech',
-    'shortcuts',
+    'automations',
     'controllers',
     'model-editing',
     'asset-inspection',
     'layer-effects',
+    'scene-transitions',
 ];
 export function isAppCapability(v) {
-    return typeof v === 'string' && APP_CAPABILITIES.includes(v);
+    return isOneOf(v, APP_CAPABILITIES);
 }
-// ---- App shortcuts --------------------------------------------------------------
-/** Action kinds an app shortcut can carry today; servers may send kinds newer than this list. */
-export const SHORTCUT_ACTION_KINDS = [
+// ---- App automations --------------------------------------------------------------
+/** Action kinds an app automation can carry today; servers may send kinds newer than this list. */
+export const AUTOMATION_ACTION_KINDS = [
     'effect-toggle',
     'effect-params',
     'camera-pose',
     'reset-camera',
     'layer-visibility',
     'stream-mode',
+    'switch-scene',
+    'delay',
 ];
+/** Kinds that end an action batch: the actions after one wait until it finishes. */
+export const AUTOMATION_BOUNDARY_KINDS = ['switch-scene', 'delay'];
 // ---- Settings ------------------------------------------------------------------
+export const LIVE2D_ENGINES = ['pixi', 'three'];
 export const TRACKING_SOURCE_IDS = ['persona-ios', 'ifacialmocap', 'vts-ios'];
 /** Body-pose protocols. Every one so far is UDP with a configurable port. */
 export const POSE_SOURCE_IDS = ['vmc', 'mocopi'];
 /** Every protocol a tracking source instance can speak; face and body kinds. */
 export const TRACKING_SOURCE_KINDS = [...TRACKING_SOURCE_IDS, ...POSE_SOURCE_IDS, 'mediapipe'];
-export const TRACKING_CHANNELS = ['face', 'pose', 'hands'];
 /** The scene-item binding each channel reads and writes. */
 export const TRACKING_CHANNEL_FIELDS = {
     face: 'faceSourceId',
     pose: 'poseSourceId',
     hands: 'handSourceId',
 };
+export const TRACKING_CHANNELS = keysOf(TRACKING_CHANNEL_FIELDS);
 export const HAND_TRACKING_MODES = ['arms', 'fingers'];
 export function isHandTrackingMode(v) {
-    return HAND_TRACKING_MODES.includes(v);
+    return isOneOf(v, HAND_TRACKING_MODES);
 }
+export const MEDIAPIPE_DELEGATES = ['CPU', 'GPU'];
 export const DEFAULT_MEDIAPIPE_CONFIG = {
     deviceId: '',
     mirror: true,
@@ -75,11 +85,11 @@ export const DEFAULT_MEDIAPIPE_CONFIG = {
 };
 /** Whether a source kind uses a network face receiver. */
 export function isFaceSourceKind(kind) {
-    return TRACKING_SOURCE_IDS.includes(kind);
+    return isOneOf(kind, TRACKING_SOURCE_IDS);
 }
 /** Whether a source uses a network body receiver. */
 export function isPoseSource(source) {
-    return POSE_SOURCE_IDS.includes(source.kind);
+    return isOneOf(source.kind, POSE_SOURCE_IDS);
 }
 const FACE_ONLY = ['face'];
 const POSE_ONLY = ['pose'];
@@ -119,30 +129,41 @@ export const EFFECTS_QUALITY_LEVELS = ['low', 'medium', 'high'];
  */
 export const FPS_LIMIT_PRESETS = [0, 15, 30, 60, 90];
 // ---- Injection -----------------------------------------------------------------
+/**
+ * From VTS's own registry (`FaceTrackingParamInfo.paramNameDictionary`), which is both the
+ * range its editor seeds a new parameter with and what every `.vtube.json` was authored
+ * against. Two families differ deliberately:
+ *
+ * - **the brow inputs** are signed here. VTS lists them `0..1`; we derive them as
+ *   `brow-up − brow-down`, so a frown needs the lower half.
+ * - **`JawOpen`** is absent from VTS's registry — it exists there only as a plugin-created
+ *   parameter, which VTS then special-cases — so its span is the ARKit channel's.
+ */
+const VTS_INPUT_RANGES = {
+    FaceAngleX: [-30, 30],
+    FaceAngleY: [-30, 30],
+    FaceAngleZ: [-90, 90],
+    FacePositionX: [-15, 15],
+    FacePositionY: [-15, 15],
+    FacePositionZ: [-10, 10],
+    EyeOpenLeft: [0, 1],
+    EyeOpenRight: [0, 1],
+    EyeLeftX: [-1, 1],
+    EyeLeftY: [-1, 1],
+    EyeRightX: [-1, 1],
+    EyeRightY: [-1, 1],
+    Brows: [-1, 1],
+    BrowLeftY: [-1, 1],
+    BrowRightY: [-1, 1],
+    MouthSmile: [0, 1],
+    MouthOpen: [0, 1],
+    MouthX: [-1, 1],
+    CheekPuff: [0, 1],
+    JawOpen: [0, 1],
+    TongueOut: [0, 1],
+};
 /** VTS's input vocabulary, plus `JawOpen` — the derived half of {@link INPUT_NAMES}. */
-const VTS_INPUT_NAMES = [
-    'FaceAngleX',
-    'FaceAngleY',
-    'FaceAngleZ',
-    'FacePositionX',
-    'FacePositionY',
-    'FacePositionZ',
-    'EyeOpenLeft',
-    'EyeOpenRight',
-    'EyeLeftX',
-    'EyeLeftY',
-    'EyeRightX',
-    'EyeRightY',
-    'Brows',
-    'BrowLeftY',
-    'BrowRightY',
-    'MouthSmile',
-    'MouthOpen',
-    'MouthX',
-    'CheekPuff',
-    'JawOpen',
-    'TongueOut',
-];
+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.
@@ -180,39 +201,6 @@ export const BINDING_INPUT_NAMES = INPUT_NAMES.filter(n => !isArkitTwinAlias(n))
 export function arkitTwinOf(input) {
     return isArkitTwinAlias(input) ? ARKIT_TWINS[input] : input;
 }
-/**
- * From VTS's own registry (`FaceTrackingParamInfo.paramNameDictionary`), which is both the
- * range its editor seeds a new parameter with and what every `.vtube.json` was authored
- * against. Two families differ deliberately:
- *
- * - **the brow inputs** are signed here. VTS lists them `0..1`; we derive them as
- *   `brow-up − brow-down`, so a frown needs the lower half.
- * - **`JawOpen`** is absent from VTS's registry — it exists there only as a plugin-created
- *   parameter, which VTS then special-cases — so its span is the ARKit channel's.
- */
-const VTS_INPUT_RANGES = {
-    FaceAngleX: [-30, 30],
-    FaceAngleY: [-30, 30],
-    FaceAngleZ: [-90, 90],
-    FacePositionX: [-15, 15],
-    FacePositionY: [-15, 15],
-    FacePositionZ: [-10, 10],
-    EyeOpenLeft: [0, 1],
-    EyeOpenRight: [0, 1],
-    EyeLeftX: [-1, 1],
-    EyeLeftY: [-1, 1],
-    EyeRightX: [-1, 1],
-    EyeRightY: [-1, 1],
-    Brows: [-1, 1],
-    BrowLeftY: [-1, 1],
-    BrowRightY: [-1, 1],
-    MouthSmile: [0, 1],
-    MouthOpen: [0, 1],
-    MouthX: [-1, 1],
-    CheekPuff: [0, 1],
-    JawOpen: [0, 1],
-    TongueOut: [0, 1],
-};
 /** ARKit blendshapes are unit-scale by definition, so every raw channel shares one span. */
 const ARKIT_RANGE = [0, 1];
 /**
@@ -232,3 +220,12 @@ export const INPUT_RANGES = {
 export function getInputRange(name) {
     return isControllerInputName(name) ? controllerInputRange(name) : INPUT_RANGES[name];
 }
+/**
+ * What an injected value drives:
+ * - `input` — a VTS-vocabulary tracking input (`MouthOpen`, `FaceAngleX`, …), mapped
+ *   through the model's own tracking rules. Live2D only.
+ * - `live2d-param` — a Cubism parameter id, written directly.
+ * - `vrm-expression` — reserved, not implemented yet; the server answers
+ *   `unsupported-for-format`.
+ */
+export const INJECT_TARGET_TYPES = ['input', 'live2d-param', 'vrm-expression'];

package/package.json

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