@laplace.live/persona-sdk 1.24.0 → 1.25.1

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({

package/dist/wire/types.d.ts

@@ -1,5 +1,5 @@
 import type * as z from 'zod';
-import type { EFFECT_BLEND_MODES, EFFECT_SCOPES } from '../values/effect-schema.ts';
+import type { BLOOM_MODES, BLUR_MODES, BloomColorSlot, COLOR_SHIFT_BANDS, COLOR_WHEELS_MODES, EFFECT_BLEND_MODES, EFFECT_SCOPES, EFFECTS_QUALITY_LEVELS, FLARE_MODES, FLARE_RAYS_MODES, GRADIENT_TYPES, LEVEL_CHANNELS, RIM_MODES, SelectColorsSlot } from '../values/effect-schema.ts';
 import type { ItemTransition } from '../values/item-transition.ts';
 import type { SCENE_TRANSITION_TYPES } from '../values/scene-transition.ts';
 import type { SettingsPatchSchema, SettingsSchema } from './schemas/settings.ts';
@@ -9,9 +9,11 @@ import { type HandInputName } from '../values/hands.ts';
 import { type LipSyncMode, type VoiceInputName } from '../values/lipsync.ts';
 import { type MouseInputName } from '../values/mouse.ts';
 import { type TimeInputName } from '../values/time.ts';
-export type ModelFormat = 'live2d' | 'vrm';
+export declare const MODEL_FORMATS: readonly ["live2d", "vrm"];
+export type ModelFormat = (typeof MODEL_FORMATS)[number];
+export declare const CONTENT_ORIGINS: readonly ["bundled", "user"];
 /** Where an item came from: shipped with the app, or added by the user. */
-export type ContentOrigin = 'bundled' | 'user';
+export type ContentOrigin = (typeof CONTENT_ORIGINS)[number];
 /**
  * How a registered file is labelled. Wider than an object's content kinds: `.hdr` is only
  * ever an environment map, and a `.vmd` splits by content — `cameraMotion` for one that
@@ -55,6 +57,8 @@ export interface ModelRef extends ContentRef {
      * without one. Only `model.list` fills it: absent on scene item refs, `model.register`'s answer, and older hosts.
      */
     vtubeFile?: string | null;
+    /** False once the entry file is gone from disk, like {@link AssetRef.exists}; filled like {@link ModelRef.vtubeFile}. */
+    exists?: boolean;
 }
 /** A registered object-source file. `exists` is false once the file is gone from disk. */
 export interface AssetRef extends ContentRef {
@@ -215,7 +219,8 @@ export interface SceneModelItem {
 }
 export declare const OBJECT_SPACES: readonly ["2d", "3d"];
 export type ObjectSpace = (typeof OBJECT_SPACES)[number];
-export type CaptureKind = 'display' | 'window';
+export declare const CAPTURE_KINDS: readonly ["display", "window"];
+export type CaptureKind = (typeof CAPTURE_KINDS)[number];
 export declare const TEXT_ALIGNS: readonly ["left", "center", "right", "justify"];
 export type TextAlign = (typeof TEXT_ALIGNS)[number];
 /** `baseline` is the first line's baseline — Blender's Top Base-Line. */
@@ -487,7 +492,8 @@ export interface SceneObjectItem {
 }
 /** Anything the stage renders. Array order in {@link Scene.items} is z-order within each space. */
 export type SceneItem = SceneModelItem | SceneObjectItem;
-export type BackgroundMode = 'transparent' | 'color' | 'image';
+export declare const BACKGROUND_MODES: readonly ["transparent", "color", "image"];
+export type BackgroundMode = (typeof BACKGROUND_MODES)[number];
 /** `imageAssetId` names a registered asset; an id this app cannot resolve renders transparent. */
 export interface SceneBackground {
     mode: BackgroundMode;
@@ -607,6 +613,8 @@ export interface SceneCameraHandheld {
     /** 0–2; 1 sways at the authored pace. */
     speed: number;
 }
+export declare const CAMERA_PROJECTIONS: readonly ["perspective", "orthographic"];
+export type CameraProjection = (typeof CAMERA_PROJECTIONS)[number];
 /** Scene-level VRM camera. `orbit: null` = never framed — the first VRM load frames it from model height. */
 export interface SceneCamera {
     orbit: OrbitTransform | null;
@@ -615,7 +623,7 @@ export interface SceneCamera {
     /** Rotation about camera-local +Z in radians; absent on older hosts, default 0. */
     roll?: number;
     /** Absent on older hosts; defaults to perspective. */
-    projection?: 'perspective' | 'orthographic';
+    projection?: CameraProjection;
     /**
      * A `cameraMotion` asset driving the camera, or null for the user's own orbit. While one
      * is set it overrides the framing every frame without writing it back.
@@ -678,7 +686,7 @@ export interface SceneLight {
     type: SceneLightType;
     /** Mutes illumination and shadows. Defaults to true; omitted by hosts without light toggles. */
     enabled?: boolean;
-    /** Camera-relative placement and angles; defaults to false. Gate editing on `camera-follow-lights`; ambient ignores it. */
+    /** Camera-relative placement and angles; defaults to false. Gate editing on `light-camera-follow`; ambient ignores it. */
     followCamera?: boolean;
     /** Independent camera components; omitted means all true. */
     followCameraOptions?: SceneLightCameraFollowOptions;
@@ -710,7 +718,7 @@ export interface SceneLight {
     shadowQuality: ShadowQuality;
     /** PCF disk radius in shadow-map texels; retained while PCSS is selected. */
     shadowRadius: number;
-    /** Per-light filter; defaults to PCF. Gate editing on the `shadow-filters` app capability. */
+    /** Per-light filter; defaults to PCF. Gate editing on the `light-shadow-filter` app capability. */
     shadowFilter?: ShadowFilter;
     /** PCSS source diameter: degrees for directional lights, metres for point/spot; 0–10, default 0.1. */
     shadowSourceSize?: number;
@@ -735,11 +743,15 @@ export interface SceneVolumetricLighting {
     speed: number;
 }
 /** Display transform applied after the scene renders. `none` keeps colors exactly as authored. */
-export type SceneToneMapping = 'none' | 'neutral' | 'aces' | 'agx';
+export declare const SCENE_TONE_MAPPINGS: readonly ["none", "neutral", "aces", "agx"];
+export type SceneToneMapping = (typeof SCENE_TONE_MAPPINGS)[number];
+export type BloomMode = (typeof BLOOM_MODES)[number];
+/** An effect's color slots, `color1` up, each with its `Enabled` switch. */
+type ColorSlots<Slot extends number> = Record<`color${Slot}`, string> & Record<`color${Slot}Enabled`, boolean>;
 /** Highlight glow in normal, streak, or star mode; color selection applies only to layer effects. */
-export interface SceneBloom {
+export interface SceneBloom extends ColorSlots<BloomColorSlot> {
     enabled: boolean;
-    mode: 'normal' | 'streak' | 'star';
+    mode: BloomMode;
     /** The glow's brightness multiplier, as Warudo's; 0 adds no glow. */
     intensity: number;
     /** Gamma-space brightness a channel must pass; squared into linear light, as Warudo's. */
@@ -756,16 +768,6 @@ export interface SceneBloom {
     invertColors: boolean;
     /** Shared saturation/brightness tolerance; hue tolerance is fixed at 0.03. */
     colorTolerance: number;
-    color1: string;
-    color2: string;
-    color3: string;
-    color4: string;
-    color5: string;
-    color1Enabled: boolean;
-    color2Enabled: boolean;
-    color3Enabled: boolean;
-    color4Enabled: boolean;
-    color5Enabled: boolean;
 }
 /**
  * Cinematic soft-focus veil (Shoost's diffusion, a Kino bloom variant): the
@@ -799,34 +801,19 @@ export interface SceneColorGrade {
     /** White balance along green↔magenta, −100..100 — the axis `temperature` leaves alone. */
     tint: number;
 }
+/** A Levels color channel, suffixing its copy of every {@link LevelParam}. */
+export type LevelChannel = (typeof LEVEL_CHANNELS)[number];
+/** One channel's levels; the master set carries no suffix. */
+export type LevelParam = 'inputBlack' | 'inputWhite' | 'inputGamma' | 'outputBlack' | 'outputWhite';
 /** Master and per-channel input/output levels; RGB channels run before master levels. */
-export interface EffectLevels {
+export interface EffectLevels extends Record<`${LevelParam}${'' | LevelChannel}`, number> {
     enabled: boolean;
-    inputBlack: number;
-    inputWhite: number;
-    inputGamma: number;
-    outputBlack: number;
-    outputWhite: number;
-    inputBlackR: number;
-    inputWhiteR: number;
-    inputGammaR: number;
-    outputBlackR: number;
-    outputWhiteR: number;
-    inputBlackG: number;
-    inputWhiteG: number;
-    inputGammaG: number;
-    outputBlackG: number;
-    outputWhiteG: number;
-    inputBlackB: number;
-    inputWhiteB: number;
-    inputGammaB: number;
-    outputBlackB: number;
-    outputWhiteB: number;
 }
+export type ColorWheelsMode = (typeof COLOR_WHEELS_MODES)[number];
 /** Color wheels in lift/gamma/gain or shadows/midtones/highlights mode. */
 export interface EffectColorWheels {
     enabled: boolean;
-    mode: 'liftGammaGain' | 'shadowsMidtonesHighlights';
+    mode: ColorWheelsMode;
     lift: number;
     liftColor: string;
     gamma: number;
@@ -842,36 +829,16 @@ export interface EffectColorWheels {
     shadowLimit: number;
     highlightLimit: number;
 }
-/** Six hue bands; hue offsets are degrees, other offsets are -1..1. */
-export interface EffectColorShift {
+/** A Color Shift hue band, suffixing its copy of every {@link ColorShiftParam}. */
+export type ColorShiftBand = (typeof COLOR_SHIFT_BANDS)[number];
+/** One hue band's offsets. */
+export type ColorShiftParam = 'hue' | 'saturation' | 'luminance' | 'luminanceSaturation';
+/** Per-band offsets; hue offsets are degrees, other offsets are -1..1. */
+export interface EffectColorShift extends Record<`${ColorShiftParam}${ColorShiftBand}`, number> {
     enabled: boolean;
-    hueRed: number;
-    saturationRed: number;
-    luminanceRed: number;
-    luminanceSaturationRed: number;
-    hueYellow: number;
-    saturationYellow: number;
-    luminanceYellow: number;
-    luminanceSaturationYellow: number;
-    hueGreen: number;
-    saturationGreen: number;
-    luminanceGreen: number;
-    luminanceSaturationGreen: number;
-    hueCyan: number;
-    saturationCyan: number;
-    luminanceCyan: number;
-    luminanceSaturationCyan: number;
-    hueBlue: number;
-    saturationBlue: number;
-    luminanceBlue: number;
-    luminanceSaturationBlue: number;
-    hueMagenta: number;
-    saturationMagenta: number;
-    luminanceMagenta: number;
-    luminanceSaturationMagenta: number;
 }
 /** Preserve selected colors while adjusting saturation outside their HSV ranges. */
-export interface EffectSelectColors {
+export interface EffectSelectColors extends ColorSlots<SelectColorsSlot> {
     enabled: boolean;
     invert: boolean;
     /** Hue distance in turns around the color wheel. */
@@ -881,32 +848,13 @@ export interface EffectSelectColors {
     /** Saturation offset outside the selection; -1 makes it monochrome. */
     saturation: number;
     blend: number;
-    color1: string;
-    color1Enabled: boolean;
-    color2: string;
-    color2Enabled: boolean;
-    color3: string;
-    color3Enabled: boolean;
-    color4: string;
-    color4Enabled: boolean;
-    color5: string;
-    color5Enabled: boolean;
-    color6: string;
-    color6Enabled: boolean;
-    color7: string;
-    color7Enabled: boolean;
-    color8: string;
-    color8Enabled: boolean;
-    color9: string;
-    color9Enabled: boolean;
-    color10: string;
-    color10Enabled: boolean;
 }
+export type BlurMode = (typeof BLUR_MODES)[number];
 /** Gaussian or disk-shaped bokeh blur in output pixels. */
 export interface EffectBlur {
     enabled: boolean;
     radius: number;
-    mode: 'gaussian' | 'bokeh';
+    mode: BlurMode;
     highQuality: boolean;
 }
 /**
@@ -1013,10 +961,11 @@ export interface SceneDroplets {
 }
 /** Shoost's blend modes, as Gradient offers them. */
 export type EffectBlendMode = (typeof EFFECT_BLEND_MODES)[number];
+export type GradientType = (typeof GRADIENT_TYPES)[number];
 /** Solid, linear, or radial color overlay in scene or source coordinates. */
 export interface EffectGradient {
     enabled: boolean;
-    type: 'solid' | 'linear' | 'circle' | 'ellipse';
+    type: GradientType;
     blendMode: EffectBlendMode;
     /** Foreground color (hex). */
     color: string;
@@ -1036,10 +985,12 @@ export interface EffectGradient {
     scaleY: number;
     opacity: number;
 }
+export type FlareMode = (typeof FLARE_MODES)[number];
+export type FlareRaysMode = (typeof FLARE_RAYS_MODES)[number];
 /** Directional screen-space light with an independent monitor glow. */
 export interface SceneFlare {
     enabled: boolean;
-    mode: 'add' | 'screen' | 'colorDodge';
+    mode: FlareMode;
     /** Light color (hex). */
     color: string;
     intensity: number;
@@ -1048,17 +999,18 @@ export interface SceneFlare {
     angle: number;
     glowOpacity: number;
     rays: boolean;
-    raysMode: 'sun' | 'shine' | 'god';
+    raysMode: FlareRaysMode;
     /** Particle-ray color (hex). */
     raysColor: string;
     raysScale: number;
     raysIntensity: number;
     raysOpacity: number;
 }
+export type RimMode = (typeof RIM_MODES)[number];
 /** Directional silhouette light, added like VTube Studio's backlight; optionally sharpened or two-sided. */
 export interface SceneRim {
     enabled: boolean;
-    mode: 'single' | 'double' | 'sharpenSingle' | 'sharpenDouble';
+    mode: RimMode;
     /** Rim tint (hex). */
     color: string;
     /** Normalized rim width, 0..1. */
@@ -1072,7 +1024,7 @@ export interface SceneRim {
 /** Solid silhouette border; quality sets how closely it follows fine detail. */
 export interface SceneOutline {
     enabled: boolean;
-    quality: 'low' | 'medium' | 'high';
+    quality: EffectsQuality;
     /** Outline color (hex). */
     color: string;
     /** Normalized border thickness, 0..1. */
@@ -1312,29 +1264,21 @@ export interface ScenePatch {
 /**
  * App-level features a client gates on (never version-sniff): `hello` and
  * `app.info` report them — the per-app mirror of {@link InstanceRuntime.capabilities}.
+ * Each name leads with what it extends (`light-spot`, `object-text`), as action kinds do.
  */
-export declare const APP_CAPABILITIES: readonly ["storage", "speech", "automations", "controllers", "model-editing", "asset-inspection", "layer-effects", "scene-transitions", "area-lights", "spot-lights", "camera-follow-lights", "shadow-filters", "environment-map-model", "spawn", "tracking-lost", "motion-stop", "stage-capture", "model-movement", "object-pin-depth", "text-objects", "camera-follow", "camera-aim", "camera-focus", "camera-handheld", "video-sound", "object-chroma-key"];
+export declare const APP_CAPABILITIES: readonly ["storage", "speech", "automations", "controllers", "model-editing", "asset-inspection", "layer-effects", "scene-transitions", "light-area", "light-spot", "light-camera-follow", "light-shadow-filter", "environment-map-model", "stage-spawn", "idle-tracking-lost", "motion-stop", "stage-capture", "model-movement", "object-pin-depth", "object-text", "camera-follow", "camera-aim", "camera-focus", "camera-handheld", "object-video-sound", "object-chroma-key", "model-movement-pivot", "layer-effects-2d"];
 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'
-/** `instance.setIdle` with `idleMotion`: one of the model's motions loops as its idle. Live2D only. */
- | 'idle-motions' | 'pose' | 'live2d-params'
-/** `instance.setBreath`; the idle breathing loop is Cubism's, so VRM lacks it. */
- | 'breath'
-/** `expression.setWeight`; Cubism expressions carry no user-settable weight, so Live2D lacks it. */
- | 'expression-weights'
 /**
- * `speech.play` lip-sync. Loaded Live2D models only; 0.53 and earlier hosts also omit it under
- * the Pixi engine, so gate on the runtime, not the format.
+ * Old app capability names, each mapped to its category-first replacement. Hosts still list them for
+ * clients from before the rename; the SDK client folds them into the new names on receipt.
  */
- | 'speech'
-/**
- * Draws through the 3D post chain, so the scene's look rows (tone mapping, exposure, LUT)
- * reach it. Every model; 0.53 and earlier hosts omit it on Pixi-engine Live2D, so read it off
- * the runtime rather than the format.
- */
- | 'post-fx';
+export declare const LEGACY_APP_CAPABILITIES: ReadonlyMap<string, AppCapability>;
+/** The current name of an app capability; names that were never renamed, known or not, pass through. */
+export declare function canonicalAppCapability(name: string): string;
+/** What a loaded model instance can do; absent capabilities answer `unsupported-for-format`. */
+export declare const INSTANCE_CAPABILITIES: readonly ["motions", "expressions", "placement-2d", "placement-3d", "mtoon", "idle-clips", "idle-motions", "pose", "live2d-params", "breath", "expression-weights", "speech", "post-fx"];
+export type InstanceCapability = (typeof INSTANCE_CAPABILITIES)[number];
 export interface InstanceRuntime {
     instanceId: string;
     kind: 'model' | 'object';
@@ -1378,14 +1322,20 @@ export interface AnchorOption {
 }
 export type { ModelInfo } from '../values/model-info.ts';
 export interface Hotkey {
+    /** VTS `HotkeyID`: 32 lowercase hex chars when Persona mints it. */
     id: string;
     name: string;
     /** The VTS `Action` string verbatim; `action` is null when Persona cannot run it. */
     vtsAction: string;
+    /** Derived from `vtsAction`; `hotkey.set` ignores the value a client sends. */
     action: 'expression-toggle' | 'motion-play' | 'expression-clear' | 'model-load' | null;
+    /** A `hotkeyTargets` file, or the model's for model-load (see `modelMatchesFile`); empty for expression-clear. */
     file: string;
+    /** Keyboard accelerator or `Controller*` combo; null when the stored triggers are unsupported. */
     accelerator: string | null;
+    /** VTS `IsGlobal`: the user's intent, independent of whether registration succeeded. */
     global: boolean;
+    /** VTS `IsActive`; an inactive hotkey never fires. */
     active: boolean;
     /** Expression: on only while the combo is held down (VTS `DeactivateAfterKeyUp`). Default false. */
     hold?: boolean;
@@ -1397,6 +1347,7 @@ export interface Hotkey {
     stopsOnLastFrame?: boolean;
 }
 export interface HotkeyConfig {
+    /** The model's master switch (VTS `HotkeySettings.UseKeyboardHotkeys`). */
     keyboardEnabled: boolean;
     hotkeys: Hotkey[];
 }
@@ -1469,6 +1420,8 @@ export declare const TRACKING_CHANNEL_FIELDS: {
     readonly hands: "handSourceId";
 };
 export declare const TRACKING_CHANNELS: readonly TrackingChannel[];
+/** A model item's source binding for each channel, the fields {@link TRACKING_CHANNEL_FIELDS} names. */
+export type ChannelBindings = Pick<SceneModelItem, (typeof TRACKING_CHANNEL_FIELDS)[TrackingChannel]>;
 export declare const HAND_TRACKING_MODES: readonly ["arms", "fingers"];
 /** How the face drivers react to a dropout; see `SceneModelInstance.trackingLostBehavior`. */
 export declare const TRACKING_LOST_BEHAVIORS: readonly ["hold", "idle"];
@@ -1534,7 +1487,7 @@ export declare function sourceChannelEnabled(source: TrackingSourceConfig, chann
  * share one socket per port (frames demux by phone); every other pairing EADDRINUSEs a listener.
  */
 export declare function trackingPortTaken(sources: readonly TrackingSourceConfig[], kind: TrackingSourceKind, port: number, excludeId?: string): boolean;
-export declare const EFFECTS_QUALITY_LEVELS: readonly ["low", "medium", "high"];
+export { EFFECTS_QUALITY_LEVELS } from '../values/effect-schema.ts';
 export type EffectsQuality = (typeof EFFECTS_QUALITY_LEVELS)[number];
 /**
  * Accepted values for `performance.fpsLimit`; 0 = unlimited. Anything else is snapped