@laplace.live/persona-sdk 1.23.1 → 1.25.0

package/dist/wire/envelope.js

@@ -1,7 +1,7 @@
 import { isRecord } from "../values/guards.js";
 import { isApiErrorCode } from "./errors.js";
 import { isEventName } from "./events.js";
-import { isAppCapability } from "./types.js";
+import { canonicalAppCapability, isAppCapability } from "./types.js";
 /**
  * Parse one inbound client frame. Returns the request, or an error code telling
  * the server what to answer: `parse-error` for junk bytes, `invalid-request`
@@ -47,8 +47,11 @@ export function parseServerMessage(raw) {
             const { name, version, platform } = v.app;
             if (typeof name !== 'string' || typeof version !== 'string' || typeof platform !== 'string')
                 return null;
-            // Tolerant both ways: absent on older servers, unknown names from newer ones dropped.
-            const capabilities = Array.isArray(v.app.capabilities) ? v.app.capabilities.filter(isAppCapability) : [];
+            // Tolerant both ways: absent on older servers, unknown names from newer ones dropped. Old names fold
+            // into their replacements, which a newer server also lists.
+            const names = Array.isArray(v.app.capabilities) ? v.app.capabilities : [];
+            const folded = names.map(n => (typeof n === 'string' ? canonicalAppCapability(n) : n));
+            const capabilities = [...new Set(folded.filter(isAppCapability))];
             return { kind: 'hello', protocol: v.protocol, app: { name, version, platform, capabilities } };
         }
         case 'response':

package/dist/wire/methods.d.ts

@@ -4,8 +4,9 @@ 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 { AppInfo } from './envelope.ts';
 import type { EventName } from './events.ts';
-import type { AnchorOption, AppCapability, AssetKind, AssetRef, Attach, AttachHeadAngle, AutomationInfo, BindingInput, Expression, ExpressionPersistence, FontFamilyInfo, 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';
+import type { AnchorOption, AssetKind, AssetRef, Attach, AttachHeadAngle, AutomationInfo, BindingInput, ChannelBindings, Expression, ExpressionPersistence, FontFamilyInfo, 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, SceneModelItem, ScenePatch, SceneState, ScreenPlacement, Settings, SettingsPatch, TrackingLostBehavior, TrackingSourceConfig, TrackingSourceId, TrackingSourceKind, TrackingStatus, VrmPlacement } from './types.ts';
 /** Marker for methods that take no parameters; the client lets you omit the argument. */
 export type EmptyRequest = Record<never, never>;
 /** Marker for methods whose success response carries no data. */
@@ -85,7 +86,10 @@ export interface InstanceSetVisibleRequest {
     visible: boolean;
 }
 export type InstanceSetVisibleResponse = EmptyResponse;
-/** Edits one model or object's source effects; gate on the `layer-effects` app capability. */
+/**
+ * Edits one model or object's source effects; gate on the `layer-effects` app capability, and a `2d`
+ * object on `layer-effects-2d`.
+ */
 export interface InstanceSetEffectsRequest {
     instanceId: string;
     effects: LayerEffectsPatch;
@@ -96,13 +100,12 @@ export interface InstanceSetEffectsResponse {
     effects: LayerEffects;
     effectLayers: LayerEffectKey[];
 }
-/** Omitted fields keep their binding; null stops tracking that channel for this instance. */
-export interface InstanceSetTrackingSourcesRequest {
+/**
+ * The channels' source bindings (`ChannelBindings`). Omitted fields keep their binding;
+ * null stops tracking that channel for this instance.
+ */
+export interface InstanceSetTrackingSourcesRequest extends Partial<ChannelBindings>, Partial<Pick<SceneModelItem, 'handTrackingMode'>> {
     instanceId: string;
-    faceSourceId?: string | null;
-    poseSourceId?: string | null;
-    handSourceId?: string | null;
-    handTrackingMode?: HandTrackingMode;
 }
 export type InstanceSetTrackingSourcesResponse = EmptyResponse;
 export interface InstanceSetControllerMovementRequest {
@@ -173,7 +176,7 @@ export interface InstanceSetIdleRequest {
     idleClip?: string;
     /** Live2D only: a motion file from `motion.list`, or null for the model's `Idle` group. */
     idleMotion?: string | null;
-    /** The `tracking-lost` app capability carries these three. */
+    /** The `idle-tracking-lost` app capability carries these three. */
     trackingLostBehavior?: TrackingLostBehavior;
     /** Live2D only: a motion file from `motion.list`, or null for none. */
     trackingLostMotion?: string | null;
@@ -215,7 +218,7 @@ export interface ObjectSetContentRequest {
     content: ObjectContent;
 }
 export type ObjectSetContentResponse = EmptyResponse;
-/** A `text` object's text alone, under `text-objects`. */
+/** A `text` object's text alone, under `object-text`. */
 export interface ObjectSetTextRequest {
     instanceId: string;
     /** Null drops a transient text, showing the saved one again. */
@@ -526,13 +529,9 @@ export interface StageCaptureResponse {
     height: number;
 }
 export type AppInfoRequest = EmptyRequest;
-export interface AppInfoResponse {
-    name: string;
-    version: string;
-    platform: string;
+/** What `hello` carries, the app identity plus its protocol version. */
+export interface AppInfoResponse extends AppInfo {
     protocol: number;
-    /** Same list `hello` carries; gate features on it, never on `version`. */
-    capabilities: AppCapability[];
 }
 export type AppLocalAddressesRequest = EmptyRequest;
 export interface AppLocalAddressesResponse {
@@ -662,7 +661,7 @@ export interface ModelSetMovementRequest {
 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. */
+    /** False when any part missed its file — a refused write (read-only, unreadable) — or no field was usable. */
     saved: boolean;
 }
 export interface InstanceSetBreathRequest {

package/dist/wire/protocol.d.ts

@@ -7,6 +7,8 @@ export declare const DEFAULT_API_PORT = 25034;
 export declare const DEFAULT_API_HOST = "127.0.0.1";
 /** Scene activation waits for asset preparation before committing the new scene. */
 export declare const SCENE_ACTIVATION_TIMEOUT_MS = 120000;
+/** How long a caller waits for `method`'s answer: scene activation prepares assets first, the rest get `fallbackMs`. */
+export declare function requestTimeoutMs(method: string, fallbackMs: number): number;
 /** Server close code: the session's API key was revoked. Terminal — the client must not redial. */
 export declare const CLOSE_KEY_REVOKED = 4001;
 /** Server close code: the user disconnected this session from Persona's settings. Terminal — the client must not redial. */

package/dist/wire/protocol.js

@@ -6,6 +6,10 @@ export const DEFAULT_API_PORT = 25034;
 export const DEFAULT_API_HOST = '127.0.0.1';
 /** Scene activation waits for asset preparation before committing the new scene. */
 export const SCENE_ACTIVATION_TIMEOUT_MS = 120_000;
+/** How long a caller waits for `method`'s answer: scene activation prepares assets first, the rest get `fallbackMs`. */
+export function requestTimeoutMs(method, fallbackMs) {
+    return method === 'scene.activate' ? SCENE_ACTIVATION_TIMEOUT_MS : fallbackMs;
+}
 /** Server close code: the session's API key was revoked. Terminal — the client must not redial. */
 export const CLOSE_KEY_REVOKED = 4001;
 /** Server close code: the user disconnected this session from Persona's settings. Terminal — the client must not redial. */

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

@@ -0,0 +1,8 @@
+import type * as z from 'zod';
+/**
+ * A `z.object` shape naming every key of `T`, optional ones included. `satisfies` it so a field added
+ * to `T` fails to compile until the schema takes it — `z.object` strips the keys it does not name.
+ */
+export type Fields<T> = {
+    [K in keyof T]-?: z.ZodType;
+};

package/dist/wire/schemas/fields.js

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

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

@@ -170,12 +170,12 @@ export declare const requestSchemas: {
     }, z.core.$strip>;
     'tracking.addSource': z.ZodObject<{
         kind: z.ZodEnum<{
+            mediapipe: "mediapipe";
             "persona-ios": "persona-ios";
             ifacialmocap: "ifacialmocap";
             "vts-ios": "vts-ios";
             vmc: "vmc";
             mocopi: "mocopi";
-            mediapipe: "mediapipe";
         }>;
         name: z.ZodOptional<z.ZodString>;
         phoneIp: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -221,7 +221,7 @@ export declare const requestSchemas: {
     }, 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">>>;
+        movement: z.ZodCustom<Partial<Pick<import("../../index.ts").ModelMovementConfig, "enabled" | "x" | "y" | "z" | "pivot">>, Partial<Pick<import("../../index.ts").ModelMovementConfig, "enabled" | "x" | "y" | "z" | "pivot">>>;
     }, z.core.$strip>;
     'asset.register': z.ZodObject<{
         path: z.ZodString;

package/dist/wire/schemas/requests.js

@@ -2,7 +2,7 @@ import * as z from 'zod';
 import { CONTROLLER_DEAD_ZONE_MAX } from "../../values/controller.js";
 import { isRecord } from "../../values/guards.js";
 import { ITEM_TRANSITION_STYLES, LEGACY_DITHER_STYLE } from "../../values/item-transition.js";
-import { OBJECT_ADD_MANY_MAX, SCENE_COLOR_RE, SPEECH_URL_MAX_LENGTH, STAGE_CAPTURE_EDGE_MAX, STAGE_CAPTURE_EDGE_MIN, STORAGE_KEY_MAX_LENGTH, STORAGE_VALUE_MAX_LENGTH, } from "../../values/limits.js";
+import { OBJECT_ADD_MANY_MAX, SCENE_COLOR_RE, SESSION_NAME_MAX_LENGTH, SPEECH_URL_MAX_LENGTH, STAGE_CAPTURE_EDGE_MAX, STAGE_CAPTURE_EDGE_MIN, STORAGE_KEY_MAX_LENGTH, STORAGE_VALUE_MAX_LENGTH, } from "../../values/limits.js";
 import { LIP_SYNC_CALIBRATION_ACTIONS, LIP_SYNC_MODES, LIP_SYNC_PHONEMES, } from "../../values/lipsync.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, INJECT_TARGET_TYPES, POSE_SOURCE_IDS, TRACKING_SOURCE_IDS, TRACKING_SOURCE_KINDS, } from "../types.js";
@@ -68,20 +68,35 @@ const objectAdd = z.object({
     place3d: z.custom(isRecord, 'place3d must be an object').optional(),
 });
 const stageVector = z.object({ x: z.number(), y: z.number(), z: z.number() });
+// Each object schema `satisfies Fields<…>` of its request, so an optional field the interface gains
+// fails to compile here instead of being stripped before the executor sees it.
 export const requestSchemas = {
     'lipSync.state': z.object({}),
     'lipSync.configure': lipSyncPatch,
     'lipSync.restart': z.object({}),
     'lipSync.calibrate': lipSyncCalibration,
-    'instance.setLipSync': z.object({ instanceId: nonEmpty.optional(), mode: z.enum(LIP_SYNC_MODES) }),
-    'registry.thumbnail': z.object({ kind: z.enum(['model', 'asset']), id: nonEmpty }),
-    'controller.rename': z.object({ slot: z.number().int().positive(), name: z.string() }),
+    'instance.setLipSync': z.object({
+        instanceId: nonEmpty.optional(),
+        mode: z.enum(LIP_SYNC_MODES),
+    }),
+    'registry.thumbnail': z.object({
+        kind: z.enum(['model', 'asset']),
+        id: nonEmpty,
+    }),
+    'controller.rename': z.object({
+        slot: z.number().int().positive(),
+        name: z.string(),
+    }),
     'controller.setDeadZone': z.object({
         slot: z.number().int().positive(),
         deadZone: z.number().min(0).max(CONTROLLER_DEAD_ZONE_MAX),
     }),
-    'controller.remove': z.object({ slot: z.number().int().positive() }),
-    'controller.assign': z.object({ slot: z.number().int().positive().nullable() }),
+    'controller.remove': z.object({
+        slot: z.number().int().positive(),
+    }),
+    'controller.assign': z.object({
+        slot: z.number().int().positive().nullable(),
+    }),
     'scene.get': z.object({ sceneId: nonEmpty.optional() }),
     'scene.activate': z.object({ sceneId: nonEmpty }),
     'scene.duplicate': z.object({ sceneId: nonEmpty }),
@@ -90,24 +105,44 @@ export const requestSchemas = {
     'scene.setLightFollowCamera': z.object({
         lightId: nonEmpty,
         followCamera: z.boolean(),
-        options: z.object({ position: z.boolean(), rotation: z.boolean(), distance: z.boolean() }).partial().optional(),
+        options: z
+            .object({
+            position: z.boolean(),
+            rotation: z.boolean(),
+            distance: z.boolean(),
+        })
+            .partial()
+            .optional(),
     }),
     'instance.add': z.object({ modelId: nonEmpty }),
-    'instance.setModel': z.object({ instanceId: nonEmpty, modelId: nonEmpty }),
+    'instance.setModel': z.object({
+        instanceId: nonEmpty,
+        modelId: nonEmpty,
+    }),
     'object.add': objectAdd,
-    'object.addMany': z.object({ objects: z.array(objectAdd).min(1).max(OBJECT_ADD_MANY_MAX) }),
+    'object.addMany': z.object({
+        objects: z.array(objectAdd).min(1).max(OBJECT_ADD_MANY_MAX),
+    }),
     'object.setContent': z.object({
         instanceId: nonEmpty,
         content: z.custom(isRecord, 'content must be an object'),
     }),
-    'expression.getPersistence': z.object({ modelId: nonEmpty.optional() }),
-    'expression.setPersistence': z.object({ modelId: nonEmpty.optional(), enabled: z.boolean() }),
+    'expression.getPersistence': z.object({
+        modelId: nonEmpty.optional(),
+    }),
+    'expression.setPersistence': z.object({
+        modelId: nonEmpty.optional(),
+        enabled: z.boolean(),
+    }),
     'hotkey.list': z.object({ modelId: nonEmpty.optional() }),
     'hotkey.set': z.object({
         modelId: nonEmpty.optional(),
         config: z.custom(isRecord, 'config must be a hotkey config'),
     }),
-    'hotkey.trigger': z.object({ hotkeyId: nonEmpty, modelId: nonEmpty.optional() }),
+    '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,7 +163,9 @@ export const requestSchemas = {
     }),
     'tracking.removeSource': z.object({ id: nonEmpty }),
     'model.register': z.object({ path: nonEmpty }),
-    'model.getMovement': z.object({ modelId: nonEmpty.optional() }),
+    '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(),
@@ -136,15 +173,20 @@ export const requestSchemas = {
     }),
     // 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() }),
+    'asset.register': z.object({
+        path: nonEmpty,
+        want: z.enum(ASSET_KINDS).optional(),
+    }),
     'settings.patch': z.object({ settings: SettingsPatchSchema }),
     'tracking.setEnabled': z.object({ enabled: z.boolean() }),
-    'tracking.setSource': z.object({ source: z.enum(TRACKING_SOURCE_IDS) }),
+    'tracking.setSource': z.object({
+        source: z.enum(TRACKING_SOURCE_IDS),
+    }),
     'pose.setEnabled': z.object({ enabled: z.boolean() }),
     'pose.setSource': z.object({ source: z.enum(POSE_SOURCE_IDS) }),
     'pose.setPort': z.object({ port: PortSchema }),
     'session.identify': z.object({
-        name: z.string().trim().min(1).max(64),
+        name: z.string().trim().min(1).max(SESSION_NAME_MAX_LENGTH),
         version: z.string().max(32).optional(),
         developer: z.string().max(64).optional(),
     }),
@@ -181,10 +223,18 @@ export const requestSchemas = {
     'stage.capture': z.object({
         maxEdge: z.number().int().min(STAGE_CAPTURE_EDGE_MIN).max(STAGE_CAPTURE_EDGE_MAX).optional(),
     }),
-    'events.subscribe': z.object({ events: z.array(lenientEventNameSchema).min(1) }),
-    'events.unsubscribe': z.object({ events: z.array(lenientEventNameSchema).optional() }),
-    'param.inject': z.object({ entries: z.array(InjectEntrySchema).min(1) }),
-    'param.release': z.object({ targets: z.array(InjectTargetSchema).optional() }),
+    'events.subscribe': z.object({
+        events: z.array(lenientEventNameSchema).min(1),
+    }),
+    'events.unsubscribe': z.object({
+        events: z.array(lenientEventNameSchema).optional(),
+    }),
+    'param.inject': z.object({
+        entries: z.array(InjectEntrySchema).min(1),
+    }),
+    'param.release': z.object({
+        targets: z.array(InjectTargetSchema).optional(),
+    }),
 };
 /**
  * Validate one request's params against its method schema. Methods without a

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

@@ -56,12 +56,12 @@ export declare const MediaPipeConfigSchema: z.ZodObject<{
 export declare const TrackingSourceConfigSchema: z.ZodObject<{
     id: z.ZodString;
     kind: z.ZodEnum<{
+        mediapipe: "mediapipe";
         "persona-ios": "persona-ios";
         ifacialmocap: "ifacialmocap";
         "vts-ios": "vts-ios";
         vmc: "vmc";
         mocopi: "mocopi";
-        mediapipe: "mediapipe";
     }>;
     name: z.ZodString;
     enabled: z.ZodBoolean;
@@ -123,12 +123,12 @@ export declare const TrackingSettingsSchema: z.ZodObject<{
     sources: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         kind: z.ZodEnum<{
+            mediapipe: "mediapipe";
             "persona-ios": "persona-ios";
             ifacialmocap: "ifacialmocap";
             "vts-ios": "vts-ios";
             vmc: "vmc";
             mocopi: "mocopi";
-            mediapipe: "mediapipe";
         }>;
         name: z.ZodString;
         enabled: z.ZodBoolean;
@@ -209,12 +209,12 @@ export declare const SettingsSchema: z.ZodObject<{
         sources: z.ZodArray<z.ZodObject<{
             id: z.ZodString;
             kind: z.ZodEnum<{
+                mediapipe: "mediapipe";
                 "persona-ios": "persona-ios";
                 ifacialmocap: "ifacialmocap";
                 "vts-ios": "vts-ios";
                 vmc: "vmc";
                 mocopi: "mocopi";
-                mediapipe: "mediapipe";
             }>;
             name: z.ZodString;
             enabled: z.ZodBoolean;

package/dist/wire/schemas/settings.js

@@ -1,16 +1,16 @@
 import * as z from 'zod';
 import { CONTROLLER_DEAD_ZONE_MAX } from "../../values/controller.js";
 import { LIP_SYNC_GAIN_MAX, LIP_SYNC_MAX_SAMPLES, LIP_SYNC_MFCC_COEFFICIENTS, LIP_SYNC_MIN_SAMPLES, LIP_SYNC_NOISE_GATE_MIN, LIP_SYNC_PHONEMES, LIP_SYNC_SMOOTHING_MAX, } from "../../values/lipsync.js";
-import { LOCALES } from "../../values/locale.js";
+import { LANGUAGE_SETTINGS, THEME_SETTINGS } from "../../values/locale.js";
 import { EFFECTS_QUALITY_LEVELS, MEDIAPIPE_DELEGATES, POSE_SOURCE_IDS, TRACKING_SOURCE_IDS, TRACKING_SOURCE_KINDS, } from "../types.js";
 /** Shared field definitions; parsing validates values without adding defaults or healing them. */
 export const PortSchema = z.number().int().min(1).max(65535).describe('Network port, from 1 through 65535.');
 export const EffectsQualitySchema = z.enum(EFFECTS_QUALITY_LEVELS).describe('Scene and layer effects quality tier.');
 export const LanguageSettingSchema = z
-    .enum(['system', ...LOCALES])
+    .enum(LANGUAGE_SETTINGS)
     .describe('Interface language, or system to follow the operating system.');
 export const ThemeSettingSchema = z
-    .enum(['system', 'light', 'dark'])
+    .enum(THEME_SETTINGS)
     .describe('Interface appearance, or system to follow the operating system.');
 /** Microphone configuration shared by desktop persistence and the plugin API. */
 export const LipSyncConfigSchema = z.object({