@laplace.live/persona-sdk 1.24.0 → 1.25.0

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

package/dist/wire/types.js

@@ -8,6 +8,8 @@ import { HAND_INPUT_NAMES, HAND_INPUT_RANGES } from "../values/hands.js";
 import { VOICE_INPUT_NAMES, VOICE_INPUT_RANGES } from "../values/lipsync.js";
 import { MOUSE_INPUT_NAMES, MOUSE_INPUT_RANGES } from "../values/mouse.js";
 import { TIME_INPUT_NAMES, TIME_INPUT_RANGES } from "../values/time.js";
+export const MODEL_FORMATS = ['live2d', 'vrm'];
+export const CONTENT_ORIGINS = ['bundled', 'user'];
 /**
  * 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
@@ -30,18 +32,22 @@ export function isAssetKind(v) {
 }
 // ---- Objects -------------------------------------------------------------------
 export const OBJECT_SPACES = ['2d', '3d'];
+export const CAPTURE_KINDS = ['display', 'window'];
 export const TEXT_ALIGNS = ['left', 'center', 'right', 'justify'];
 /** `baseline` is the first line's baseline — Blender's Top Base-Line. */
 export const TEXT_VERTICAL_ALIGNS = ['top', 'middle', 'baseline', 'bottom'];
 /** Blender's text-box overflow: spill past the box, shrink to fit it, or drop the lines that don't fit. */
 export const TEXT_OVERFLOWS = ['overflow', 'scale', 'truncate'];
 export const TEXT_STROKE_JOINS = ['round', 'miter', 'bevel'];
+// ---- Scene sections ------------------------------------------------------------
+export const BACKGROUND_MODES = ['transparent', 'color', 'image'];
 /**
  * How a following camera turns with its anchor — Warudo's Transposer binding modes. `world` follows
  * position only; `yaw`, `yaw-pitch` and `full` also turn with it (Lock To Target With World Up, No Roll,
  * and Lock To Target); `lazy` trails it, turning only as it passes (Simple Follow With World Up).
  */
 export const CAMERA_FOLLOW_BINDINGS = ['world', 'yaw', 'yaw-pitch', 'full', 'lazy'];
+export const CAMERA_PROJECTIONS = ['perspective', 'orthographic'];
 export const SCENE_LIGHT_TYPES = ['directional', 'point', 'ambient', 'area', 'spot'];
 /**
  * Per-light shadow tier. `off` is the old `castShadow: false`; the rest raise
@@ -50,10 +56,13 @@ export const SCENE_LIGHT_TYPES = ['directional', 'point', 'ambient', 'area', 'sp
  */
 export const SHADOW_QUALITY_LEVELS = ['off', 'low', 'medium', 'high', 'ultra'];
 export const SHADOW_FILTERS = ['pcf', 'pcss'];
+/** Display transform applied after the scene renders. `none` keeps colors exactly as authored. */
+export const SCENE_TONE_MAPPINGS = ['none', 'neutral', 'aces', 'agx'];
 // ---- 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}.
+ * Each name leads with what it extends (`light-spot`, `object-text`), as action kinds do.
  */
 export const APP_CAPABILITIES = [
     'storage',
@@ -64,14 +73,14 @@ export const APP_CAPABILITIES = [
     'asset-inspection',
     'layer-effects',
     'scene-transitions',
-    'area-lights',
-    'spot-lights',
-    'camera-follow-lights',
-    'shadow-filters',
+    'light-area',
+    'light-spot',
+    'light-camera-follow',
+    'light-shadow-filter',
     'environment-map-model',
-    'spawn',
+    'stage-spawn',
     /** `instance.setIdle` takes `trackingLostBehavior`, `trackingLostMotion` and `trackingLostDelay`. */
-    'tracking-lost',
+    'idle-tracking-lost',
     /** `motion.stop`; `motion.playing` and `motion.started` carry `oneShot`. */
     'motion-stop',
     /** `stage.capture`. */
@@ -84,7 +93,7 @@ export const APP_CAPABILITIES = [
      */
     'object-pin-depth',
     /** `text` object content and `fonts.list`. */
-    'text-objects',
+    'object-text',
     /** `SceneCamera.follow`. */
     'camera-follow',
     /** `SceneCamera.aim`. */
@@ -94,13 +103,63 @@ export const APP_CAPABILITIES = [
     /** `SceneCamera.handheld`. */
     'camera-handheld',
     /** `object.setContent` edits a video's `loop`, `muted` and `volume` in place; its sound follows the output device. */
-    'video-sound',
+    'object-video-sound',
     /** Image, video and webpage content takes `chromaKey`, which `object.setContent` edits in place. */
     'object-chroma-key',
+    /** `ModelMovementConfig.pivot`, which `model.setMovement` edits. */
+    'model-movement-pivot',
+    /** `instance.setEffects` takes objects in `2d` space too; older hosts answer `unsupported-for-format`. */
+    'layer-effects-2d',
 ];
 export function isAppCapability(v) {
     return isOneOf(v, APP_CAPABILITIES);
 }
+/**
+ * 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.
+ */
+export const LEGACY_APP_CAPABILITIES = new Map([
+    ['area-lights', 'light-area'],
+    ['spot-lights', 'light-spot'],
+    ['camera-follow-lights', 'light-camera-follow'],
+    ['shadow-filters', 'light-shadow-filter'],
+    ['spawn', 'stage-spawn'],
+    ['tracking-lost', 'idle-tracking-lost'],
+    ['text-objects', 'object-text'],
+    ['video-sound', 'object-video-sound'],
+]);
+/** The current name of an app capability; names that were never renamed, known or not, pass through. */
+export function canonicalAppCapability(name) {
+    return LEGACY_APP_CAPABILITIES.get(name) ?? name;
+}
+/** What a loaded model instance can do; absent capabilities answer `unsupported-for-format`. */
+export const INSTANCE_CAPABILITIES = [
+    '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.
+     */
+    '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',
+];
 // ---- App automations --------------------------------------------------------------
 /** Action kinds an app automation can carry today; servers may send kinds newer than this list. */
 export const AUTOMATION_ACTION_KINDS = [
@@ -220,7 +279,7 @@ export function sourceChannelEnabled(source, channel, masters) {
 export function trackingPortTaken(sources, kind, port, excludeId) {
     return sources.some(s => s.id !== excludeId && s.port === port && !(s.kind === 'ifacialmocap' && kind === 'ifacialmocap'));
 }
-export const EFFECTS_QUALITY_LEVELS = ['low', 'medium', 'high'];
+export { EFFECTS_QUALITY_LEVELS } from "../values/effect-schema.js";
 /**
  * Accepted values for `performance.fpsLimit`; 0 = unlimited. Anything else is snapped
  * to the nearest preset by the app, so a picker offering other values would lie.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@laplace.live/persona-sdk",
-  "version": "1.24.0",
+  "version": "1.25.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": "^5.0.2"
+    "vitest": "^5.0.3"
   },
   "engines": {
     "node": ">=24"

package/dist/client/legacy-kinds.d.ts

@@ -1,2 +0,0 @@
-/** A method result or event payload with the action kinds an older host still sends renamed to current ones. */
-export declare function renameLegacyKinds(name: string, data: unknown): unknown;