@laplace.live/persona-sdk 1.24.0 → 1.25.1

package/dist/values/limits.js

@@ -1,4 +1,5 @@
 import { effectLayerKeys } from "./effect-schema.js";
+import { isFiniteNumber, isOneOf, isRecord } from "./guards.js";
 export function clamp(v, min, max) {
     return Math.min(max, Math.max(min, v));
 }
@@ -16,6 +17,10 @@ export function wrapAngle(a) {
         r += TAU;
     return r;
 }
+/** Wrap degrees into (-180°, 180°], {@link wrapAngle}'s range; whole turns keep in-range values exact. */
+export function wrapDegrees(v) {
+    return v - 360 * Math.ceil((v - 180) / 360);
+}
 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; both cases are spelled out because JSON Schema patterns carry no flags. */
@@ -43,6 +48,11 @@ export const SCENE_LIGHT_SPOT_ANGLE_MIN = 1;
 export const SCENE_LIGHT_SPOT_ANGLE_MAX = 89;
 export const DEFAULT_SPOT_ANGLE_DEG = 30;
 export const DEFAULT_SPOT_PENUMBRA = 0.3;
+/** Light azimuth and roll bounds in degrees, symmetric: a half turn either way. */
+export const SCENE_LIGHT_AZIMUTH_MAX = 180;
+export const SCENE_LIGHT_ROLL_MAX = 180;
+/** Light elevation bound in degrees, symmetric: straight up or straight down. */
+export const SCENE_LIGHT_ELEVATION_MAX = 90;
 /** Positional lights need falloff headroom; the slider and scene healing share this ceiling. */
 export function sceneLightIntensityMax(type) {
     return type === 'directional' || type === 'ambient' ? SCENE_LIGHT_INTENSITY_MAX : SCENE_LIGHT_POINT_INTENSITY_MAX;
@@ -68,6 +78,7 @@ 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;
+export const SCENE_LIGHT_RANGE_MIN = 0.1;
 // 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;
@@ -77,6 +88,8 @@ export const SCENE_LIGHT_SHADOW_RADIUS_MAX = 16;
 export const SCENE_LIGHT_POINT_SHADOW_RADIUS_MAX = 32;
 export const SCENE_LIGHT_SHADOW_SOURCE_SIZE_MAX = 10;
 export const DEFAULT_LIGHT_SHADOW_SOURCE_SIZE = 0.1;
+/** A light override's key: the baked light's traversal index, in decimal digits. */
+export const LIGHT_OVERRIDE_KEY_RE = /^\d+$/;
 /** 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;
@@ -99,6 +112,8 @@ export const CAMERA_DAMPING_MAX = 10;
 /** Ceiling for {@link SceneCameraAim}'s lookahead time, in seconds, and its smoothing. */
 export const CAMERA_AIM_LOOKAHEAD_MAX = 1;
 export const CAMERA_AIM_SMOOTHING_MAX = 30;
+/** {@link SceneCameraAim}'s bias bound on each axis, symmetric: a share of the slack between its zones. */
+export const CAMERA_AIM_BIAS_MAX = 0.5;
 /** Ceiling for {@link SceneCameraHandheld}'s speed. */
 export const CAMERA_HANDHELD_SPEED_MAX = 2;
 /** Warudo's Handheld Movement defaults, switched off. */
@@ -158,6 +173,18 @@ export function cameraTrackKind(item) {
         return item.ref.kind === 'vrm' ? 'model' : null;
     return item.space === '3d' ? 'object' : null;
 }
+/**
+ * The layer `target` tracks in `scene` — the primary model for a primary pick, else the first model — when it
+ * is one a camera can track.
+ */
+export function cameraTrackItem(scene, target) {
+    // Runs per frame for each camera track, so it searches the list rather than filtering a copy.
+    const item = target.target === 'primary'
+        ? (scene.items.find(i => i.kind === 'model' && i.instanceId === scene.primaryInstanceId) ??
+            scene.items.find(i => i.kind === 'model'))
+        : scene.items.find(i => i.instanceId === target.instanceId);
+    return item && cameraTrackKind(item) ? item : undefined;
+}
 /** Rows for the camera's follow, aim and focus pickers, in layer order. One rule, or the console offers a layer the desktop drops. */
 export function cameraTrackCandidates(items) {
     return items.flatMap(item => {
@@ -196,6 +223,23 @@ 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 const MTOON_UV_ANIMATION_MAX = 4;
+/** Each {@link MToonTuning} field's `[min, max]`: offsets −1..1, `shade` 0..1, multipliers 0 to their ceiling. */
+export const MTOON_RANGES = {
+    shade: [0, 1],
+    shadingShift: [-1, 1],
+    shadingToony: [-1, 1],
+    giEqualization: [-1, 1],
+    normalScale: [0, MTOON_NORMAL_SCALE_MAX],
+    rim: [0, MTOON_RIM_MAX],
+    rimLift: [-1, 1],
+    rimFresnelPower: [0, MTOON_RIM_FRESNEL_POWER_MAX],
+    rimLightingMix: [-1, 1],
+    matcap: [0, MTOON_MATCAP_MAX],
+    outlineWidth: [0, MTOON_OUTLINE_WIDTH_MAX],
+    outlineLightingMix: [-1, 1],
+    emissive: [0, MTOON_EMISSIVE_MAX],
+    uvAnimation: [0, MTOON_UV_ANIMATION_MAX],
+};
 export function defaultMToonTuning() {
     return {
         shade: 1,
@@ -402,13 +446,35 @@ export const TEXT_BEVEL_RESOLUTION_MAX = 8;
 export const TEXT_EMISSION_MAX = 4;
 /** A PostScript name: printable ASCII, at most 63 chars, minus the quote and backslash that would escape `local("…")`. */
 export const TEXT_POSTSCRIPT_NAME_RE = /^[\x21\x23-\x5b\x5d-\x7e]{1,63}$/;
+/** A text font's CSS `font-weight` bounds. */
+export const TEXT_FONT_WEIGHT_MIN = 1;
+export const TEXT_FONT_WEIGHT_MAX = 1000;
+/** A text font's CSS `font-stretch` bounds, in percent. */
+export const TEXT_FONT_STRETCH_MIN = 50;
+export const TEXT_FONT_STRETCH_MAX = 200;
+/** CSS's normal face: what a text font, or a font file, that leaves its weight, slope or width unsaid reads as. */
+export const DEFAULT_TEXT_FONT_FACE = {
+    weight: 400,
+    italic: false,
+    stretch: 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 {@link ObjectContent} kinds that stream from a registered asset; the rest carry their source inline. */
+const ASSET_CONTENT_KINDS = ['image', 'video', 'prop'];
+/** Whether `kind` — a content kind, or an Inventory row's — is one whose asset streams into a layer. */
+export function isAssetContentKind(kind) {
+    return isOneOf(kind, ASSET_CONTENT_KINDS);
+}
+/** Whether the content streams from a registered asset: image, video and prop; the rest carry their source inline. */
+export function isAssetContent(content) {
+    return isAssetContentKind(content.kind);
+}
 /** The asset an object streams from, or null for kinds that carry their source inline (web, capture, text). */
 export function contentAssetId(content) {
-    return content.kind === 'image' || content.kind === 'video' || content.kind === 'prop' ? content.assetId : null;
+    return isAssetContent(content) ? content.assetId : null;
 }
 /**
  * The one model format a space's objects can ride: the screen layer always composites
@@ -453,6 +519,14 @@ export function pinnableParents(models, items, instanceId) {
     }
     return out;
 }
+/**
+ * {@link pinnableParents} for an object: every model of the one format its space can ride. Nothing
+ * rides an object, so no row is ever flagged.
+ */
+export function objectPinParents(models, space) {
+    const format = attachableParentFormat(space);
+    return models.filter(m => m.ref.kind === format).map(m => ({ instanceId: m.instanceId, name: m.ref.name }));
+}
 /**
  * Whether pinning puts an item inside its Live2D host's ArtMesh stack, where `attach.depth` places
  * it: a Live2D item, or a 2D object as one quad. A 3D object only ever paints in front.
@@ -477,6 +551,38 @@ export function depthStopIndex(meshes, depth) {
     const at = meshes.indexOf(depth.id);
     return at < 0 ? meshes.length + 1 : at + 1;
 }
+/** Three non-negative finite numbers — whole ones when `int` — or null. */
+function healTriple(raw, int) {
+    if (!Array.isArray(raw) || raw.length !== 3)
+        return null;
+    const usable = (v) => isFiniteNumber(v) && v >= 0 && (!int || Number.isInteger(v));
+    const [a, b, c] = raw;
+    return usable(a) && usable(b) && usable(c) ? [a, b, c] : null;
+}
+/** A stored anchor — a model's root, a VRM bone or a point on a Live2D ArtMesh — as a usable one, or null. */
+export function healAttachAnchor(raw) {
+    if (!isRecord(raw))
+        return null;
+    if (raw.kind === 'root')
+        return { kind: 'root' };
+    if (raw.kind === 'bone')
+        return typeof raw.bone === 'string' && raw.bone !== '' ? { kind: 'bone', bone: raw.bone } : null;
+    if (raw.kind !== 'artMesh' || typeof raw.id !== 'string' || raw.id === '')
+        return null;
+    const verts = healTriple(raw.verts, true);
+    const weights = healTriple(raw.weights, false);
+    if (!verts || !weights)
+        return null;
+    const sum = weights[0] + weights[1] + weights[2];
+    // Finite weights can still sum to Infinity; dividing by it would zero the point.
+    if (!Number.isFinite(sum) || sum <= 0)
+        return null;
+    // Normalized so the point stays inside its triangle whatever was stored. A normalized triple is kept
+    // bit for bit: dividing it again can flip last bits, and hosts key anchor caches on them.
+    if (Math.abs(sum - 1) < 1e-9)
+        return { kind: 'artMesh', id: raw.id, verts, weights };
+    return { kind: 'artMesh', id: raw.id, verts, weights: [weights[0] / sum, weights[1] / sum, weights[2] / sum] };
+}
 export const DEFAULT_HEAD_ANGLE = {
     multiplier: 1,
     parallaxX: 0,
@@ -514,6 +620,8 @@ export const STORAGE_KEY_MAX_LENGTH = 128;
 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;
+/** `session.identify` refuses a longer name, so a client composing one trims it to this. */
+export const SESSION_NAME_MAX_LENGTH = 64;
 /** `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/lipsync.d.ts

@@ -54,19 +54,18 @@ export interface LipSyncSample {
     /** Smoothed vowel weights sum to at most one; the remainder represents non-vowel audio. */
     vowels: Record<LipSyncVowel, number>;
 }
+/** A capture or output device as a device picker lists it. */
+export interface MediaDeviceOption {
+    deviceId: string;
+    label: string;
+}
 export interface LipSyncState {
     config: LipSyncConfig;
     status: 'off' | 'starting' | 'listening' | 'error';
     error: 'permission' | 'device' | 'analysis' | null;
-    devices: {
-        deviceId: string;
-        label: string;
-    }[];
+    devices: MediaDeviceOption[];
     sample: LipSyncSample | null;
-    microphone: {
-        deviceId: string;
-        label: string;
-    } | null;
+    microphone: MediaDeviceOption | null;
     profile: Omit<LipSyncProfile, 'samples'> | null;
     calibration: LipSyncCalibrationState | null;
 }

package/dist/values/locale.d.ts

@@ -2,7 +2,8 @@ export type Locale = keyof typeof LOCALE_LABELS;
 /** `ui.language` setting: an explicit locale, or follow the OS language. */
 export type LanguageSetting = 'system' | Locale;
 /** `ui.theme` setting: an explicit appearance, or follow the OS. */
-export type ThemeSetting = 'system' | 'light' | 'dark';
+export declare const THEME_SETTINGS: readonly ["system", "light", "dark"];
+export type ThemeSetting = (typeof THEME_SETTINGS)[number];
 /** Native-language display names for the language picker (deliberately untranslated). */
 export declare const LOCALE_LABELS: {
     en: string;
@@ -12,5 +13,7 @@ export declare const LOCALE_LABELS: {
 };
 /** Locales shipped in the compiled catalogs (`pnpm i18n`). */
 export declare const LOCALES: readonly Locale[];
+/** Every `ui.language` value, `system` first. */
+export declare const LANGUAGE_SETTINGS: readonly LanguageSetting[];
 /** 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

@@ -1,4 +1,6 @@
 import { isOneOf, keysOf } from "./guards.js";
+/** `ui.theme` setting: an explicit appearance, or follow the OS. */
+export const THEME_SETTINGS = ['system', 'light', 'dark'];
 /** Native-language display names for the language picker (deliberately untranslated). */
 export const LOCALE_LABELS = {
     en: 'English',
@@ -8,6 +10,8 @@ export const LOCALE_LABELS = {
 };
 /** Locales shipped in the compiled catalogs (`pnpm i18n`). */
 export const LOCALES = keysOf(LOCALE_LABELS);
+/** Every `ui.language` value, `system` first. */
+export const LANGUAGE_SETTINGS = ['system', ...LOCALES];
 /** Best supported locale for a BCP 47-ish tag: exact match first, then fuzzy per language. */
 export function matchLocaleTag(tag) {
     if (isOneOf(tag, LOCALES))

package/dist/values/model-movement.d.ts

@@ -1,3 +1,11 @@
+import type { AttachAnchor } from '../wire/types.ts';
+/**
+ * The point `z` grows and shrinks the model around: its centre (`root`), or a point on one of its
+ * ArtMeshes, taken where that mesh sits in the model's rest pose so head motion never moves it.
+ */
+export type ModelMovementPivot = Extract<AttachAnchor, {
+    kind: 'root' | 'artMesh';
+}>;
 /**
  * VTube Studio's Movement Config: how far tracked face position slides (`x`, `y`) and scales (`z`)
  * a whole Live2D model. It moves the model itself and never writes a parameter, so it stacks with
@@ -9,21 +17,28 @@ export interface ModelMovementConfig {
     x: number;
     y: number;
     z: number;
+    /** Persona-only: VTS has no such setting, so it lives in the sidecar even beside a `.vtube.json`. */
+    pivot: ModelMovementPivot;
     /** Smoothing levels 0–100, read once when the model loads; file-only, as in VTS. */
     smoothingX: number;
     smoothingY: number;
     smoothingZ: number;
 }
-/** VTS's slider limit (`MAX_MOVEMENT`): an edited amount is a whole number within ±20. */
-export declare const MODEL_MOVEMENT_MAX = 20;
+/** The per-axis smoothing levels, read once when the model loads and never edited. */
+export type ModelMovementSmoothing = Pick<ModelMovementConfig, 'smoothingX' | 'smoothingY' | 'smoothingZ'>;
+/**
+ * The editor's limit: an edited amount is a whole number within ±50. VTS's own sliders stop at ±20
+ * (`MAX_MOVEMENT`), and releasing one there writes all three axes back clamped to that.
+ */
+export declare const MODEL_MOVEMENT_MAX = 50;
 /** VTS's `ModelPositionMovement` field initializers — a model nobody configured moves by default. */
 export declare const DEFAULT_MODEL_MOVEMENT: Readonly<ModelMovementConfig>;
 /**
  * A stored or relayed configuration, read per field over the defaults. Amounts are taken as
- * written: VTS clamps its sliders to ±20, never what a file holds.
+ * written: the editors clamp what they write, never what a file holds.
  */
 export declare function healModelMovement(raw: unknown): ModelMovementConfig;
 /** What the Movement Config editor changes; a file's smoothing levels are left as they are. */
-export type ModelMovementEdit = Partial<Pick<ModelMovementConfig, 'enabled' | 'x' | 'y' | 'z'>>;
+export type ModelMovementEdit = Partial<Pick<ModelMovementConfig, 'enabled' | 'x' | 'y' | 'z' | 'pivot'>>;
 /** An edit healed to the editor's limits; an absent or unusable field is dropped, not defaulted. */
 export declare function healModelMovementEdit(raw: unknown): ModelMovementEdit;

package/dist/values/model-movement.js

@@ -1,20 +1,29 @@
 import { finiteOr, isFiniteNumber, isRecord } from "./guards.js";
-import { clamp } from "./limits.js";
-/** VTS's slider limit (`MAX_MOVEMENT`): an edited amount is a whole number within ±20. */
-export const MODEL_MOVEMENT_MAX = 20;
+import { clamp, healAttachAnchor } from "./limits.js";
+/**
+ * The editor's limit: an edited amount is a whole number within ±50. VTS's own sliders stop at ±20
+ * (`MAX_MOVEMENT`), and releasing one there writes all three axes back clamped to that.
+ */
+export const MODEL_MOVEMENT_MAX = 50;
 /** VTS's `ModelPositionMovement` field initializers — a model nobody configured moves by default. */
 export const DEFAULT_MODEL_MOVEMENT = {
     enabled: true,
     x: 6,
     y: 8,
     z: 11,
+    pivot: { kind: 'root' },
     smoothingX: 10,
     smoothingY: 10,
     smoothingZ: 10,
 };
+/** A stored or relayed pivot as a usable one: any anchor but a bone, which no Live2D model has. */
+function healPivot(raw) {
+    const anchor = healAttachAnchor(raw);
+    return anchor?.kind === 'bone' ? null : anchor;
+}
 /**
  * A stored or relayed configuration, read per field over the defaults. Amounts are taken as
- * written: VTS clamps its sliders to ±20, never what a file holds.
+ * written: the editors clamp what they write, never what a file holds.
  */
 export function healModelMovement(raw) {
     const r = isRecord(raw) ? raw : {};
@@ -24,6 +33,7 @@ export function healModelMovement(raw) {
         x: finiteOr(r.x, d.x),
         y: finiteOr(r.y, d.y),
         z: finiteOr(r.z, d.z),
+        pivot: healPivot(r.pivot) ?? d.pivot,
         smoothingX: finiteOr(r.smoothingX, d.smoothingX),
         smoothingY: finiteOr(r.smoothingY, d.smoothingY),
         smoothingZ: finiteOr(r.smoothingZ, d.smoothingZ),
@@ -40,5 +50,8 @@ export function healModelMovementEdit(raw) {
         if (isFiniteNumber(v))
             edit[axis] = clamp(Math.round(v), -MODEL_MOVEMENT_MAX, MODEL_MOVEMENT_MAX);
     }
+    const pivot = healPivot(r.pivot);
+    if (pivot)
+        edit.pivot = pivot;
     return edit;
 }

package/dist/values/volumetric-lighting.d.ts

@@ -1,4 +1,4 @@
-import { type SceneEnvironment, type SceneVolumetricLighting } from '../wire/types.ts';
+import type { SceneEnvironment, SceneVolumetricLighting } from '../wire/types.ts';
 /** Slider and healing metadata for the haze's numeric settings. */
 export declare const SCENE_VOLUMETRIC_LIGHTING_SPECS: {
     readonly density: {

package/dist/values/volumetric-lighting.js

@@ -1,4 +1,4 @@
-import { EFFECTS_QUALITY_LEVELS } from "../wire/types.js";
+import { EFFECTS_QUALITY_LEVELS } from "./effect-schema.js";
 import { finiteOr, isOneOf, isRecord } from "./guards.js";
 import { clamp } from "./limits.js";
 /** Slider and healing metadata for the haze's numeric settings. */

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;