@laplace.live/persona-sdk 0.7.0 → 0.8.0

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

@@ -18,5 +18,13 @@ export type ToggleEffectKey = {
 }[keyof SceneEffects];
 export declare const EFFECT_SPECS: Record<ToggleEffectKey, Readonly<Record<string, EffectParamSpec>>>;
 export declare const TOGGLE_EFFECT_KEYS: readonly ToggleEffectKey[];
+/**
+ * Registry effects that render as scene geometry inside the scene pass rather
+ * than composing into the post chain. A new scene-space effect must join this
+ * list, or its toggle needlessly forces the post path on and rebuilds the graph.
+ */
+export declare const SCENE_SPACE_EFFECT_KEYS: readonly ToggleEffectKey[];
+/** Registry effects the post chain composes — {@link TOGGLE_EFFECT_KEYS} minus the scene-space ones. */
+export declare const POST_EFFECT_KEYS: readonly ToggleEffectKey[];
 /** Every registry effect at its defaults — the derived half of a fresh {@link SceneEffects}. */
 export declare function defaultToggleEffects(): Pick<SceneEffects, ToggleEffectKey>;

package/dist/values/effect-schema.js

@@ -4,6 +4,8 @@
 //   1. Type its values in `SceneEffects` (types.ts) + its interface.
 //   2. Spec it here; label it in the panel's effect-labels.ts (parity-checked).
 //   3. Implement its stage under apps/desktop/src/renderer/vrm/webgpu/effects/.
+//      Scene-space effects (geometry, not a post stage — e.g. snow) also join
+//      SCENE_SPACE_EFFECT_KEYS below.
 //   4. Drop one `<EffectSection>` line into a panel section.
 // Effects that don't fit the pattern (tone mapping, exposure, LUT, shockwave)
 // stay bespoke — extend the pattern before special-casing a third shape.
@@ -72,9 +74,28 @@ export const EFFECT_SPECS = {
         staticDrops: { default: 0.2, min: 0, max: 3, step: 0.1, digits: 1 },
         glints: { default: 0.6, min: 0, max: 1, step: 0.05 },
     },
+    // three's webgpu_compute_particles_snow, rescaled to the stage's metre-scale
+    // world. `amount` is the live instance count; buffers allocate the max once.
+    snow: {
+        amount: { default: 2000, min: 100, max: 10000, step: 100 },
+        speed: { default: 1, min: 0, max: 3, step: 0.1, digits: 1, unit: '×' },
+        wind: { default: 0, min: -3, max: 3, step: 0.1, digits: 1, unit: 'm/s' },
+        sway: { default: 1, min: 0, max: 3, step: 0.1, digits: 1 },
+        size: { default: 1, min: 0.4, max: 3, step: 0.05 },
+        melt: { default: 6, min: 0.5, max: 30, step: 0.5, digits: 1, unit: 's' },
+        opacity: { default: 1, min: 0.1, max: 1, step: 0.05 },
+    },
 };
 // Object.keys widens to string[]; the annotation above pins the keys to exactly ToggleEffectKey.
 export const TOGGLE_EFFECT_KEYS = Object.keys(EFFECT_SPECS);
+/**
+ * Registry effects that render as scene geometry inside the scene pass rather
+ * than composing into the post chain. A new scene-space effect must join this
+ * list, or its toggle needlessly forces the post path on and rebuilds the graph.
+ */
+export const SCENE_SPACE_EFFECT_KEYS = ['snow'];
+/** Registry effects the post chain composes — {@link TOGGLE_EFFECT_KEYS} minus the scene-space ones. */
+export const POST_EFFECT_KEYS = TOGGLE_EFFECT_KEYS.filter(key => !SCENE_SPACE_EFFECT_KEYS.includes(key));
 /** Every registry effect at its defaults — the derived half of a fresh {@link SceneEffects}. */
 export function defaultToggleEffects() {
     const out = {};

package/dist/values/limits.d.ts

@@ -24,6 +24,10 @@ export declare const VRM_SCALE_MAX = 10;
 export declare const SCENE_LIGHT_RANGE_MAX = 20;
 /** Past this the 5-tap kernel spreads thin enough that its dither reads as noise. */
 export declare const SCENE_LIGHT_SHADOW_RADIUS_MAX = 16;
+/** The point disk's 32 fixed taps stay dense across a far wider penumbra than 5 dithered ones. */
+export declare const SCENE_LIGHT_POINT_SHADOW_RADIUS_MAX = 32;
+/** Shadow softness (PCF disk radius, in shadow-map texels) ceiling for a light of `type`. */
+export declare function sceneLightShadowRadiusMax(type: SceneLightType): number;
 /**
  * Exp2 falloff is squared, so a stage measured in metres is fully socked in well
  * before Unity's nominal 1 — this keeps the slider's useful band across its width.
@@ -60,3 +64,10 @@ export declare const DEFAULT_ELASTICITY: NonNullable<Attach['elasticity']>;
 export declare const ELASTICITY_STIFFNESS_MAX = 100;
 export declare const ELASTICITY_DAMPING_MAX = 10;
 export declare const ELASTICITY_MAX_SPEED_MAX = 100;
+export declare const STORAGE_KEY_MAX_LENGTH = 128;
+/** Ceiling on one value's JSON-serialized length (UTF-16 units, `JSON.stringify(v).length`). */
+export declare const STORAGE_VALUE_MAX_LENGTH: number;
+/** Keys one API key may hold; a `storage.set` that would exceed it answers `invalid-state`. */
+export declare const STORAGE_KEYS_MAX = 256;
+/** `speech.play` URL ceiling — sized for a ~40 s WAV as a base64 `data:audio/*` payload. */
+export declare const SPEECH_URL_MAX_LENGTH = 8000000;

package/dist/values/limits.js

@@ -34,6 +34,12 @@ export const VRM_SCALE_MAX = 10;
 export const SCENE_LIGHT_RANGE_MAX = 20;
 /** Past this the 5-tap kernel spreads thin enough that its dither reads as noise. */
 export const SCENE_LIGHT_SHADOW_RADIUS_MAX = 16;
+/** The point disk's 32 fixed taps stay dense across a far wider penumbra than 5 dithered ones. */
+export const SCENE_LIGHT_POINT_SHADOW_RADIUS_MAX = 32;
+/** Shadow softness (PCF disk radius, in shadow-map texels) ceiling for a light of `type`. */
+export function sceneLightShadowRadiusMax(type) {
+    return type === 'point' ? SCENE_LIGHT_POINT_SHADOW_RADIUS_MAX : SCENE_LIGHT_SHADOW_RADIUS_MAX;
+}
 /**
  * Exp2 falloff is squared, so a stage measured in metres is fully socked in well
  * before Unity's nominal 1 — this keeps the slider's useful band across its width.
@@ -96,3 +102,11 @@ export const DEFAULT_ELASTICITY = { stiffness: 2, damping: 3, maxSpeed: 2 };
 export const ELASTICITY_STIFFNESS_MAX = 100;
 export const ELASTICITY_DAMPING_MAX = 10;
 export const ELASTICITY_MAX_SPEED_MAX = 100;
+// Plugin storage (`storage.*`) — the wire schemas and the server enforce these.
+export const STORAGE_KEY_MAX_LENGTH = 128;
+/** Ceiling on one value's JSON-serialized length (UTF-16 units, `JSON.stringify(v).length`). */
+export const STORAGE_VALUE_MAX_LENGTH = 64 * 1024;
+/** Keys one API key may hold; a `storage.set` that would exceed it answers `invalid-state`. */
+export const STORAGE_KEYS_MAX = 256;
+/** `speech.play` URL ceiling — sized for a ~40 s WAV as a base64 `data:audio/*` payload. */
+export const SPEECH_URL_MAX_LENGTH = 8_000_000;

package/dist/wire/envelope.d.ts

@@ -1,6 +1,7 @@
 import type { ApiErrorCode } from './errors.ts';
 import type { EventData, EventName } from './events.ts';
 import type { MethodName, MethodRequest } from './methods.ts';
+import type { AppCapability } from './types.ts';
 export interface RequestMessage<M extends MethodName = MethodName> {
     kind: 'request';
     /** Correlation id, echoed on the response. Non-empty, client-chosen. */
@@ -38,6 +39,8 @@ export interface AppInfo {
     name: string;
     version: string;
     platform: string;
+    /** Features to gate on — never version-sniff. Empty when the server predates capability reporting. */
+    capabilities: AppCapability[];
 }
 /**
  * Parse one inbound client frame. Returns the request, or an error code telling

package/dist/wire/envelope.js

@@ -1,6 +1,7 @@
 import { isRecord } from "../values/guards.js";
 import { isApiErrorCode } from "./errors.js";
 import { isEventName } from "./events.js";
+import { 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`
@@ -46,7 +47,9 @@ export function parseServerMessage(raw) {
             const { name, version, platform } = v.app;
             if (typeof name !== 'string' || typeof version !== 'string' || typeof platform !== 'string')
                 return null;
-            return { kind: 'hello', protocol: v.protocol, app: { name, version, platform } };
+            // 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) : [];
+            return { kind: 'hello', protocol: v.protocol, app: { name, version, platform, capabilities } };
         }
         case 'response':
             if (typeof v.id !== 'string' || v.id === '')

package/dist/wire/events.d.ts

@@ -10,9 +10,11 @@ export interface EventMap {
         modelId: string | null;
         config: HotkeyState;
     };
+    /** `sources` maps source id → status; optional so pre-multi-source servers still parse. */
     'tracking.status': {
         tracking: TrackingStatus;
         pose: PoseStatus;
+        sources?: Record<string, TrackingStatus>;
     };
     /** A model instance finished loading on stage. */
     'instance.loaded': {
@@ -31,6 +33,14 @@ export interface EventMap {
     'motion.ended': {
         instanceId: string;
     };
+    /** A `speech.play` utterance began on this instance. */
+    'speech.started': {
+        instanceId: string;
+    };
+    /** The utterance finished, failed, was stopped, or was superseded — one `ended` per `started`. */
+    'speech.ended': {
+        instanceId: string;
+    };
     /** True while a scene apply or pipeline warm-up is in flight. */
     'scene.loading': {
         loading: boolean;

package/dist/wire/events.js

@@ -9,6 +9,8 @@ export const EVENT_NAMES = Object.keys({
     'expression.changed': true,
     'motion.started': true,
     'motion.ended': true,
+    'speech.started': true,
+    'speech.ended': true,
     'scene.loading': true,
     'selection.changed': true,
     'registry.changed': true,

package/dist/wire/methods.d.ts

@@ -1,5 +1,5 @@
 import type { EventName } from './events.ts';
-import type { AnchorOption, AssetKind, AssetRef, Attach, Expression, ExpressionPersistence, HotkeyConfig, HotkeyState, InjectEntry, InjectTarget, InstanceRuntime, ModelInfo, ModelRef, MotionGroup, MToonTuning, ObjectContent, ObjectLightOverride, ObjectSpace, Place2D, Place3D, PlayingMotion, PoseSourceId, PoseStatus, Scene, SceneItem, ScenePatch, SceneState, ScreenPlacement, Settings, SettingsPatch, TrackingSourceId, TrackingStatus, VrmPlacement } from './types.ts';
+import type { AnchorOption, AppCapability, AssetKind, AssetRef, Attach, Expression, ExpressionPersistence, HotkeyConfig, HotkeyState, InjectEntry, InjectTarget, InstanceRuntime, JsonValue, ModelInfo, ModelRef, MotionGroup, MToonTuning, ObjectContent, ObjectLightOverride, ObjectSpace, Place2D, Place3D, PlayingMotion, PoseSourceId, PoseStatus, Scene, SceneItem, ScenePatch, SceneState, ScreenPlacement, Settings, SettingsPatch, 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. */
@@ -73,6 +73,13 @@ export interface InstanceSetVisibleRequest {
     visible: boolean;
 }
 export type InstanceSetVisibleResponse = EmptyResponse;
+/** Omitted fields keep their binding; null stops tracking that channel for this instance. */
+export interface InstanceSetTrackingSourcesRequest {
+    instanceId: string;
+    faceSourceId?: string | null;
+    poseSourceId?: string | null;
+}
+export type InstanceSetTrackingSourcesResponse = EmptyResponse;
 export interface InstanceReorderRequest {
     /** Full z-order within the scene; ids not listed keep their relative order at the end. */
     orderedInstanceIds: string[];
@@ -206,6 +213,20 @@ export interface MotionPlayingRequest {
 export interface MotionPlayingResponse {
     playing: PlayingMotion | null;
 }
+/** Play a clip with lip-sync. One utterance per model: a new play supersedes the current one. */
+export interface SpeechPlayRequest {
+    instanceId?: string;
+    /** `https:`/`http:` (local TTS bridges) or an inline `data:audio/*` payload. */
+    url: string;
+    /** 0..1; the backend's own default when omitted. */
+    volume?: number;
+}
+export type SpeechPlayResponse = EmptyResponse;
+/** Stopping a silent model is a silent success. */
+export interface SpeechStopRequest {
+    instanceId?: string;
+}
+export type SpeechStopResponse = EmptyResponse;
 export interface HotkeyListRequest {
     modelId?: string;
 }
@@ -279,10 +300,37 @@ export interface PoseSetPortRequest {
     port: number;
 }
 export type PoseSetPortResponse = EmptyResponse;
+export interface TrackingAddSourceRequest {
+    kind: TrackingSourceKind;
+    name?: string;
+    /** Face kinds: pin to a device IP. */
+    phoneIp?: string | null;
+    /** vmc: the UDP port to listen on; defaults to the next free VMC port. */
+    port?: number;
+}
+export interface TrackingAddSourceResponse {
+    source: TrackingSourceConfig;
+}
+export interface TrackingUpdateSourceRequest {
+    id: string;
+    name?: string;
+    enabled?: boolean;
+    phoneIp?: string | null;
+    port?: number;
+}
+export interface TrackingUpdateSourceResponse {
+    source: TrackingSourceConfig;
+}
+export interface TrackingRemoveSourceRequest {
+    id: string;
+}
+export type TrackingRemoveSourceResponse = EmptyResponse;
 export type TrackingStatusRequest = EmptyRequest;
 export interface TrackingStatusResponse {
     tracking: TrackingStatus;
     pose: PoseStatus;
+    /** Per-source status by {@link TrackingSourceConfig.id}. */
+    sources: Record<string, TrackingStatus>;
 }
 export interface StageResetTransformRequest {
     instanceId?: string;
@@ -298,6 +346,8 @@ export interface AppInfoResponse {
     version: string;
     platform: string;
     protocol: number;
+    /** Same list `hello` carries; gate features on it, never on `version`. */
+    capabilities: AppCapability[];
 }
 export type AppLocalAddressesRequest = EmptyRequest;
 export interface AppLocalAddressesResponse {
@@ -323,6 +373,28 @@ export interface SessionIdentifyRequest {
     developer?: string;
 }
 export type SessionIdentifyResponse = EmptyResponse;
+export interface StorageGetRequest {
+    key: string;
+}
+export interface StorageGetResponse {
+    /** Null when the key was never set (a stored null is indistinguishable by design). */
+    value: JsonValue | null;
+}
+export interface StorageSetRequest {
+    key: string;
+    value: JsonValue;
+}
+export type StorageSetResponse = EmptyResponse;
+/** Deleting an absent key succeeds silently. */
+export interface StorageDeleteRequest {
+    key: string;
+}
+export type StorageDeleteResponse = EmptyResponse;
+export type StorageListRequest = EmptyRequest;
+export interface StorageListResponse {
+    /** Sorted for stable output. */
+    keys: string[];
+}
 export interface EventsSubscribeRequest {
     events: EventName[];
 }
@@ -413,6 +485,11 @@ export interface MethodMap {
         request: InstanceSetVisibleRequest;
         response: InstanceSetVisibleResponse;
     };
+    /** Bind this instance's face/pose channels to tracking sources (null stops tracking that channel). */
+    'instance.setTrackingSources': {
+        request: InstanceSetTrackingSourcesRequest;
+        response: InstanceSetTrackingSourcesResponse;
+    };
     'instance.reorder': {
         request: InstanceReorderRequest;
         response: InstanceReorderResponse;
@@ -511,6 +588,18 @@ export interface MethodMap {
         request: MotionPlayingRequest;
         response: MotionPlayingResponse;
     };
+    /**
+     * Lip-synced audio on models advertising the `speech` capability. The response means
+     * playback started (else `invalid-state`); `speech.started`/`speech.ended` bracket it.
+     */
+    'speech.play': {
+        request: SpeechPlayRequest;
+        response: SpeechPlayResponse;
+    };
+    'speech.stop': {
+        request: SpeechStopRequest;
+        response: SpeechStopResponse;
+    };
     'hotkey.list': {
         request: HotkeyListRequest;
         response: HotkeyListResponse;
@@ -551,18 +640,33 @@ export interface MethodMap {
         request: TrackingSetEnabledRequest;
         response: TrackingSetEnabledResponse;
     };
+    /** Legacy single-source setter: rewrites the first face source's kind. Prefer the source CRUD below. */
     'tracking.setSource': {
         request: TrackingSetSourceRequest;
         response: TrackingSetSourceResponse;
     };
+    'tracking.addSource': {
+        request: TrackingAddSourceRequest;
+        response: TrackingAddSourceResponse;
+    };
+    'tracking.updateSource': {
+        request: TrackingUpdateSourceRequest;
+        response: TrackingUpdateSourceResponse;
+    };
+    'tracking.removeSource': {
+        request: TrackingRemoveSourceRequest;
+        response: TrackingRemoveSourceResponse;
+    };
     'pose.setEnabled': {
         request: PoseSetEnabledRequest;
         response: PoseSetEnabledResponse;
     };
+    /** Legacy: operates on the first vmc source. Prefer the tracking.* source CRUD. */
     'pose.setSource': {
         request: PoseSetSourceRequest;
         response: PoseSetSourceResponse;
     };
+    /** Legacy: sets the first vmc source's port. */
     'pose.setPort': {
         request: PoseSetPortRequest;
         response: PoseSetPortResponse;
@@ -603,6 +707,27 @@ export interface MethodMap {
         request: SessionIdentifyRequest;
         response: SessionIdentifyResponse;
     };
+    /**
+     * Durable key–value storage namespaced by the session's API key; revoking the key deletes
+     * it. Limits: `STORAGE_KEY_MAX_LENGTH`, `STORAGE_VALUE_MAX_LENGTH`, `STORAGE_KEYS_MAX`
+     * keys (over-quota answers `invalid-state`).
+     */
+    'storage.get': {
+        request: StorageGetRequest;
+        response: StorageGetResponse;
+    };
+    'storage.set': {
+        request: StorageSetRequest;
+        response: StorageSetResponse;
+    };
+    'storage.delete': {
+        request: StorageDeleteRequest;
+        response: StorageDeleteResponse;
+    };
+    'storage.list': {
+        request: StorageListRequest;
+        response: StorageListResponse;
+    };
     'events.subscribe': {
         request: EventsSubscribeRequest;
         response: EventsSubscribeResponse;

package/dist/wire/schemas.d.ts

@@ -93,6 +93,27 @@ export declare const requestSchemas: {
     'hotkey.trigger': z.ZodObject<{
         hotkeyId: z.ZodString;
     }, z.core.$strip>;
+    'tracking.addSource': z.ZodObject<{
+        kind: z.ZodEnum<{
+            "vts-ios": "vts-ios";
+            "vts-ios-native": "vts-ios-native";
+            ifacialmocap: "ifacialmocap";
+            vmc: "vmc";
+        }>;
+        name: z.ZodOptional<z.ZodString>;
+        phoneIp: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        port: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+    'tracking.updateSource': z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+        enabled: z.ZodOptional<z.ZodBoolean>;
+        phoneIp: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        port: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+    'tracking.removeSource': z.ZodObject<{
+        id: z.ZodString;
+    }, z.core.$strip>;
     'model.register': z.ZodObject<{
         path: z.ZodString;
     }, z.core.$strip>;
@@ -153,6 +174,24 @@ export declare const requestSchemas: {
         version: z.ZodOptional<z.ZodString>;
         developer: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
+    'storage.get': z.ZodObject<{
+        key: z.ZodString;
+    }, z.core.$strip>;
+    'storage.set': z.ZodObject<{
+        key: z.ZodString;
+        value: z.ZodJSONSchema;
+    }, z.core.$strip>;
+    'storage.delete': z.ZodObject<{
+        key: z.ZodString;
+    }, z.core.$strip>;
+    'speech.play': z.ZodObject<{
+        instanceId: z.ZodOptional<z.ZodString>;
+        url: z.ZodString;
+        volume: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+    'speech.stop': z.ZodObject<{
+        instanceId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
     'events.subscribe': z.ZodObject<{
         events: z.ZodArray<z.ZodCustom<keyof import("./events.ts").EventMap, keyof import("./events.ts").EventMap>>;
     }, z.core.$strip>;

package/dist/wire/schemas.js

@@ -1,11 +1,13 @@
 import * as z from 'zod';
 import { isRecord } from "../values/guards.js";
+import { SPEECH_URL_MAX_LENGTH, STORAGE_KEY_MAX_LENGTH, STORAGE_VALUE_MAX_LENGTH } from "../values/limits.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
 // one are stage-owned — the renderer validates and heals them (same rules as the
 // panel). Fields marked z.custom are deliberately gated shallowly here because
 // the app heals them into shape server-side.
 const nonEmpty = z.string().min(1);
+const port = z.number().int().min(1).max(65535);
 export const InjectTargetSchema = z.object({
     type: z.enum(['input', 'live2d-param', 'vrm-expression']),
     id: nonEmpty,
@@ -30,6 +32,25 @@ export const SettingsPatchSchema = z.object({
 });
 /** Tolerates unknown names for version skew; the server filters them and reports what took. */
 const lenientEventNameSchema = z.custom(v => typeof v === 'string', 'event names must be strings');
+const storageKey = z.string().min(1).max(STORAGE_KEY_MAX_LENGTH);
+/** JSON-serializable and bounded; the serialized-length cap is what the server persists by. */
+const storageValue = z
+    .json()
+    .refine(v => JSON.stringify(v).length <= STORAGE_VALUE_MAX_LENGTH, `value exceeds ${STORAGE_VALUE_MAX_LENGTH} serialized chars`);
+/** http(s) covers hosted clips and local TTS bridges; data: carries inline audio only. */
+const speechUrl = z
+    .string()
+    .min(1)
+    .max(SPEECH_URL_MAX_LENGTH)
+    .refine(v => {
+    try {
+        const p = new URL(v).protocol;
+        return p === 'https:' || p === 'http:' || (p === 'data:' && v.slice(5, 11) === 'audio/');
+    }
+    catch {
+        return false;
+    }
+}, 'url must be http(s) or data:audio/*');
 export const requestSchemas = {
     'scene.get': z.object({ sceneId: nonEmpty.optional() }),
     'scene.activate': z.object({ sceneId: nonEmpty }),
@@ -55,6 +76,20 @@ export const requestSchemas = {
         config: z.custom(isRecord, 'config must be a hotkey config'),
     }),
     'hotkey.trigger': z.object({ hotkeyId: nonEmpty }),
+    'tracking.addSource': z.object({
+        kind: z.enum(['vts-ios', 'vts-ios-native', 'ifacialmocap', 'vmc']),
+        name: z.string().optional(),
+        phoneIp: nonEmpty.nullable().optional(),
+        port: port.optional(),
+    }),
+    'tracking.updateSource': z.object({
+        id: nonEmpty,
+        name: z.string().optional(),
+        enabled: z.boolean().optional(),
+        phoneIp: nonEmpty.nullable().optional(),
+        port: port.optional(),
+    }),
+    'tracking.removeSource': z.object({ id: nonEmpty }),
     'model.register': z.object({ path: nonEmpty }),
     'asset.register': z.object({ path: nonEmpty, want: z.enum(['image', 'video', 'prop', 'ibl', 'lut']).optional() }),
     'settings.patch': z.object({ settings: SettingsPatchSchema }),
@@ -62,12 +97,21 @@ export const requestSchemas = {
     'tracking.setSource': z.object({ source: z.enum(['vts-ios', 'vts-ios-native', 'ifacialmocap']) }),
     'pose.setEnabled': z.object({ enabled: z.boolean() }),
     'pose.setSource': z.object({ source: z.enum(['vmc']) }),
-    'pose.setPort': z.object({ port: z.number().int().min(1).max(65535) }),
+    'pose.setPort': z.object({ port }),
     'session.identify': z.object({
         name: z.string().trim().min(1).max(64),
         version: z.string().max(32).optional(),
         developer: z.string().max(64).optional(),
     }),
+    'storage.get': z.object({ key: storageKey }),
+    'storage.set': z.object({ key: storageKey, value: storageValue }),
+    'storage.delete': z.object({ key: storageKey }),
+    'speech.play': z.object({
+        instanceId: nonEmpty.optional(),
+        url: speechUrl,
+        volume: z.number().min(0).max(1).optional(),
+    }),
+    'speech.stop': z.object({ instanceId: nonEmpty.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) }),

package/dist/wire/types.d.ts

@@ -109,6 +109,13 @@ export interface SceneModelItem {
     instanceId: string;
     ref: ModelRef;
     visible: boolean;
+    /**
+     * Face source tracking this instance ({@link TrackingSourceConfig.id}); null = its face is untracked.
+     * A dangling or disabled id behaves as null. One source may track several instances (mirroring).
+     */
+    faceSourceId: string | null;
+    /** Body source (vmc) tracking this instance; null = its pose is untracked. New instances bind to each channel's default source. */
+    poseSourceId: string | null;
     live2d: ScreenPlacement;
     vrm: VrmPlacement;
     idleAnimation: boolean;
@@ -371,6 +378,24 @@ export interface SceneDroplets {
     /** Specular glint on drops where the frame is transparent, so rain reads over the desktop (0 to 1). */
     glints: number;
 }
+/** Compute-driven snowfall in the 3D scene: flakes drift down, settle on models and props, then melt. */
+export interface SceneSnow {
+    enabled: boolean;
+    /** How many flakes are alive at once. */
+    amount: number;
+    /** Fall and drift clock multiplier. */
+    speed: number;
+    /** Steady sideways drift, in metres per second along the stage's x axis. */
+    wind: number;
+    /** Horizontal wobble while falling. */
+    sway: number;
+    /** Flake size multiplier. */
+    size: number;
+    /** Seconds a settled flake rests before it finishes melting away. */
+    melt: number;
+    /** Flake opacity. */
+    opacity: number;
+}
 /**
  * Post-processing over the rendered 3D frame. Everything off skips the effect
  * chain entirely. Deliberately flat: every toggle-plus-numbers effect sits at
@@ -391,6 +416,7 @@ export interface SceneEffects {
     pixelate: ScenePixelate;
     glitch: SceneGlitch;
     droplets: SceneDroplets;
+    snow: SceneSnow;
 }
 /**
  * Image-based lighting for the 3D stage: an environment map, whether to show it
@@ -438,8 +464,17 @@ export interface ScenePatch {
     lights?: SceneLight[];
     environment?: SceneEnvironment;
 }
+/**
+ * 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"];
+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`. */
-export type InstanceCapability = 'motions' | 'expressions' | 'placement-2d' | 'placement-3d' | 'mtoon' | 'idle-clips' | 'pose' | 'live2d-params';
+export type InstanceCapability = 'motions' | 'expressions' | 'placement-2d' | 'placement-3d' | 'mtoon' | 'idle-clips' | 'pose' | 'live2d-params'
+/** `speech.play` lip-sync; engine-dependent, so gate on the runtime, not the format. */
+ | 'speech';
 export interface InstanceRuntime {
     instanceId: string;
     kind: 'model' | 'object';
@@ -503,6 +538,10 @@ export interface ExpressionPersistence {
     enabled: boolean;
     saved: string[];
 }
+/** Any JSON-serializable value — what `storage.set` accepts and `storage.get` returns. */
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
 export declare const TRACKING_SOURCE_IDS: readonly ["vts-ios", "vts-ios-native", "ifacialmocap"];
 export type TrackingSourceId = (typeof TRACKING_SOURCE_IDS)[number];
 /** Body-pose protocols. Every one so far is UDP with a configurable port. */
@@ -510,6 +549,29 @@ export declare const POSE_SOURCE_IDS: readonly ["vmc"];
 export type PoseSourceId = (typeof POSE_SOURCE_IDS)[number];
 export type TrackingStatus = 'off' | 'waiting' | 'tracking' | 'no-face';
 export type PoseStatus = 'off' | 'waiting' | 'tracking';
+/** Every protocol a tracking source instance can speak; face kinds plus the body (vmc) kind. */
+export declare const TRACKING_SOURCE_KINDS: readonly ["vts-ios", "vts-ios-native", "ifacialmocap", "vmc"];
+export type TrackingSourceKind = (typeof TRACKING_SOURCE_KINDS)[number];
+/** Whether a source kind feeds the face channel (vmc is the body channel). */
+export declare function isFaceSourceKind(kind: TrackingSourceKind): kind is TrackingSourceId;
+/**
+ * One configured tracking source instance. Several can run at once — one per person —
+ * and scene model instances bind to them by id (`SceneModelItem.faceSourceId`/`poseSourceId`).
+ */
+export interface TrackingSourceConfig {
+    id: string;
+    kind: TrackingSourceKind;
+    /** User label shown in lists; '' renders as the kind's own label. */
+    name: string;
+    enabled: boolean;
+    /**
+     * Face kinds: accept only this device/sender IP; null accepts any sender not claimed
+     * by a pinned instance of the same kind. Ignored by vmc (its senders pick the port).
+     */
+    phoneIp: string | null;
+    /** vmc only: the UDP port this instance listens on. Null on face kinds — they bind per protocol. */
+    port: number | null;
+}
 export declare const EFFECTS_QUALITY_LEVELS: readonly ["low", "medium", "high"];
 export type EffectsQuality = (typeof EFFECTS_QUALITY_LEVELS)[number];
 /**
@@ -532,10 +594,13 @@ export interface Settings {
         selectionOutline: boolean;
         effectsQuality: EffectsQuality;
     };
+    /** `source` mirrors the first face source's kind — the pre-multi-source field, kept for old clients. */
     tracking: {
         enabled: boolean;
         source: TrackingSourceId;
+        sources: TrackingSourceConfig[];
     };
+    /** `source`/`port` mirror the first vmc source — the pre-multi-source fields, kept for old clients. */
     pose: {
         enabled: boolean;
         source: PoseSourceId;

package/dist/wire/types.js

@@ -7,10 +7,25 @@
  * directional light covers with one map, so it gets the smaller of the pair.
  */
 export const SHADOW_QUALITY_LEVELS = ['off', 'low', 'medium', 'high', 'extra'];
+// ---- Runtime state -------------------------------------------------------------
+/**
+ * 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 const APP_CAPABILITIES = ['storage', 'speech'];
+export function isAppCapability(v) {
+    return typeof v === 'string' && APP_CAPABILITIES.includes(v);
+}
 // ---- Settings ------------------------------------------------------------------
 export const TRACKING_SOURCE_IDS = ['vts-ios', 'vts-ios-native', 'ifacialmocap'];
 /** Body-pose protocols. Every one so far is UDP with a configurable port. */
 export const POSE_SOURCE_IDS = ['vmc'];
+/** Every protocol a tracking source instance can speak; face kinds plus the body (vmc) kind. */
+export const TRACKING_SOURCE_KINDS = [...TRACKING_SOURCE_IDS, ...POSE_SOURCE_IDS];
+/** Whether a source kind feeds the face channel (vmc is the body channel). */
+export function isFaceSourceKind(kind) {
+    return TRACKING_SOURCE_IDS.includes(kind);
+}
 export const EFFECTS_QUALITY_LEVELS = ['low', 'medium', 'high'];
 /**
  * Accepted values for `performance.fpsLimit`; 0 = unlimited. Anything else is snapped

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@laplace.live/persona-sdk",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "TypeScript SDK and wire schema for the LAPLACE Persona plugin API",
   "license": "MIT",
   "type": "module",
@@ -28,7 +28,7 @@
   "devDependencies": {
     "rimraf": "^6.1.3",
     "typescript": "~6.0.3",
-    "vitest": "^4.1.10"
+    "vitest": "^4.1.11"
   },
   "engines": {
     "node": ">=22"