@laplace.live/persona-sdk 1.5.0 → 1.7.0

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export * from './client/address.ts';
 export * from './client/client.ts';
 export * from './values/arkit.ts';
 export * from './values/bindings.ts';
+export * from './values/camera.ts';
 export * from './values/controller.ts';
 export * from './values/curve.ts';
 export * from './values/edit-history.ts';

package/dist/index.js

@@ -4,6 +4,7 @@ export * from "./client/address.js";
 export * from "./client/client.js";
 export * from "./values/arkit.js";
 export * from "./values/bindings.js";
+export * from "./values/camera.js";
 export * from "./values/controller.js";
 export * from "./values/curve.js";
 export * from "./values/edit-history.js";

package/dist/values/camera.d.ts

@@ -0,0 +1,13 @@
+import type { OrbitTransform } from '../wire/types.ts';
+/** Camera position for an orbit transform, in world units. Y is up, +Z toward the viewer. */
+export declare function orbitPosition(t: OrbitTransform): {
+    x: number;
+    y: number;
+    z: number;
+};
+/** Translate a camera and its look-at point to a world position, preserving its view direction and distance. */
+export declare function orbitAtPosition(orbit: OrbitTransform, position: {
+    x: number;
+    y: number;
+    z: number;
+}): OrbitTransform;

package/dist/values/camera.js

@@ -0,0 +1,19 @@
+/** Camera position for an orbit transform, in world units. Y is up, +Z toward the viewer. */
+export function orbitPosition(t) {
+    const r = Math.cos(t.elevation) * t.distance;
+    return {
+        x: t.targetX + Math.sin(t.azimuth) * r,
+        y: t.targetY + Math.sin(t.elevation) * t.distance,
+        z: t.targetZ + Math.cos(t.azimuth) * r,
+    };
+}
+/** Translate a camera and its look-at point to a world position, preserving its view direction and distance. */
+export function orbitAtPosition(orbit, position) {
+    const current = orbitPosition(orbit);
+    return {
+        ...orbit,
+        targetX: orbit.targetX + position.x - current.x,
+        targetY: orbit.targetY + position.y - current.y,
+        targetZ: orbit.targetZ + position.z - current.z,
+    };
+}

package/dist/values/labels.d.ts

@@ -1,4 +1,4 @@
-import type { AutomationInfo } from '../wire/types.ts';
+import type { AutomationBoundaryKind, AutomationInfo } from '../wire/types.ts';
 /** Last path segment, tolerating both `/` and `\` separators. */
 export declare function fileBasename(path: string): string;
 /**
@@ -9,9 +9,11 @@ export declare function fileBasename(path: string): string;
 export declare function motionLabel(file: string): string;
 /** English label for one automation action kind; kinds newer than this SDK read `Action`. */
 export declare function automationActionLabel(kind: string): string;
+/** True for an action that ends a batch and waits before continuing. */
+export declare function isAutomationBoundary(kind: string | undefined): kind is AutomationBoundaryKind;
 /**
- * Join one automation's action labels: a wait ends a batch, so it reads as an arrow, while
- * actions inside a batch read as ` + `. `kinds` must match `labels` in length and position.
+ * Join one automation's action labels: a batch boundary reads as an arrow, while actions
+ * inside a batch read as ` + `. `kinds` must match `labels` in length and position.
  */
 export declare function joinAutomationActionLabels(labels: readonly string[], kinds: readonly string[]): string;
 /** Display label for an app automation: its title, else its joined action-kind labels. */

package/dist/values/labels.js

@@ -1,3 +1,5 @@
+import { AUTOMATION_BOUNDARY_KINDS } from "../wire/types.js";
+import { isOneOf } from "./guards.js";
 /** Last path segment, tolerating both `/` and `\` separators. */
 export function fileBasename(path) {
     return path.split(/[/\\]/).at(-1) ?? path;
@@ -19,20 +21,32 @@ const AUTOMATION_ACTION_KIND_LABELS = {
     'reset-camera': 'Reset Camera',
     'layer-visibility': 'Layer Visibility',
     'stream-mode': 'Stream Mode',
+    'switch-scene': 'Switch Scene',
+    'toggle-expression': 'Toggle Expression',
+    'play-motion': 'Play Motion',
+    'remove-all-expressions': 'Clear All Expressions',
+    'load-model': 'Swap Model',
+    'model-position': 'Model Position',
     delay: 'Wait',
 };
 /** English label for one automation action kind; kinds newer than this SDK read `Action`. */
 export function automationActionLabel(kind) {
     return AUTOMATION_ACTION_KIND_LABELS[kind] ?? 'Action';
 }
+/** True for an action that ends a batch and waits before continuing. */
+export function isAutomationBoundary(kind) {
+    return isOneOf(kind, AUTOMATION_BOUNDARY_KINDS);
+}
 /**
- * Join one automation's action labels: a wait ends a batch, so it reads as an arrow, while
- * actions inside a batch read as ` + `. `kinds` must match `labels` in length and position.
+ * Join one automation's action labels: a batch boundary reads as an arrow, while actions
+ * inside a batch read as ` + `. `kinds` must match `labels` in length and position.
  */
 export function joinAutomationActionLabels(labels, kinds) {
     if (labels.length !== kinds.length)
         throw new RangeError('automation action labels and kinds must have the same length');
-    return labels.reduce((out, label, i) => out + (i === 0 ? '' : kinds[i] === 'delay' || kinds[i - 1] === 'delay' ? ' → ' : ' + ') + label, '');
+    return labels.reduce((out, label, i) => out +
+        (i === 0 ? '' : isAutomationBoundary(kinds[i]) || isAutomationBoundary(kinds[i - 1]) ? ' → ' : ' + ') +
+        label, '');
 }
 /** Display label for an app automation: its title, else its joined action-kind labels. */
 export function automationLabel(automation) {

package/dist/values/limits.js

@@ -104,6 +104,7 @@ export function defaultSceneLightOf(type) {
     return {
         id: crypto.randomUUID(),
         type,
+        enabled: true,
         color: '#ffffff',
         // Ambient is a flat albedo floor with no shading — 1.0 alone washes the model out.
         intensity: type === 'ambient' ? 0.4 : 1,

package/dist/values/scene-transition.d.ts

@@ -2,6 +2,7 @@ import type { AssetRef, SceneTransition } from '../wire/types.ts';
 export declare const SCENE_TRANSITION_TYPES: readonly ["cut", "fade", "wipe", "circle", "image", "video"];
 export declare const SCENE_TRANSITION_DURATION_MIN_MS = 100;
 export declare const SCENE_TRANSITION_DURATION_MAX_MS = 10000;
+export declare const SCENE_TRANSITION_FADE_DEFAULT_MS = 300;
 export declare const SCENE_TRANSITION_SWITCH_POINT_MIN = 0.05;
 export declare const SCENE_TRANSITION_SWITCH_POINT_MAX = 0.95;
 /** The destination scene's entrance effect; existing scenes keep an immediate cut. */

package/dist/values/scene-transition.js

@@ -3,11 +3,21 @@ import { clamp, hexColorOr } from "./limits.js";
 export const SCENE_TRANSITION_TYPES = ['cut', 'fade', 'wipe', 'circle', 'image', 'video'];
 export const SCENE_TRANSITION_DURATION_MIN_MS = 100;
 export const SCENE_TRANSITION_DURATION_MAX_MS = 10_000;
+export const SCENE_TRANSITION_FADE_DEFAULT_MS = 300;
 export const SCENE_TRANSITION_SWITCH_POINT_MIN = 0.05;
 export const SCENE_TRANSITION_SWITCH_POINT_MAX = 0.95;
 /** The destination scene's entrance effect; existing scenes keep an immediate cut. */
 export function defaultSceneTransition() {
-    return { type: 'cut', durationMs: 1000, color: '#000000', assetId: null, switchPoint: 0.5, autoFade: false };
+    return {
+        type: 'cut',
+        durationMs: 1000,
+        color: '#000000',
+        assetId: null,
+        switchPoint: 0.5,
+        autoFade: false,
+        fadeInMs: SCENE_TRANSITION_FADE_DEFAULT_MS,
+        fadeOutMs: SCENE_TRANSITION_FADE_DEFAULT_MS,
+    };
 }
 /** The media kind a transition type plays, or null for the built-in effects. */
 export function sceneTransitionMedia(type) {
@@ -32,5 +42,7 @@ export function healSceneTransition(raw) {
         assetId: nonEmptyString(raw.assetId),
         switchPoint: clamp(finiteOr(raw.switchPoint, d.switchPoint), SCENE_TRANSITION_SWITCH_POINT_MIN, SCENE_TRANSITION_SWITCH_POINT_MAX),
         autoFade: typeof raw.autoFade === 'boolean' ? raw.autoFade : d.autoFade,
+        fadeInMs: clamp(finiteOr(raw.fadeInMs, d.fadeInMs), 0, SCENE_TRANSITION_DURATION_MAX_MS),
+        fadeOutMs: clamp(finiteOr(raw.fadeOutMs, d.fadeOutMs), 0, SCENE_TRANSITION_DURATION_MAX_MS),
     };
 }

package/dist/wire/events.d.ts

@@ -1,7 +1,7 @@
 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 {
-    /** Any scene mutation: create/delete/rename/activate/shortcut and persisted scene edits. */
+    /** Any scene mutation: create/delete/rename/activate and persisted scene edits. */
     'scene.changed': SceneState;
     'settings.changed': {
         settings: Settings;

package/dist/wire/methods.d.ts

@@ -36,12 +36,6 @@ export interface SceneDeleteRequest {
     sceneId: string;
 }
 export type SceneDeleteResponse = SceneState;
-export interface SceneSetShortcutRequest {
-    sceneId: string;
-    /** Electron accelerator string, or null to clear. */
-    accelerator: string | null;
-}
-export type SceneSetShortcutResponse = SceneState;
 export type ScenePatchRequest = ScenePatch;
 export interface ScenePatchResponse {
     scene: Scene;
@@ -668,10 +662,6 @@ export interface MethodMap {
         request: SceneDeleteRequest;
         response: SceneDeleteResponse;
     };
-    'scene.setShortcut': {
-        request: SceneSetShortcutRequest;
-        response: SceneSetShortcutResponse;
-    };
     /** Live edit of the active scene's sections; applies next frame, persists debounced. */
     'scene.patch': {
         request: ScenePatchRequest;
@@ -724,7 +714,7 @@ export interface MethodMap {
         request: InstanceSetPrimaryRequest;
         response: InstanceSetPrimaryResponse;
     };
-    /** Drives the desktop's editing selection (outline + Model tab); ephemeral, never persisted. */
+    /** Drives the desktop's editing selection (handles and inspector); ephemeral, never persisted. */
     'selection.set': {
         request: SelectionSetRequest;
         response: SelectionSetResponse;

package/dist/wire/schemas.d.ts

@@ -16,6 +16,8 @@ export declare const SceneTransitionSchema: z.ZodObject<{
     assetId: z.ZodNullable<z.ZodString>;
     switchPoint: z.ZodNumber;
     autoFade: z.ZodDefault<z.ZodBoolean>;
+    fadeInMs: z.ZodDefault<z.ZodNumber>;
+    fadeOutMs: z.ZodDefault<z.ZodNumber>;
 }, z.core.$strip>;
 export declare const InjectTargetSchema: z.ZodObject<{
     type: z.ZodEnum<{
@@ -57,7 +59,6 @@ export declare const SettingsPatchSchema: z.ZodObject<{
     performance: z.ZodOptional<z.ZodObject<{
         showFps: z.ZodOptional<z.ZodBoolean>;
         fpsLimit: z.ZodOptional<z.ZodNumber>;
-        selectionOutline: z.ZodOptional<z.ZodBoolean>;
         effectsQuality: z.ZodOptional<z.ZodEnum<{
             low: "low";
             medium: "medium";
@@ -144,10 +145,6 @@ export declare const requestSchemas: {
     'scene.delete': z.ZodObject<{
         sceneId: z.ZodString;
     }, z.core.$strip>;
-    'scene.setShortcut': z.ZodObject<{
-        sceneId: z.ZodString;
-        accelerator: z.ZodNullable<z.ZodString>;
-    }, z.core.$strip>;
     'instance.add': z.ZodObject<{
         modelId: z.ZodString;
     }, z.core.$strip>;
@@ -264,7 +261,6 @@ export declare const requestSchemas: {
             performance: z.ZodOptional<z.ZodObject<{
                 showFps: z.ZodOptional<z.ZodBoolean>;
                 fpsLimit: z.ZodOptional<z.ZodNumber>;
-                selectionOutline: z.ZodOptional<z.ZodBoolean>;
                 effectsQuality: z.ZodOptional<z.ZodEnum<{
                     low: "low";
                     medium: "medium";

package/dist/wire/schemas.js

@@ -3,7 +3,7 @@ import { CONTROLLER_DEAD_ZONE_MAX } from "../values/controller.js";
 import { isRecord } from "../values/guards.js";
 import { SCENE_COLOR_RE, SPEECH_URL_MAX_LENGTH, STORAGE_KEY_MAX_LENGTH, STORAGE_VALUE_MAX_LENGTH, } from "../values/limits.js";
 import { LIP_SYNC_CALIBRATION_ACTIONS, LIP_SYNC_GAIN_MAX, LIP_SYNC_MODES, LIP_SYNC_NOISE_GATE_MIN, LIP_SYNC_PHONEMES, LIP_SYNC_SMOOTHING_MAX, } from "../values/lipsync.js";
-import { SCENE_TRANSITION_DURATION_MAX_MS, SCENE_TRANSITION_DURATION_MIN_MS, SCENE_TRANSITION_SWITCH_POINT_MAX, SCENE_TRANSITION_SWITCH_POINT_MIN, SCENE_TRANSITION_TYPES, } from "../values/scene-transition.js";
+import { SCENE_TRANSITION_DURATION_MAX_MS, SCENE_TRANSITION_DURATION_MIN_MS, SCENE_TRANSITION_FADE_DEFAULT_MS, SCENE_TRANSITION_SWITCH_POINT_MAX, SCENE_TRANSITION_SWITCH_POINT_MIN, SCENE_TRANSITION_TYPES, } from "../values/scene-transition.js";
 import { ASSET_KINDS, EFFECTS_QUALITY_LEVELS, INJECT_TARGET_TYPES, LIVE2D_ENGINES, MEDIAPIPE_DELEGATES, POSE_SOURCE_IDS, TRACKING_SOURCE_IDS, TRACKING_SOURCE_KINDS, } from "./types.js";
 // Runtime validation for the request side of the wire. Schemas exist for the
 // methods whose params the app's main process consumes directly; methods without
@@ -19,6 +19,8 @@ export const SceneTransitionSchema = z.object({
     assetId: nonEmpty.refine(v => v.trim() !== '', 'assetId must not be blank').nullable(),
     switchPoint: z.number().min(SCENE_TRANSITION_SWITCH_POINT_MIN).max(SCENE_TRANSITION_SWITCH_POINT_MAX),
     autoFade: z.boolean().default(false),
+    fadeInMs: z.number().min(0).max(SCENE_TRANSITION_DURATION_MAX_MS).default(SCENE_TRANSITION_FADE_DEFAULT_MS),
+    fadeOutMs: z.number().min(0).max(SCENE_TRANSITION_DURATION_MAX_MS).default(SCENE_TRANSITION_FADE_DEFAULT_MS),
 });
 const port = z.number().int().min(1).max(65535);
 const lipSyncCalibration = z.discriminatedUnion('action', [
@@ -58,7 +60,6 @@ export const SettingsPatchSchema = z.object({
         .object({
         showFps: z.boolean().optional(),
         fpsLimit: z.number().optional(),
-        selectionOutline: z.boolean().optional(),
         effectsQuality: z.enum(EFFECTS_QUALITY_LEVELS).optional(),
         renderScale: z.number().optional(),
         live2dEngine: z.enum(LIVE2D_ENGINES).optional(),
@@ -105,7 +106,6 @@ export const requestSchemas = {
     'scene.duplicate': z.object({ sceneId: nonEmpty }),
     'scene.rename': z.object({ sceneId: nonEmpty, name: nonEmpty }),
     'scene.delete': z.object({ sceneId: nonEmpty }),
-    'scene.setShortcut': z.object({ sceneId: nonEmpty, accelerator: nonEmpty.nullable() }),
     'instance.add': z.object({ modelId: nonEmpty }),
     'instance.setModel': z.object({ instanceId: nonEmpty, modelId: nonEmpty }),
     'object.add': z.object({

package/dist/wire/types.d.ts

@@ -335,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;
@@ -854,6 +856,10 @@ export interface SceneTransition {
     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;
@@ -869,14 +875,10 @@ export interface Scene {
     environment: SceneEnvironment;
     /** Absent on older hosts; gate editing on the `scene-transitions` capability. */
     transition?: SceneTransition;
-    /** Electron accelerator that applies this scene, or null. */
-    shortcut: string | null;
 }
 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
@@ -967,11 +969,14 @@ export interface HotkeyState extends HotkeyConfig {
     registered: string[];
 }
 /** 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", "delay"];
+export declare const AUTOMATION_ACTION_KINDS: readonly ["effect-toggle", "effect-params", "camera-pose", "reset-camera", "layer-visibility", "stream-mode", "switch-scene", "toggle-expression", "play-motion", "remove-all-expressions", "load-model", "model-position", "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", "load-model", "delay"];
+export type AutomationBoundaryKind = (typeof AUTOMATION_BOUNDARY_KINDS)[number];
 /**
- * One app automation as clients see it. Action payloads stay app-side — `actionKinds`
- * 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 AutomationInfo {
     id: string;
@@ -981,6 +986,8 @@ export interface AutomationInfo {
     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. */
@@ -1109,7 +1116,6 @@ export interface Settings {
     performance: {
         showFps: boolean;
         fpsLimit: number;
-        selectionOutline: boolean;
         effectsQuality: EffectsQuality;
         /** Absent on older hosts. */
         renderScale?: number;
@@ -1140,7 +1146,6 @@ export interface SettingsPatch {
     performance?: {
         showFps?: boolean;
         fpsLimit?: number;
-        selectionOutline?: boolean;
         effectsQuality?: EffectsQuality;
         renderScale?: number;
         live2dEngine?: Live2DEngine;

package/dist/wire/types.js

@@ -51,6 +51,18 @@ export const AUTOMATION_ACTION_KINDS = [
     'reset-camera',
     'layer-visibility',
     'stream-mode',
+    'switch-scene',
+    'toggle-expression',
+    'play-motion',
+    'remove-all-expressions',
+    'load-model',
+    'model-position',
+    'delay',
+];
+/** Kinds that end an action batch: the actions after one wait until it finishes. */
+export const AUTOMATION_BOUNDARY_KINDS = [
+    'switch-scene',
+    'load-model',
     'delay',
 ];
 // ---- Settings ------------------------------------------------------------------

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@laplace.live/persona-sdk",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "description": "TypeScript SDK and wire schema for the LAPLACE Persona plugin API",
   "license": "MIT",
   "type": "module",
@@ -34,7 +34,7 @@
     "node": ">=24"
   },
   "dependencies": {
-    "zod": "^4.5.4"
+    "zod": "^4.6.1"
   },
   "scripts": {
     "build": "rimraf dist && tsc -p tsconfig.build.json",