@laplace.live/persona-sdk 0.6.0 → 0.8.0

package/dist/values/limits.js

@@ -0,0 +1,112 @@
+export function clamp(v, min, max) {
+    return Math.min(max, Math.max(min, v));
+}
+/** Clamp to the unit interval. */
+export function clamp01(v) {
+    return v < 0 ? 0 : v > 1 ? 1 : v;
+}
+export const DEFAULT_LIVE2D_PLACEMENT = { x: 0, y: 0, scale: 1, rotation: 0 };
+export const DEFAULT_VRM_PLACEMENT = { x: 0, y: 0, z: 0, rotX: 0, rotY: 0, rotZ: 0, scale: 1 };
+/** Scene colors heal to 6-digit hex. */
+export const SCENE_COLOR_RE = /^#[0-9a-f]{6}$/i;
+/** Drop the alpha byte a picker's hex input can produce (`#rrggbbaa` → `#rrggbb`). */
+export function opaqueHex(hex) {
+    return /^#[0-9a-f]{8}$/i.test(hex) ? hex.slice(0, 7) : hex;
+}
+export const SCENE_LIGHT_INTENSITY_MAX = 2;
+/**
+ * Point lights decay physically (1/d²), so reach rides on power the way Blender's
+ * does: 20 stays visible to ~10 m where 2 self-extinguishes by ~5. The other
+ * types have no falloff to overcome — 20 would just blow the stage out.
+ */
+export const SCENE_LIGHT_POINT_INTENSITY_MAX = 20;
+/** Intensity ceiling for a light of `type` — one source for the slider and scene healing. */
+export function sceneLightIntensityMax(type) {
+    return type === 'point' ? SCENE_LIGHT_POINT_INTENSITY_MAX : SCENE_LIGHT_INTENSITY_MAX;
+}
+// Live2D bounds are the zoom clamp (zoom.ts re-exports these); VRM scales a world-space root.
+export const LIVE2D_SCALE_MIN = 0.1;
+export const LIVE2D_SCALE_MAX = 24;
+export const VRM_SCALE_MIN = 0.05;
+export const VRM_SCALE_MAX = 10;
+// Range only *cuts off* a point light — three's 1/d² decay has extinguished it
+// by ~18 m even at max intensity, so a slider past 20 changes nothing visible.
+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.
+ */
+export const SCENE_FOG_DENSITY_MAX = 0.5;
+/** ×4 is +2 stops — enough to rescue an AgX-dimmed avatar without turning the slider to mush. */
+export const SCENE_EXPOSURE_MAX = 4;
+export const MTOON_RIM_MAX = 2;
+export const MTOON_OUTLINE_WIDTH_MAX = 2;
+/** HDR headroom: past ×1 the point is pushing emissive parts over the bloom threshold. */
+export const MTOON_EMISSIVE_MAX = 4;
+export function defaultMToonTuning() {
+    return { shade: 1, shadingShift: 0, shadingToony: 0, giEqualization: 0, rim: 1, outlineWidth: 1, emissive: 1 };
+}
+// Ranges for toggle-style effect params live in effect-schema.ts (EFFECT_SPECS).
+// Angles at which lightDirection reproduces (1,1,1).normalize() — the app's original hardcoded light.
+export const DEFAULT_LIGHT_AZIMUTH_DEG = 45;
+export const DEFAULT_LIGHT_ELEVATION_DEG = (Math.asin(1 / Math.sqrt(3)) * 180) / Math.PI;
+/** A fresh light of `type`, at the defaults that read sensibly for that type. */
+export function defaultSceneLightOf(type) {
+    return {
+        id: crypto.randomUUID(),
+        type,
+        color: '#ffffff',
+        intensity: 1,
+        azimuth: DEFAULT_LIGHT_AZIMUTH_DEG,
+        elevation: DEFAULT_LIGHT_ELEVATION_DEG,
+        x: 0,
+        y: 1.4,
+        z: 1,
+        range: 10,
+        // A point light shadow is six cube faces, so it stays opt-in where a
+        // directional light's single depth pass can be on by default.
+        shadowQuality: type === 'directional' ? 'high' : 'off',
+        shadowRadius: 6,
+    };
+}
+export const PLACE_2D_SCALE_MIN = 0.01;
+export const PLACE_2D_SCALE_MAX = 50;
+export const PLACE_3D_SCALE_MIN = 0.01;
+export const PLACE_3D_SCALE_MAX = 100;
+/** A prop is a mesh, so it only exists in the three.js scene; every other kind renders in both. */
+export function objectSupportsSpace(kind, space) {
+    return kind === 'prop' ? space === '3d' : true;
+}
+/**
+ * The one model format a space's objects can ride: the renderers never mix, and
+ * the three canvas always composites over the Pixi one, so a cross-space pin
+ * would z-fight by construction.
+ */
+export function attachableParentFormat(space) {
+    return space === '2d' ? 'live2d' : 'vrm';
+}
+export const DEFAULT_HEAD_ANGLE = { multiplier: 1, smoothing: 15 };
+export const ATTACH_MULTIPLIER_MIN = -2;
+export const ATTACH_MULTIPLIER_MAX = 2;
+export const ATTACH_SMOOTHING_MAX = 50;
+// Warudo Attachable defaults and slider ceilings, verbatim.
+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/values/locale.d.ts

@@ -0,0 +1,9 @@
+/** Locales shipped in the compiled catalogs (`pnpm i18n`). */
+export declare const LOCALES: readonly ["en", "ja", "zh-CN", "zh-TW"];
+export type Locale = (typeof LOCALES)[number];
+/** `ui.language` setting: an explicit locale, or follow the OS language. */
+export type LanguageSetting = 'system' | Locale;
+/** Native-language display names for the language picker (deliberately untranslated). */
+export declare const LOCALE_LABELS: Record<Locale, string>;
+/** Best supported locale for a BCP 47-ish tag: exact match first, then fuzzy per language. */
+export declare function matchLocaleTag(tag: string): Locale;

package/dist/values/locale.js

@@ -0,0 +1,21 @@
+/** Locales shipped in the compiled catalogs (`pnpm i18n`). */
+export const LOCALES = ['en', 'ja', 'zh-CN', 'zh-TW'];
+/** Native-language display names for the language picker (deliberately untranslated). */
+export const LOCALE_LABELS = {
+    en: 'English',
+    ja: '日本語',
+    'zh-CN': '简体中文',
+    'zh-TW': '繁體中文',
+};
+/** Best supported locale for a BCP 47-ish tag: exact match first, then fuzzy per language. */
+export function matchLocaleTag(tag) {
+    if (LOCALES.includes(tag))
+        return tag;
+    const t = tag.toLowerCase();
+    // Most systems/browsers report `zh-TW`/`zh-HK` with no `hant` subtag, so match the regions too.
+    if (t.startsWith('zh'))
+        return /hant|tw|hk|mo/.test(t) ? 'zh-TW' : 'zh-CN';
+    if (t.startsWith('ja'))
+        return 'ja';
+    return 'en';
+}

package/dist/{envelope.d.ts → 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. */
@@ -12,11 +13,7 @@ export interface RequestMessage<M extends MethodName = MethodName> {
 export interface HelloMessage {
     kind: 'hello';
     protocol: number;
-    app: {
-        name: string;
-        version: string;
-        platform: string;
-    };
+    app: AppInfo;
 }
 export interface ResponseMessage {
     kind: 'response';
@@ -37,6 +34,14 @@ export interface EventMessage<E extends EventName = EventName> {
 }
 export type ServerMessage = HelloMessage | ResponseMessage | ErrorMessage | EventMessage;
 export type ClientMessage = RequestMessage;
+/** The desktop app's identity, as `hello` reports it. */
+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
  * the server what to answer: `parse-error` for junk bytes, `invalid-request`

package/dist/{envelope.js → wire/envelope.js}

@@ -1,8 +1,7 @@
+import { isRecord } from "../values/guards.js";
 import { isApiErrorCode } from "./errors.js";
 import { isEventName } from "./events.js";
-function isRecord(v) {
-    return typeof v === 'object' && v !== null && !Array.isArray(v);
-}
+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`
@@ -48,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/{events.d.ts → 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/{events.js → 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/{methods.d.ts → 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/{protocol.d.ts → wire/protocol.d.ts}

@@ -3,10 +3,14 @@ import type { InjectTarget } from './types.ts';
 export declare const PROTOCOL_VERSION = 1;
 /** Default port the Persona API server listens on (user-configurable in the app). */
 export declare const DEFAULT_API_PORT = 25034;
+/** Default host clients dial: the server binds loopback unless LAN is opted in. */
+export declare const DEFAULT_API_HOST = "127.0.0.1";
 /** 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. */
 export declare const CLOSE_FORCE_DISCONNECTED = 4002;
+/** Standard going-away code the server sends when it stops; reconnecting is expected once it returns. */
+export declare const CLOSE_SERVER_STOPPING = 1001;
 /** An injected parameter reverts this long after its last write — the lease, not a setting. */
 export declare const INJECT_LEASE_TTL_MS = 1000;
 /** How often {@link PersonaClient.driveParameter} re-sends held leases to keep them alive. */

package/dist/{protocol.js → wire/protocol.js}

@@ -2,10 +2,14 @@
 export const PROTOCOL_VERSION = 1;
 /** Default port the Persona API server listens on (user-configurable in the app). */
 export const DEFAULT_API_PORT = 25034;
+/** Default host clients dial: the server binds loopback unless LAN is opted in. */
+export const DEFAULT_API_HOST = '127.0.0.1';
 /** 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. */
 export const CLOSE_FORCE_DISCONNECTED = 4002;
+/** Standard going-away code the server sends when it stops; reconnecting is expected once it returns. */
+export const CLOSE_SERVER_STOPPING = 1001;
 /** An injected parameter reverts this long after its last write — the lease, not a setting. */
 export const INJECT_LEASE_TTL_MS = 1000;
 /** How often {@link PersonaClient.driveParameter} re-sends held leases to keep them alive. */

package/dist/{schemas.d.ts → 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/{schemas.js → wire/schemas.js}

@@ -1,13 +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.
-function isRecord(v) {
-    return typeof v === 'object' && v !== null && !Array.isArray(v);
-}
 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,
@@ -32,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 }),
@@ -57,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 }),
@@ -64,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) }),