@laplace.live/persona-sdk 0.18.1 → 1.1.0

package/dist/wire/types.d.ts

@@ -1,4 +1,9 @@
+import type { ControllerConfig } from '../values/controller.ts';
+import type { EFFECT_SCOPES } from '../values/effect-schema.ts';
 import { type ArkitInputName } from '../values/arkit.ts';
+import { type BaseControllerInputName, type ControllerInputName, type ControllerMovementConfig } from '../values/controller.ts';
+import { type HandInputName } from '../values/hands.ts';
+import { type LipSyncConfig, type LipSyncMode, type VoiceInputName } from '../values/lipsync.ts';
 export type ModelFormat = 'live2d' | 'vrm';
 /** Where an item came from: shipped with the app, or added by the user. */
 export type ContentOrigin = 'bundled' | 'user';
@@ -44,6 +49,8 @@ export interface AssetRef extends ContentRef {
     /** What the extension makes it — an object created from it starts on this kind. */
     kind: AssetKind;
     exists: boolean;
+    /** Source basename, with no directory. Absent on older hosts. */
+    file?: string;
 }
 /**
  * Content metadata decoupled from any on-disk file — local registry entries and
@@ -135,13 +142,25 @@ export interface SceneModelItem {
     instanceId: string;
     ref: ModelRef;
     visible: boolean;
+    /** Independent effects on this source, before scene effects; WebGPU only. */
+    effects: LayerEffects;
+    /** Added layer effects, including disabled rows whose tuning is retained. */
+    effectLayers: LayerEffectKey[];
     /**
      * Face source tracking this instance ({@link TrackingSourceConfig.id}); null = its face is untracked.
      * A dangling or disabled id behaves as null. One source may track several instances (mirroring).
      */
     faceSourceId: string | null;
-    /** Body source (vmc) tracking this instance; null = its pose is untracked. New instances bind to each channel's default source. */
+    /** Body source tracking this instance; null = its pose is untracked. New instances bind to each channel's default source. */
     poseSourceId: string | null;
+    /** Hand source tracking this instance; null leaves hands untracked. */
+    handSourceId: string | null;
+    /** Track wrists and arms, or only fingers while the body source owns the arms. */
+    handTrackingMode: HandTrackingMode;
+    /** Whether microphone lipsync drives this model, independently of the face source assignment. */
+    lipSyncMode: LipSyncMode;
+    /** Opt-in controller movement, independent of parameter/bone bindings; disabled by default. */
+    controllerMovement: ControllerMovementConfig;
     live2d: ScreenPlacement;
     vrm: VrmPlacement;
     idleAnimation: boolean;
@@ -188,6 +207,8 @@ export type ObjectContent = {
     css: string;
     /** 2D only: composited behind or in front of the whole stage, not interleaved with other layers. */
     layer: WebLayer;
+    /** Close the page while the object is hidden and reload it on show, as an OBS browser source can. */
+    shutdownWhenHidden: boolean;
 } | {
     kind: 'capture';
     source: CaptureKind;
@@ -249,6 +270,10 @@ export interface SceneObjectItem {
     instanceId: string;
     name: string;
     visible: boolean;
+    /** Independent effects on this source, before scene effects; WebGPU only. */
+    effects: LayerEffects;
+    /** Added layer effects, including disabled rows whose tuning is retained. */
+    effectLayers: LayerEffectKey[];
     space: ObjectSpace;
     content: ObjectContent;
     place2d: Place2D;
@@ -271,9 +296,6 @@ export interface SceneBackground {
     color: string;
     imageAssetId: string | null;
 }
-export interface SceneBehavior {
-    lookAtCursor: boolean;
-}
 /** VRM stage framing: the camera moves, the model does not. Angles in radians, distance in world units. */
 export interface OrbitTransform {
     azimuth: number;
@@ -333,28 +355,35 @@ export interface SceneFog {
 }
 /** Display transform applied after the scene renders. `none` keeps colors exactly as authored. */
 export type SceneToneMapping = 'none' | 'neutral' | 'aces' | 'agx';
-/**
- * Glow around bright pixels, with anamorphic streak flares on the side
- * (VTube Studio's Beautify-based bloom). `threshold` is the luminance floor;
- * `radius` widens the halo.
- */
+/** Highlight glow in normal, streak, or star mode; color selection applies only to layer effects. */
 export interface SceneBloom {
     enabled: boolean;
+    mode: 'normal' | 'streak' | 'star';
+    /** UI offset: the glow's brightness multiplier is 1 + intensity. */
     intensity: number;
     threshold: number;
+    thresholdSmooth: number;
     radius: number;
-    /** Halo tint (hex); white is untinted. */
+    saturation: number;
+    /** Glow color (hex); white is untinted. */
     tint: string;
-    /** Anamorphic streak strength; 0 keeps the streak passes out of the graph. */
-    streak: number;
-    /** Luminance floor for the streak's own bright pass. */
-    streakThreshold: number;
-    /** Streak axis in degrees: 0 horizontal, ±90 vertical (VTS's vertical toggle, continuous). */
-    streakAngle: number;
-    /** Streak tint (hex); classic anamorphic flares are light blue. */
-    streakTint: string;
-    /** Darkens the avatar under the glow so highlights pop (VTS's model darken), 0..1. */
-    darken: number;
+    opacity: number;
+    starRays: number;
+    starAngle: number;
+    selectColors: boolean;
+    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
@@ -388,6 +417,116 @@ export interface SceneColorGrade {
     /** White balance along green↔magenta, −100..100 — the axis `temperature` leaves alone. */
     tint: number;
 }
+/** Master and per-channel input/output levels; RGB channels run before master levels. */
+export interface EffectLevels {
+    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;
+}
+/** Color wheels in lift/gamma/gain or shadows/midtones/highlights mode. */
+export interface EffectColorWheels {
+    enabled: boolean;
+    mode: 'liftGammaGain' | 'shadowsMidtonesHighlights';
+    lift: number;
+    liftColor: string;
+    gamma: number;
+    gammaColor: string;
+    gain: number;
+    gainColor: string;
+    shadows: number;
+    shadowsColor: string;
+    midtones: number;
+    midtonesColor: string;
+    highlights: number;
+    highlightsColor: string;
+    shadowLimit: number;
+    highlightLimit: number;
+}
+/** Six hue bands; hue offsets are degrees, other offsets are -1..1. */
+export interface EffectColorShift {
+    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 {
+    enabled: boolean;
+    invert: boolean;
+    /** Hue distance in turns around the color wheel. */
+    hueRange: number;
+    saturationRange: number;
+    brightnessRange: number;
+    /** 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;
+}
+/** Gaussian or disk-shaped bokeh blur in output pixels. */
+export interface EffectBlur {
+    enabled: boolean;
+    radius: number;
+    mode: 'gaussian' | 'bokeh';
+    highQuality: boolean;
+}
 /** Lens fringing that grows toward frame edges (Unity PPv2's curve, the one VTube Studio wraps). */
 export interface SceneChromaticAberration {
     enabled: boolean;
@@ -468,55 +607,33 @@ export interface SceneDroplets {
     /** Specular glint on drops where the frame is transparent, so rain reads over the desktop (0 to 1). */
     glints: number;
 }
-/**
- * Screen-space rim light along the avatar silhouette (Shoost's layer rim light,
- * VTube Studio's backlight): coverage edges facing `angle` catch the glow.
- * Silhouette-driven — an opaque skybox leaves no edges to light.
- */
+/** Blend modes shared with Shoost's rim light. */
+export type EffectBlendMode = 'normal' | 'darken' | 'multiply' | 'colorBurn' | 'linearBurn' | 'add' | 'lighten' | 'screen' | 'colorDodge' | 'overlay' | 'softLight' | 'hardLight' | 'vividLight' | 'linearLight' | 'pinLight' | 'hardMix' | 'difference' | 'exclusion' | 'subtract' | 'divide' | 'hue' | 'saturation' | 'color' | 'luminosity';
+/** Directional silhouette lighting, optionally sharpened or applied to both sides. */
 export interface SceneRim {
     enabled: boolean;
+    mode: 'single' | 'double' | 'sharpenSingle' | 'sharpenDouble';
+    blendMode: EffectBlendMode;
     /** Rim tint (hex). */
     color: string;
-    /** Glow strength; past 1 overdrives into bloom territory. */
-    intensity: number;
-    /** Rim width in output pixels. */
+    /** Normalized rim width, 0..1. */
     size: number;
-    /** Edge falloff: 0 a crisp line, 1 a wide soft fade. */
-    softness: number;
-    /** Light direction in degrees, compass-style: 0 lights from above, 90 from the right. */
+    brightness: number;
+    contrast: number;
+    /** Light direction in degrees, -180..180. */
     angle: number;
-    /** How much the edge opposite the light glows too (0 to 1). */
-    bothSides: number;
-    /** Uniform glow on every edge regardless of `angle` (VTS's main backlight strength), 0..1. */
-    omni: number;
-    /** Ceiling the glow lightens pixels toward: 1 screens to white, lower protects highlights. */
-    brightnessLimit: number;
-    /** Darkens the avatar under the glow for contrast (VTS's model darken), 0..1. */
-    darken: number;
+    opacity: number;
 }
-/**
- * Contour band hugging the avatar silhouette, with an optional animated stripe
- * pattern scrolling through it (VTube Studio's backlight outline). Silhouette-
- * driven like the rim light — it needs coverage edges to trace.
- */
+/** Solid silhouette border with selectable edge sampling quality. */
 export interface SceneOutline {
     enabled: boolean;
+    quality: 'low' | 'medium' | 'high';
     /** Outline color (hex). */
     color: string;
-    /** Stripe color (hex), painted over `color` where the stripe pattern lands. */
-    stripeColor: string;
-    /** Band thickness in output pixels. */
+    /** Normalized border thickness, 0..1. */
     size: number;
     /** Outline opacity 0..1. */
     opacity: number;
-    /** Stripe density: 0 broad bands, 1 fine candy stripes. */
-    stripes: number;
-    /** Stripe visibility: 0 a solid outline, 1 full-strength stripes. */
-    stripeMix: number;
-    /** Stripe scroll speed; negative reverses the direction. */
-    stripeSpeed: number;
-    /** Bends the stripes into waves: 0 straight, 1 strongly curled. */
-    stripeCurve: number;
 }
 /**
  * Hard-edged copy of the avatar silhouette cast behind it (VTube Studio's
@@ -532,6 +649,8 @@ export interface SceneDropShadow {
     offsetX: number;
     /** Vertical offset, percent of frame height; positive casts down. */
     offsetY: number;
+    /** Gaussian shadow softness in output pixels; 0 keeps a hard edge. */
+    size: number;
 }
 /** Compute-driven 3D rainfall: motion-blur streaks fall through the scene and splash on models, props, and the floor. */
 export interface SceneRain {
@@ -569,23 +688,19 @@ export interface SceneSnow {
     /** Flake opacity. */
     opacity: number;
 }
-/**
- * Post-processing over the rendered 3D frame. Everything off skips the effect
- * chain entirely. Deliberately flat: every toggle-plus-numbers effect sits at
- * the top level so tooling (defaults, healing, editors) can walk the effect
- * registry generically. Grouping is a panel concern, not a data one.
- */
-export interface SceneEffects {
-    toneMapping: SceneToneMapping;
-    /** Scene brightness multiplied in before the tone curve; 1 is neutral. Works in every mode, including `none`. */
-    exposure: number;
+/** Toggle effects independent of the scene or layer that owns their values. */
+export interface EffectValues {
     bloom: SceneBloom;
     diffusion: SceneDiffusion;
     vignette: SceneVignette;
     color: SceneColorGrade;
+    levels: EffectLevels;
+    colorWheels: EffectColorWheels;
+    colorShift: EffectColorShift;
+    selectColors: EffectSelectColors;
+    blur: EffectBlur;
     chromaticAberration: SceneChromaticAberration;
     grain: SceneFilmGrain;
-    lut: SceneLut;
     dof: SceneDepthOfField;
     rim: SceneRim;
     outline: SceneOutline;
@@ -596,30 +711,29 @@ export interface SceneEffects {
     rain: SceneRain;
     snow: SceneSnow;
 }
-/** Keys of {@link SceneEffects} that follow the `{ enabled } + params` pattern. */
-export type ToggleEffectKey = {
-    [K in keyof SceneEffects]: SceneEffects[K] extends {
-        enabled: boolean;
-    } ? K : never;
-}[keyof SceneEffects];
-/**
- * One user-authored effect's placement in a scene. Deliberately a sibling of
- * {@link SceneEffects} rather than a key inside it: `ToggleEffectKey` is derived
- * from that interface, and healing, defaults, hotkey snapshots and the panel all
- * iterate it as a closed compile-time union. Runtime keys in there would erase
- * that guarantee for the built-in effects too.
- */
-export interface SceneCustomEffect {
-    /** Folder name under the config home's `effects/` dir — stable id and module location. */
-    slug: string;
-    enabled: boolean;
-    /**
-     * Author-declared values, keyed by the manifest's param names. Untyped by
-     * construction: the specs arrive from disk at runtime, so these are validated
-     * against the installed manifest rather than checked at compile time.
-     */
-    params: Record<string, number | boolean | string>;
+export type EffectKey = keyof EffectValues;
+export type EffectScope = 'scene' | 'layer';
+/** Effect availability comes from the catalog, independently for each scope. */
+export type EffectKeyForScope<S extends EffectScope> = {
+    [K in EffectKey]: S extends (typeof EFFECT_SCOPES)[K][number] ? K : never;
+}[EffectKey];
+export type SceneEffectKey = EffectKeyForScope<'scene'>;
+/** Scene toggle keys; retained for existing SDK consumers. */
+export type ToggleEffectKey = SceneEffectKey;
+/** Scene-wide toggles plus the display transform and color lookup table. */
+export interface SceneEffects extends Pick<EffectValues, SceneEffectKey> {
+    toneMapping: SceneToneMapping;
+    /** Scene brightness multiplied in before the tone curve; 1 is neutral. Works in every mode, including `none`. */
+    exposure: number;
+    lut: SceneLut;
 }
+/** Source-local effects, evaluated before the source joins the scene composition. */
+export type LayerEffectKey = EffectKeyForScope<'layer'>;
+export type LayerEffects = Pick<EffectValues, LayerEffectKey>;
+/** Omitted effects and parameters retain their current values. */
+export type LayerEffectsPatch = {
+    [K in LayerEffectKey]?: Partial<LayerEffects[K]>;
+};
 /**
  * A 3D set's own suggested look — the fog and post settings it was authored against,
  * read from its root `LAPLACE_environment` extension and held on the scene for every client.
@@ -681,14 +795,6 @@ export interface SceneEnvironment {
      * switched off. Healing lists every switched-on effect, so a patch that switches one on adds its layer.
      */
     effectLayers: ToggleEffectKey[];
-    /**
-     * User-authored effects, in the order they compose. They run as a group at one
-     * fixed point in the post chain — after grading and the screen-space warps,
-     * before grain and vignette — so the built-in composition order stays fixed.
-     * An entry whose effect is not installed here is kept, not dropped: it would
-     * cost the user their tuning on a machine that simply lacks the folder.
-     */
-    customEffects: SceneCustomEffect[];
 }
 export interface Scene {
     id: string;
@@ -698,7 +804,6 @@ export interface Scene {
     /** Hotkey target and the default instance for model-scoped methods. null only when `items` holds no model. */
     primaryInstanceId: string | null;
     background: SceneBackground;
-    behavior: SceneBehavior;
     vrmCamera: SceneCamera;
     /** Array order is display order only; live lights are keyed by id. */
     lights: SceneLight[];
@@ -719,7 +824,6 @@ export interface SceneState {
  */
 export interface ScenePatch {
     background?: SceneBackground;
-    behavior?: SceneBehavior;
     vrmCamera?: SceneCamera;
     lights?: SceneLight[];
     environment?: SceneEnvironment;
@@ -728,11 +832,13 @@ 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}.
  */
-export declare const APP_CAPABILITIES: readonly ["storage", "speech", "shortcuts"];
+export declare const APP_CAPABILITIES: readonly ["storage", "speech", "shortcuts", "controllers", "model-editing", "asset-inspection", "layer-effects"];
 export type AppCapability = (typeof APP_CAPABILITIES)[number];
 export declare function isAppCapability(v: unknown): v is AppCapability;
 /** What a loaded model instance can do; absent capabilities answer `unsupported-for-format`. */
 export type InstanceCapability = 'motions' | 'expressions' | 'placement-2d' | 'placement-3d' | 'mtoon' | 'idle-clips' | 'pose' | 'live2d-params'
+/** `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; engine-dependent, so gate on the runtime, not the format. */
@@ -752,6 +858,8 @@ export interface InstanceRuntime {
     capabilities: InstanceCapability[];
 }
 export interface MotionGroup {
+    /** Whether this group loops; absent on older hosts. */
+    looping?: boolean;
     group: string;
     files: string[];
 }
@@ -776,20 +884,7 @@ export interface AnchorOption {
     anchor: AttachAnchor;
     label: string;
 }
-/**
- * Panel-style model info block. Format-specific fields mirror the app's `ModelInfo`.
- * `format` stays the union's discriminant here — this is a runtime diagnostic, not
- * content metadata, so it does not follow {@link ContentRef}'s `kind`.
- */
-export interface ModelInfo {
-    format: ModelFormat;
-    name: string;
-    origin: ContentOrigin;
-    file: string;
-    loadMs: number;
-    /** Format-specific details (canvas/params/textures for Live2D, spec/bones for VRM). */
-    [key: string]: unknown;
-}
+export type { ModelInfo } from '../values/model-info.ts';
 export interface Hotkey {
     id: string;
     name: string;
@@ -836,17 +931,38 @@ export interface ExpressionPersistence {
 export type JsonValue = string | number | boolean | null | JsonValue[] | {
     [key: string]: JsonValue;
 };
-export declare const TRACKING_SOURCE_IDS: readonly ["vts-ios", "ifacialmocap"];
+export declare const TRACKING_SOURCE_IDS: readonly ["persona-ios", "ifacialmocap", "vts-ios"];
 export type TrackingSourceId = (typeof TRACKING_SOURCE_IDS)[number];
 /** Body-pose protocols. Every one so far is UDP with a configurable port. */
-export declare const POSE_SOURCE_IDS: readonly ["vmc"];
+export declare const POSE_SOURCE_IDS: readonly ["vmc", "mocopi"];
 export type PoseSourceId = (typeof POSE_SOURCE_IDS)[number];
 export type TrackingStatus = 'off' | 'waiting' | 'tracking' | 'no-face';
 export type PoseStatus = 'off' | 'waiting' | 'tracking';
-/** Every protocol a tracking source instance can speak; face kinds plus the body (vmc) kind. */
-export declare const TRACKING_SOURCE_KINDS: readonly ["vts-ios", "ifacialmocap", "vmc"];
+/** Every protocol a tracking source instance can speak; face and body kinds. */
+export declare const TRACKING_SOURCE_KINDS: readonly ["persona-ios", "ifacialmocap", "vts-ios", "vmc", "mocopi", "mediapipe"];
 export type TrackingSourceKind = (typeof TRACKING_SOURCE_KINDS)[number];
-/** Whether a source kind feeds the face channel (vmc is the body channel). */
+export declare const TRACKING_CHANNELS: readonly ["face", "pose", "hands"];
+export type TrackingChannel = (typeof TRACKING_CHANNELS)[number];
+/** The scene-item binding each channel reads and writes. */
+export declare const TRACKING_CHANNEL_FIELDS: {
+    readonly face: "faceSourceId";
+    readonly pose: "poseSourceId";
+    readonly hands: "handSourceId";
+};
+export declare const HAND_TRACKING_MODES: readonly ["arms", "fingers"];
+export type HandTrackingMode = (typeof HAND_TRACKING_MODES)[number];
+export declare function isHandTrackingMode(v: unknown): v is HandTrackingMode;
+/** The shared webcam source's enabled inference tasks and camera configuration. */
+export interface MediaPipeConfig {
+    deviceId: string;
+    mirror: boolean;
+    face: boolean;
+    hands: boolean;
+    body: boolean;
+    delegate: 'CPU' | 'GPU';
+}
+export declare const DEFAULT_MEDIAPIPE_CONFIG: Readonly<MediaPipeConfig>;
+/** Whether a source kind uses a network face receiver. */
 export declare function isFaceSourceKind(kind: TrackingSourceKind): kind is TrackingSourceId;
 /**
  * One configured tracking source instance. Several can run at once — one per person —
@@ -860,12 +976,40 @@ export interface TrackingSourceConfig {
     enabled: boolean;
     /**
      * Face kinds: accept only this device/sender IP; null accepts any sender not claimed
-     * by a pinned instance of the same kind. Ignored by vmc (its senders pick the port).
+     * by a pinned instance of the same kind. Ignored by body sources (their senders pick the port).
      */
     phoneIp: string | null;
-    /** vmc only: the UDP port this instance listens on. Null on face kinds — they bind per protocol. */
+    /**
+     * The UDP port this instance listens on: vmc, mocopi, and ifacialmocap (its receive port — the phone's
+     * Send Port must match). Null on persona-ios and vts-ios, whose ports the protocol fixes.
+     */
     port: number | null;
+    /** Present only on the shared webcam source. */
+    mediapipe?: MediaPipeConfig;
+}
+/** Whether a source uses a network body receiver. */
+export declare function isPoseSource(source: TrackingSourceConfig): source is TrackingSourceConfig & {
+    kind: PoseSourceId;
+};
+/** The channels a kind can supply; the webcam's are further gated by its task switches. */
+export declare function sourceKindChannels(kind: TrackingSourceKind): readonly TrackingChannel[];
+/** Whether this source can supply a channel; {@link sourceChannelEnabled} folds in the switches. */
+export declare function sourceSupportsChannel(source: TrackingSourceConfig, channel: TrackingChannel): boolean;
+/** The face and body master switches; they gate network sources only. */
+export interface ChannelMasters {
+    face: boolean;
+    pose: boolean;
 }
+/**
+ * Whether a source feeds a channel right now: its own switch, its task, and — for a network
+ * face or body source — the channel master. Webcam tasks and hands answer to the source switch alone.
+ */
+export declare function sourceChannelEnabled(source: TrackingSourceConfig, channel: TrackingChannel, masters: ChannelMasters): boolean;
+/**
+ * Whether another source already holds `port` and would contend for it. iFacialMocap instances
+ * 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 type EffectsQuality = (typeof EFFECTS_QUALITY_LEVELS)[number];
 /**
@@ -873,11 +1017,22 @@ export type EffectsQuality = (typeof EFFECTS_QUALITY_LEVELS)[number];
  * to the nearest preset by the app, so a picker offering other values would lie.
  */
 export declare const FPS_LIMIT_PRESETS: readonly [0, 15, 30, 60, 90];
+/** A stage window content size in device-independent px — what the desktop's window bounds report. */
+export interface StageSize {
+    width: number;
+    height: number;
+}
 /** The curated settings surface the API exposes — never the raw store shape. */
 export interface Settings {
+    /** Absent on hosts without microphone lipsync. */
+    lipSync?: LipSyncConfig;
+    /** Absent on hosts without remote controller management. */
+    controller?: ControllerConfig;
     /** `alwaysOnTop` floats the control-panel window, never the stage. */
     window: {
         alwaysOnTop: boolean;
+        /** Read-only; absent on older desktops. */
+        stageSize?: StageSize;
     };
     ui: {
         trayVisible: boolean;
@@ -887,14 +1042,17 @@ export interface Settings {
         fpsLimit: number;
         selectionOutline: boolean;
         effectsQuality: EffectsQuality;
+        /** Absent on older hosts. */
+        renderScale?: number;
+        live2dEngine?: 'pixi' | 'three';
     };
-    /** `source` mirrors the first face source's kind — the pre-multi-source field, kept for old clients. */
+    /** `enabled` gates network face sources; `source` mirrors the first one's kind for old clients. */
     tracking: {
         enabled: boolean;
         source: TrackingSourceId;
         sources: TrackingSourceConfig[];
     };
-    /** `source`/`port` mirror the first vmc source — the pre-multi-source fields, kept for old clients. */
+    /** `enabled` gates network body sources; `source`/`port` mirror the first one's values for old clients. */
     pose: {
         enabled: boolean;
         source: PoseSourceId;
@@ -902,6 +1060,8 @@ export interface Settings {
     };
 }
 export interface SettingsPatch {
+    lipSync?: Partial<LipSyncConfig>;
+    controller?: Partial<Pick<ControllerConfig, 'enabled'>>;
     window?: {
         alwaysOnTop?: boolean;
     };
@@ -913,17 +1073,19 @@ export interface SettingsPatch {
         fpsLimit?: number;
         selectionOutline?: boolean;
         effectsQuality?: EffectsQuality;
+        renderScale?: number;
+        live2dEngine?: 'pixi' | 'three';
     };
 }
 /** VTS's input vocabulary, plus `JawOpen` — the derived half of {@link INPUT_NAMES}. */
 declare const VTS_INPUT_NAMES: readonly ["FaceAngleX", "FaceAngleY", "FaceAngleZ", "FacePositionX", "FacePositionY", "FacePositionZ", "EyeOpenLeft", "EyeOpenRight", "EyeLeftX", "EyeLeftY", "EyeRightX", "EyeRightY", "Brows", "BrowLeftY", "BrowRightY", "MouthSmile", "MouthOpen", "MouthX", "CheekPuff", "JawOpen", "TongueOut"];
 type VtsInputName = (typeof VTS_INPUT_NAMES)[number];
 /**
- * The valid `id`s for `input` inject targets, and the names a model's `.vtube.json`
- * references: VTS's derived vocabulary plus every raw ARKit channel.
+ * Default input vocabulary: face and hand inputs, raw ARKit channels and controller profile 1.
+ * Additional controller profile ids are accepted by isInputName without appearing in this list.
  */
-export declare const INPUT_NAMES: readonly InputName[];
-export type InputName = VtsInputName | ArkitInputName;
+export declare const INPUT_NAMES: readonly (VtsInputName | HandInputName | VoiceInputName | ArkitInputName | BaseControllerInputName)[];
+export type InputName = VtsInputName | HandInputName | VoiceInputName | ArkitInputName | ControllerInputName;
 /** Whether an untrusted string names a tracking input — the guard every wire boundary needs. */
 export declare function isInputName(v: string): v is InputName;
 /**
@@ -948,10 +1110,12 @@ export declare const BINDING_INPUT_NAMES: readonly BindingInput[];
 /** The id an input is read as: its ARKit twin when it has one, else itself. */
 export declare function arkitTwinOf(input: InputName): BindingInput;
 /**
- * Each input's natural span — the units a sender should write, and the input range a new
- * binding starts from. Head angles are **degrees**; the rest are unitless.
+ * Default inputs' natural spans. Use getInputRange for a dynamically numbered controller input.
+ * Head angles are degrees; the rest are unitless.
  */
-export declare const INPUT_RANGES: Record<InputName, readonly [number, number]>;
+export declare const INPUT_RANGES: Record<VtsInputName | HandInputName | VoiceInputName | ArkitInputName | BaseControllerInputName, readonly [number, number]>;
+/** Natural span of any valid input, including dynamically numbered controller profiles. */
+export declare function getInputRange(name: InputName): readonly [number, number];
 /**
  * What an injected value drives:
  * - `input` — a VTS-vocabulary tracking input (`MouthOpen`, `FaceAngleX`, …), mapped
@@ -972,4 +1136,3 @@ export interface InjectEntry extends InjectTarget {
     /** 0..1 blend over whatever else drives the parameter; default 1. */
     weight?: number;
 }
-export {};