@laplace.live/persona-sdk 1.0.0 → 1.2.0

package/README.md

@@ -20,7 +20,9 @@ await persona.connect();
 // Typed request/response
 const { scenes, activeSceneId } = await persona.call("scene.list");
 await persona.call("expression.toggle", { name: "Smile" });
-await persona.call("scene.patch", { behavior: { lookAtCursor: true } });
+await persona.call("scene.patch", {
+  background: { mode: "color", color: "#112233", imageAssetId: null },
+});
 
 // Events (subscriptions survive reconnects)
 persona.on("motion.started", (m) => console.log("playing", m.group));

package/dist/index.d.ts

@@ -8,9 +8,11 @@ export * from './values/edit-history.ts';
 export * from './values/effect-schema.ts';
 export * from './values/gltf-extensions.ts';
 export * from './values/guards.ts';
+export * from './values/hands.ts';
 export * from './values/hotkeys.ts';
 export * from './values/labels.ts';
 export * from './values/limits.ts';
+export * from './values/lipsync.ts';
 export * from './values/locale.ts';
 export * from './values/model-info.ts';
 export * from './values/stage-info.ts';

package/dist/index.js

@@ -10,9 +10,11 @@ export * from "./values/edit-history.js";
 export * from "./values/effect-schema.js";
 export * from "./values/gltf-extensions.js";
 export * from "./values/guards.js";
+export * from "./values/hands.js";
 export * from "./values/hotkeys.js";
 export * from "./values/labels.js";
 export * from "./values/limits.js";
+export * from "./values/lipsync.js";
 export * from "./values/locale.js";
 export * from "./values/model-info.js";
 export * from "./values/stage-info.js";

package/dist/values/effect-schema.d.ts

@@ -1,4 +1,38 @@
-import type { SceneEffects, ToggleEffectKey } from '../wire/types.ts';
+import type { EffectKey, EffectKeyForScope, EffectScope, EffectValues, LayerEffectKey, LayerEffects, SceneEffectKey } from '../wire/types.ts';
+/** Supported owners of each toggle effect; scene and layer membership are independent. */
+export declare const EFFECT_SCOPES: {
+    readonly color: readonly ["scene", "layer"];
+    readonly levels: readonly ["scene", "layer"];
+    readonly colorWheels: readonly ["scene", "layer"];
+    readonly colorShift: readonly ["scene", "layer"];
+    readonly selectColors: readonly ["scene", "layer"];
+    readonly blur: readonly ["scene", "layer"];
+    readonly bloom: readonly ["scene", "layer"];
+    readonly diffusion: readonly ["scene", "layer"];
+    readonly dof: readonly ["scene"];
+    readonly chromaticAberration: readonly ["scene"];
+    readonly grain: readonly ["scene"];
+    readonly vignette: readonly ["scene"];
+    readonly rim: readonly ["scene", "layer"];
+    readonly outline: readonly ["scene", "layer"];
+    readonly dropShadow: readonly ["scene", "layer"];
+    readonly pixelate: readonly ["scene"];
+    readonly glitch: readonly ["scene"];
+    readonly droplets: readonly ["scene"];
+    readonly rain: readonly ["scene"];
+    readonly snow: readonly ["scene"];
+};
+export declare const EFFECT_KEYS: readonly EffectKey[];
+/** Older hosts advertise effect availability through the values present in their payload. */
+export declare function availableEffectKeys<S extends EffectScope>(scope: S, effects: Partial<Record<EffectKey, unknown>>): EffectKeyForScope<S>[];
+/** Preserve the option shape advertised by the host when resetting or applying settings. */
+export declare function supportedEffectParams<T extends object>(current: T, patch: Partial<T>): Partial<T>;
+/** Named modes distinguish the newer rim/outline size and bloom intensity units from older hosts. */
+export declare function hasCurrentEffectFormat(effect: EffectKey, value: object): boolean;
+export declare const SCENE_EFFECT_KEYS: readonly EffectKeyForScope<"scene">[];
+/** Scene toggle keys; retained for existing SDK consumers. */
+export declare const TOGGLE_EFFECT_KEYS: readonly EffectKeyForScope<"scene">[];
+export declare const LAYER_EFFECT_KEYS: readonly EffectKeyForScope<"layer">[];
 /** Slider + healing metadata for one numeric effect parameter. */
 export interface EffectParamSpec {
     default: number;
@@ -14,28 +48,54 @@ export interface EffectParamSpec {
 export interface EffectColorSpec {
     default: string;
 }
-export declare const EFFECT_SPECS: Record<ToggleEffectKey, Readonly<Record<string, EffectParamSpec>>>;
+/** Boolean effect parameters other than the common enabled switch. */
+export interface EffectBooleanSpec {
+    default: boolean;
+}
+/** Named choices; values are protocol strings and labels belong to the UI. */
+export interface EffectEnumSpec<T extends string = string> {
+    default: T;
+    values: readonly T[];
+}
+export declare const EFFECT_SPECS: Record<EffectKey, Readonly<Record<string, EffectParamSpec>>>;
 /**
  * Hex-color params, keyed like {@link EFFECT_SPECS} — generic walkers (healing,
  * defaults, hotkey snapshots, the panel) visit both tables. Only effects with a
  * string param appear.
  */
-export declare const EFFECT_COLOR_SPECS: Partial<Record<ToggleEffectKey, Readonly<Record<string, EffectColorSpec>>>>;
-export declare const TOGGLE_EFFECT_KEYS: readonly ToggleEffectKey[];
+export declare const EFFECT_COLOR_SPECS: Partial<Record<EffectKey, Readonly<Record<string, EffectColorSpec>>>>;
+/** Boolean defaults, validated alongside numeric and color parameters. */
+export declare const EFFECT_BOOLEAN_SPECS: Partial<Record<EffectKey, Readonly<Record<string, EffectBooleanSpec>>>>;
+/** Enum defaults and allowed values. */
+export declare const EFFECT_ENUM_SPECS: Partial<Record<EffectKey, Readonly<Record<string, EffectEnumSpec>>>>;
+/** Select the layer effects from any value set containing them. */
+export declare function pickLayerEffects<T extends LayerEffects>(effects: T): LayerEffects;
+/** The canonical per-item effect list, preserving disabled rows and including every enabled effect. */
+export declare function layerEffectKeys(listed: readonly unknown[], effects: LayerEffects): LayerEffectKey[];
+/** An independent, disabled set for a fresh source layer. */
+export declare function defaultLayerEffects(): LayerEffects;
+/** Whether a source needs its own effect pass. */
+export declare function layerEffectsActive(effects: LayerEffects): boolean;
 /**
  * Registry effects that render as scene geometry inside the scene pass rather
  * than composing into the post chain. A new scene-space effect must join this
  * list, or its toggle needlessly forces the post path on and rebuilds the graph.
  */
-export declare const SCENE_SPACE_EFFECT_KEYS: readonly ToggleEffectKey[];
+export declare const SCENE_SPACE_EFFECT_KEYS: readonly SceneEffectKey[];
 /** Registry effects the post chain composes — {@link TOGGLE_EFFECT_KEYS} minus the scene-space ones. */
-export declare const POST_EFFECT_KEYS: readonly ToggleEffectKey[];
-/** The canonical `effectLayers`: registry order, junk dropped, every switched-on effect included. */
-export declare function effectLayerKeys(listed: readonly unknown[], effects: Pick<SceneEffects, ToggleEffectKey>): ToggleEffectKey[];
+export declare const POST_EFFECT_KEYS: readonly SceneEffectKey[];
+/** The canonical scene `effectLayers`. */
+export declare function effectLayerKeys(listed: readonly unknown[], effects: Pick<EffectValues, SceneEffectKey>): SceneEffectKey[];
 /**
  * Composition order, bottom to top.
  * Display-only: the desktop chain's `rebuild()` is the order that runs — a stage moved there moves here too.
  */
-export declare const EFFECT_STACK_ORDER: readonly ToggleEffectKey[];
-/** Every registry effect at its defaults — the derived half of a fresh {@link SceneEffects}. */
-export declare function defaultToggleEffects(): Pick<SceneEffects, ToggleEffectKey>;
+export declare const ALL_EFFECT_STACK_ORDER: readonly EffectKey[];
+/** Scene composition order, retained under its existing SDK name. */
+export declare const EFFECT_STACK_ORDER: readonly SceneEffectKey[];
+/** Layer composition order before the result joins the scene. */
+export declare const LAYER_EFFECT_STACK_ORDER: readonly LayerEffectKey[];
+/** Heal only the requested effect keys, using the same parameter kinds as defaults and editors. */
+export declare function healEffectValues<K extends EffectKey>(raw: unknown, keys: readonly K[]): Pick<EffectValues, K>;
+/** Scene toggle defaults, independent of effects offered only on layers. */
+export declare function defaultToggleEffects(): Pick<EffectValues, SceneEffectKey>;

package/dist/values/effect-schema.js

@@ -1,18 +1,50 @@
-// The scene-effect registry: one spec per toggle-plus-numeric-params effect.
-// Defaults, healing clamps, active checks, structural keys, and the panel's
-// sliders are all derived from this table, so adding an effect is:
-//   1. Type its values in `SceneEffects` (types.ts) + its interface.
-//   2. Spec it here (hex-color params go in EFFECT_COLOR_SPECS); label it in
-//      the panel's effect-labels.ts (parity-checked).
-//   3. Implement its stage under apps/desktop/src/renderer/vrm/webgpu/effects/.
-//      Scene-space effects (geometry, not a post stage — e.g. snow) also join
-//      SCENE_SPACE_EFFECT_KEYS below.
-//   4. Drop one `<EffectSection>` line into a panel section.
-// Effects that don't fit the pattern (tone mapping, exposure, LUT, shockwave)
-// stay bespoke — extend the pattern before special-casing a third shape.
-//
-// Plain data only — no React, no lingui (labels live in the panel's
-// effect-labels.ts) — so main-process healing and API plugins import it freely.
+// Scope and parameter metadata are plain data; labels and rendering stay with their consumers.
+import { finiteOr, isRecord } from "./guards.js";
+import { clamp, hexColorOr } from "./limits.js";
+/** Supported owners of each toggle effect; scene and layer membership are independent. */
+export const EFFECT_SCOPES = {
+    color: ['scene', 'layer'],
+    levels: ['scene', 'layer'],
+    colorWheels: ['scene', 'layer'],
+    colorShift: ['scene', 'layer'],
+    selectColors: ['scene', 'layer'],
+    blur: ['scene', 'layer'],
+    bloom: ['scene', 'layer'],
+    diffusion: ['scene', 'layer'],
+    dof: ['scene'],
+    chromaticAberration: ['scene'],
+    grain: ['scene'],
+    vignette: ['scene'],
+    rim: ['scene', 'layer'],
+    outline: ['scene', 'layer'],
+    dropShadow: ['scene', 'layer'],
+    pixelate: ['scene'],
+    glitch: ['scene'],
+    droplets: ['scene'],
+    rain: ['scene'],
+    snow: ['scene'],
+};
+export const EFFECT_KEYS = Object.keys(EFFECT_SCOPES);
+function keysForScope(scope) {
+    return EFFECT_KEYS.filter((key) => EFFECT_SCOPES[key].includes(scope));
+}
+/** Older hosts advertise effect availability through the values present in their payload. */
+export function availableEffectKeys(scope, effects) {
+    return keysForScope(scope).filter(key => effects[key] !== undefined);
+}
+/** Preserve the option shape advertised by the host when resetting or applying settings. */
+export function supportedEffectParams(current, patch) {
+    return Object.fromEntries(Object.entries(patch).filter(([key]) => Object.hasOwn(current, key)));
+}
+/** Named modes distinguish the newer rim/outline size and bloom intensity units from older hosts. */
+export function hasCurrentEffectFormat(effect, value) {
+    const field = effect === 'outline' ? 'quality' : effect === 'rim' || effect === 'bloom' ? 'mode' : null;
+    return field === null || Object.hasOwn(value, field);
+}
+export const SCENE_EFFECT_KEYS = keysForScope('scene');
+/** Scene toggle keys; retained for existing SDK consumers. */
+export const TOGGLE_EFFECT_KEYS = SCENE_EFFECT_KEYS;
+export const LAYER_EFFECT_KEYS = keysForScope('layer');
 // Declared string-indexed so generic call sites (slider loop, healing walk) iterate
 // without erasure casts; `satisfies` still checks exact per-effect param parity here.
 export const EFFECT_SPECS = {
@@ -25,18 +57,84 @@ export const EFFECT_SPECS = {
         temperature: { default: 0, min: -100, max: 100, step: 1 },
         tint: { default: 0, min: -100, max: 100, step: 1 },
     },
+    levels: {
+        inputBlack: { default: 0, min: 0, max: 1, step: 0.01 },
+        inputWhite: { default: 1, min: 0, max: 1, step: 0.01 },
+        inputGamma: { default: 1, min: 0.1, max: 4, step: 0.01 },
+        outputBlack: { default: 0, min: 0, max: 1, step: 0.01 },
+        outputWhite: { default: 1, min: 0, max: 1, step: 0.01 },
+        inputBlackR: { default: 0, min: 0, max: 1, step: 0.01 },
+        inputWhiteR: { default: 1, min: 0, max: 1, step: 0.01 },
+        inputGammaR: { default: 1, min: 0.1, max: 4, step: 0.01 },
+        outputBlackR: { default: 0, min: 0, max: 1, step: 0.01 },
+        outputWhiteR: { default: 1, min: 0, max: 1, step: 0.01 },
+        inputBlackG: { default: 0, min: 0, max: 1, step: 0.01 },
+        inputWhiteG: { default: 1, min: 0, max: 1, step: 0.01 },
+        inputGammaG: { default: 1, min: 0.1, max: 4, step: 0.01 },
+        outputBlackG: { default: 0, min: 0, max: 1, step: 0.01 },
+        outputWhiteG: { default: 1, min: 0, max: 1, step: 0.01 },
+        inputBlackB: { default: 0, min: 0, max: 1, step: 0.01 },
+        inputWhiteB: { default: 1, min: 0, max: 1, step: 0.01 },
+        inputGammaB: { default: 1, min: 0.1, max: 4, step: 0.01 },
+        outputBlackB: { default: 0, min: 0, max: 1, step: 0.01 },
+        outputWhiteB: { default: 1, min: 0, max: 1, step: 0.01 },
+    },
+    colorWheels: {
+        lift: { default: 0, min: -1, max: 1, step: 0.01 },
+        gamma: { default: 0, min: -1, max: 1, step: 0.01 },
+        gain: { default: 0, min: -1, max: 1, step: 0.01 },
+        shadows: { default: 0, min: -1, max: 1, step: 0.01 },
+        midtones: { default: 0, min: -1, max: 1, step: 0.01 },
+        highlights: { default: 0, min: -1, max: 1, step: 0.01 },
+        shadowLimit: { default: 0.3, min: 0, max: 1, step: 0.01 },
+        highlightLimit: { default: 0.7, min: 0, max: 1, step: 0.01 },
+    },
+    colorShift: {
+        hueRed: { default: 0, min: -180, max: 180, step: 1, unit: '°' },
+        saturationRed: { default: 0, min: -1, max: 1, step: 0.01 },
+        luminanceRed: { default: 0, min: -1, max: 1, step: 0.01 },
+        luminanceSaturationRed: { default: 0, min: -1, max: 1, step: 0.01 },
+        hueYellow: { default: 0, min: -180, max: 180, step: 1, unit: '°' },
+        saturationYellow: { default: 0, min: -1, max: 1, step: 0.01 },
+        luminanceYellow: { default: 0, min: -1, max: 1, step: 0.01 },
+        luminanceSaturationYellow: { default: 0, min: -1, max: 1, step: 0.01 },
+        hueGreen: { default: 0, min: -180, max: 180, step: 1, unit: '°' },
+        saturationGreen: { default: 0, min: -1, max: 1, step: 0.01 },
+        luminanceGreen: { default: 0, min: -1, max: 1, step: 0.01 },
+        luminanceSaturationGreen: { default: 0, min: -1, max: 1, step: 0.01 },
+        hueCyan: { default: 0, min: -180, max: 180, step: 1, unit: '°' },
+        saturationCyan: { default: 0, min: -1, max: 1, step: 0.01 },
+        luminanceCyan: { default: 0, min: -1, max: 1, step: 0.01 },
+        luminanceSaturationCyan: { default: 0, min: -1, max: 1, step: 0.01 },
+        hueBlue: { default: 0, min: -180, max: 180, step: 1, unit: '°' },
+        saturationBlue: { default: 0, min: -1, max: 1, step: 0.01 },
+        luminanceBlue: { default: 0, min: -1, max: 1, step: 0.01 },
+        luminanceSaturationBlue: { default: 0, min: -1, max: 1, step: 0.01 },
+        hueMagenta: { default: 0, min: -180, max: 180, step: 1, unit: '°' },
+        saturationMagenta: { default: 0, min: -1, max: 1, step: 0.01 },
+        luminanceMagenta: { default: 0, min: -1, max: 1, step: 0.01 },
+        luminanceSaturationMagenta: { default: 0, min: -1, max: 1, step: 0.01 },
+    },
+    selectColors: {
+        hueRange: { default: 0.08, min: 0, max: 0.5, step: 0.01 },
+        saturationRange: { default: 1, min: 0, max: 1, step: 0.01 },
+        brightnessRange: { default: 1, min: 0, max: 1, step: 0.01 },
+        saturation: { default: -1, min: -1, max: 1, step: 0.01 },
+        blend: { default: 1, min: 0, max: 1, step: 0.01 },
+    },
+    blur: {
+        radius: { default: 8, min: 0, max: 64, step: 0.5, unit: 'px' },
+    },
     bloom: {
-        // Past ×3 the halo overwhelms the source pixels and everything reads as haze.
-        intensity: { default: 1, min: 0, max: 3, step: 0.01 },
-        // Threshold 0.8 catches highlights without hazing the whole avatar; radius is the lib default.
-        threshold: { default: 0.8, min: 0, max: 1, step: 0.01 },
-        radius: { default: 0.85, min: 0, max: 1, step: 0.01 },
-        // VTS bloom's anamorphic-flare half. Streak 0 keeps the passes out of the
-        // graph; the angle is VTS's horizontal/vertical toggle made continuous.
-        streak: { default: 0, min: 0, max: 3, step: 0.01 },
-        streakThreshold: { default: 0.8, min: 0, max: 1, step: 0.01 },
-        streakAngle: { default: 0, min: -90, max: 90, step: 1, unit: '°' },
-        darken: { default: 0, min: 0, max: 1, step: 0.01 },
+        intensity: { default: 0, min: 0, max: 10, step: 0.01 },
+        threshold: { default: 0.5, min: 0, max: 2, step: 0.01 },
+        thresholdSmooth: { default: 0, min: 0, max: 1, step: 0.01 },
+        radius: { default: 1, min: 0, max: 6, step: 0.01 },
+        saturation: { default: 0, min: -1, max: 1, step: 0.01 },
+        opacity: { default: 1, min: 0, max: 1, step: 0.01 },
+        starRays: { default: 3, min: 1, max: 6, step: 1 },
+        starAngle: { default: 0, min: 0, max: 360, step: 1, unit: '°' },
+        colorTolerance: { default: 0.5, min: 0.01, max: 1, step: 0.01 },
     },
     // Shoost's diffusion (its Kino bloom variant, sliders Radius/Intensity/
     // Contrast→threshold): screen-composited, so its Opacity slider folds into
@@ -51,8 +149,7 @@ export const EFFECT_SPECS = {
         /** World metres of acceptably-sharp depth around the focus plane. */
         focusRange: { default: 2, min: 0.1, max: 10, step: 0.01 },
     },
-    // VTube Studio's chromatic_aberration surface: strength + blur edges, the
-    // latter continuous like rim.bothSides (VTS fades the same shader uniform).
+    // VTube Studio's chromatic_aberration surface: strength + continuous blur edges.
     chromaticAberration: {
         strength: { default: 0.2, min: 0, max: 1, step: 0.01 },
         blurEdges: { default: 1, min: 0, max: 1, step: 0.01 },
@@ -64,28 +161,16 @@ export const EFFECT_SPECS = {
         darkness: { default: 0.5, min: 0, max: 1, step: 0.01 },
         offset: { default: 0.5, min: 0, max: 1, step: 0.01 },
     },
-    // Shoost's rim-light ranges where the control carried over (size, angle,
-    // opacity→intensity); the rest follows VTube Studio's backlight. New params
-    // default neutral (omni 0, limit 1, darken 0) so healed scenes keep their look.
     rim: {
-        intensity: { default: 1, min: 0, max: 2, step: 0.01 },
-        omni: { default: 0, min: 0, max: 1, step: 0.01 },
-        size: { default: 16, min: 1, max: 64, step: 1, unit: 'px' },
-        softness: { default: 0.6, min: 0, max: 1, step: 0.01 },
-        angle: { default: 45, min: 0, max: 360, step: 1, unit: '°' },
-        bothSides: { default: 0.5, min: 0, max: 1, step: 0.01 },
-        brightnessLimit: { default: 1, min: 0, max: 1, step: 0.01 },
-        darken: { default: 0, min: 0, max: 1, step: 0.01 },
-    },
-    // VTube Studio's backlight outline block: stripe count/speed/curve ranges are
-    // VTS's; size is ours (px, like rim) instead of VTS's normalized 0..1.
+        size: { default: 0.5, min: 0, max: 1, step: 0.01 },
+        brightness: { default: 0, min: 0, max: 5, step: 0.01 },
+        contrast: { default: 0, min: 0, max: 1, step: 0.01 },
+        angle: { default: 0, min: -180, max: 180, step: 1, unit: '°' },
+        opacity: { default: 1, min: 0, max: 1, step: 0.01 },
+    },
     outline: {
-        size: { default: 8, min: 1, max: 64, step: 1, unit: 'px' },
+        size: { default: 0, min: 0, max: 1, step: 0.01 },
         opacity: { default: 1, min: 0, max: 1, step: 0.01 },
-        stripes: { default: 0.5, min: 0, max: 1, step: 0.01 },
-        stripeMix: { default: 1, min: 0, max: 1, step: 0.01 },
-        stripeSpeed: { default: 0.2, min: -1, max: 1, step: 0.01 },
-        stripeCurve: { default: 0, min: 0, max: 1, step: 0.01 },
     },
     // VTube Studio's backlight shadow: an offset silhouette copy. VTS hides it at
     // zero offset; ours defaults to a visible down-right cast so enabling shows it.
@@ -93,6 +178,7 @@ export const EFFECT_SPECS = {
         opacity: { default: 0.6, min: 0, max: 1, step: 0.01 },
         offsetX: { default: 3, min: -20, max: 20, step: 0.5, digits: 1, unit: '%' },
         offsetY: { default: 3, min: -20, max: 20, step: 0.5, digits: 1, unit: '%' },
+        size: { default: 0, min: 0, max: 64, step: 0.5, unit: 'px' },
     },
     pixelate: {
         // Pixels per block; past ~64 the frame is a handful of tiles.
@@ -154,24 +240,127 @@ export const EFFECT_SPECS = {
  * string param appear.
  */
 export const EFFECT_COLOR_SPECS = {
+    colorWheels: {
+        liftColor: { default: '#ffffff' },
+        gammaColor: { default: '#ffffff' },
+        gainColor: { default: '#ffffff' },
+        shadowsColor: { default: '#ffffff' },
+        midtonesColor: { default: '#ffffff' },
+        highlightsColor: { default: '#ffffff' },
+    },
+    selectColors: {
+        color1: { default: '#ff0000' },
+        color2: { default: '#ffff00' },
+        color3: { default: '#00ff00' },
+        color4: { default: '#00ffff' },
+        color5: { default: '#0000ff' },
+        color6: { default: '#ff00ff' },
+        color7: { default: '#ffffff' },
+        color8: { default: '#808080' },
+        color9: { default: '#000000' },
+        color10: { default: '#ff8800' },
+    },
     bloom: {
         tint: { default: '#ffffff' },
-        // Beautify's anamorphic-flare tint default — the classic lens-streak blue.
-        streakTint: { default: '#8080ff' },
+        color1: { default: '#ffffff' },
+        color2: { default: '#ffffff' },
+        color3: { default: '#ffffff' },
+        color4: { default: '#ffffff' },
+        color5: { default: '#ffffff' },
     },
     rim: {
         color: { default: '#ffffff' },
     },
     outline: {
-        color: { default: '#ffffff' },
-        stripeColor: { default: '#000000' },
+        color: { default: '#000000' },
     },
     dropShadow: {
         color: { default: '#000000' },
     },
 };
-// Object.keys widens to string[]; the annotation above pins the keys to exactly ToggleEffectKey.
-export const TOGGLE_EFFECT_KEYS = Object.keys(EFFECT_SPECS);
+/** Boolean defaults, validated alongside numeric and color parameters. */
+export const EFFECT_BOOLEAN_SPECS = {
+    blur: { highQuality: { default: false } },
+    bloom: {
+        selectColors: { default: false },
+        invertColors: { default: false },
+        // Like Select Colors' first slot: with every pick off the mask is zero, so switching
+        // selection on would make the glow vanish rather than narrow.
+        color1Enabled: { default: true },
+        color2Enabled: { default: false },
+        color3Enabled: { default: false },
+        color4Enabled: { default: false },
+        color5Enabled: { default: false },
+    },
+    selectColors: {
+        invert: { default: false },
+        color1Enabled: { default: true },
+        color2Enabled: { default: false },
+        color3Enabled: { default: false },
+        color4Enabled: { default: false },
+        color5Enabled: { default: false },
+        color6Enabled: { default: false },
+        color7Enabled: { default: false },
+        color8Enabled: { default: false },
+        color9Enabled: { default: false },
+        color10Enabled: { default: false },
+    },
+};
+/** Enum defaults and allowed values. */
+export const EFFECT_ENUM_SPECS = {
+    blur: { mode: { default: 'gaussian', values: ['gaussian', 'bokeh'] } },
+    bloom: { mode: { default: 'normal', values: ['normal', 'streak', 'star'] } },
+    rim: {
+        mode: { default: 'single', values: ['single', 'double', 'sharpenSingle', 'sharpenDouble'] },
+        blendMode: {
+            default: 'overlay',
+            values: [
+                'normal',
+                'darken',
+                'multiply',
+                'colorBurn',
+                'linearBurn',
+                'add',
+                'lighten',
+                'screen',
+                'colorDodge',
+                'overlay',
+                'softLight',
+                'hardLight',
+                'vividLight',
+                'linearLight',
+                'pinLight',
+                'hardMix',
+                'difference',
+                'exclusion',
+                'subtract',
+                'divide',
+                'hue',
+                'saturation',
+                'color',
+                'luminosity',
+            ],
+        },
+    },
+    outline: { quality: { default: 'medium', values: ['low', 'medium', 'high'] } },
+    colorWheels: { mode: { default: 'liftGammaGain', values: ['liftGammaGain', 'shadowsMidtonesHighlights'] } },
+};
+/** Select the layer effects from any value set containing them. */
+export function pickLayerEffects(effects) {
+    return Object.fromEntries(LAYER_EFFECT_KEYS.map(key => [key, effects[key]]));
+}
+/** The canonical per-item effect list, preserving disabled rows and including every enabled effect. */
+export function layerEffectKeys(listed, effects) {
+    return canonicalKeys(LAYER_EFFECT_KEYS, listed, effects);
+}
+/** An independent, disabled set for a fresh source layer. */
+export function defaultLayerEffects() {
+    return defaultsForKeys(LAYER_EFFECT_KEYS);
+}
+/** Whether a source needs its own effect pass. */
+export function layerEffectsActive(effects) {
+    return LAYER_EFFECT_KEYS.some(key => effects[key].enabled);
+}
 /**
  * Registry effects that render as scene geometry inside the scene pass rather
  * than composing into the post chain. A new scene-space effect must join this
@@ -179,16 +368,20 @@ export const TOGGLE_EFFECT_KEYS = Object.keys(EFFECT_SPECS);
  */
 export const SCENE_SPACE_EFFECT_KEYS = ['rain', 'snow'];
 /** Registry effects the post chain composes — {@link TOGGLE_EFFECT_KEYS} minus the scene-space ones. */
-export const POST_EFFECT_KEYS = TOGGLE_EFFECT_KEYS.filter(key => !SCENE_SPACE_EFFECT_KEYS.includes(key));
-/** The canonical `effectLayers`: registry order, junk dropped, every switched-on effect included. */
+export const POST_EFFECT_KEYS = SCENE_EFFECT_KEYS.filter(key => !SCENE_SPACE_EFFECT_KEYS.includes(key));
+/** Registry order, junk dropped, every switched-on effect included — the rule both layer lists follow. */
+function canonicalKeys(keys, listed, effects) {
+    return keys.filter(key => effects[key] !== undefined && (listed.includes(key) || effects[key].enabled));
+}
+/** The canonical scene `effectLayers`. */
 export function effectLayerKeys(listed, effects) {
-    return TOGGLE_EFFECT_KEYS.filter(key => listed.includes(key) || effects[key].enabled);
+    return canonicalKeys(SCENE_EFFECT_KEYS, listed, effects);
 }
 /**
  * Composition order, bottom to top.
  * Display-only: the desktop chain's `rebuild()` is the order that runs — a stage moved there moves here too.
  */
-export const EFFECT_STACK_ORDER = [
+export const ALL_EFFECT_STACK_ORDER = [
     'rain',
     'snow',
     'dof',
@@ -199,24 +392,44 @@ export const EFFECT_STACK_ORDER = [
     'bloom',
     'diffusion',
     'color',
+    'levels',
+    'colorWheels',
+    'colorShift',
+    'selectColors',
+    'blur',
     'pixelate',
     'glitch',
     'droplets',
     'grain',
     'vignette',
 ];
-/** Every registry effect at its defaults — the derived half of a fresh {@link SceneEffects}. */
-export function defaultToggleEffects() {
+/** Scene composition order, retained under its existing SDK name. */
+export const EFFECT_STACK_ORDER = ALL_EFFECT_STACK_ORDER.filter((key) => SCENE_EFFECT_KEYS.includes(key));
+/** Layer composition order before the result joins the scene. */
+export const LAYER_EFFECT_STACK_ORDER = ALL_EFFECT_STACK_ORDER.filter((key) => LAYER_EFFECT_KEYS.includes(key));
+/** Heal only the requested effect keys, using the same parameter kinds as defaults and editors. */
+export function healEffectValues(raw, keys) {
+    const src = isRecord(raw) ? raw : {};
     const out = {};
-    for (const key of TOGGLE_EFFECT_KEYS) {
-        const fx = { enabled: false };
+    for (const key of keys) {
+        const value = isRecord(src[key]) ? src[key] : {};
+        const fx = { enabled: value.enabled === true };
         for (const [param, spec] of Object.entries(EFFECT_SPECS[key]))
-            fx[param] = spec.default;
+            fx[param] = clamp(finiteOr(value[param], spec.default), spec.min, spec.max);
         for (const [param, spec] of Object.entries(EFFECT_COLOR_SPECS[key] ?? {}))
-            fx[param] = spec.default;
+            fx[param] = hexColorOr(value[param], spec.default);
+        for (const [param, spec] of Object.entries(EFFECT_BOOLEAN_SPECS[key] ?? {}))
+            fx[param] = typeof value[param] === 'boolean' ? value[param] : spec.default;
+        for (const [param, spec] of Object.entries(EFFECT_ENUM_SPECS[key] ?? {}))
+            fx[param] = typeof value[param] === 'string' && spec.values.includes(value[param]) ? value[param] : spec.default;
         out[key] = fx;
     }
-    // Runtime-built, invisible to TS; EFFECT_SPECS's satisfies check is what pins
-    // each entry's params to exactly SceneEffects[key].
     return out;
 }
+function defaultsForKeys(keys) {
+    return healEffectValues(null, keys);
+}
+/** Scene toggle defaults, independent of effects offered only on layers. */
+export function defaultToggleEffects() {
+    return defaultsForKeys(SCENE_EFFECT_KEYS);
+}

package/dist/values/hands.d.ts

@@ -0,0 +1,53 @@
+/** VTube Studio hand inputs, extended with nizima LIVE's wrist Y rotation. */
+export declare const HAND_INPUT_NAMES: readonly ["HandLeftFound", "HandLeftPositionX", "HandLeftPositionY", "HandLeftPositionZ", "HandLeftAngleX", "HandLeftAngleY", "HandLeftAngleZ", "HandLeftOpen", "HandLeftFinger_1_Thumb", "HandLeftFinger_2_Index", "HandLeftFinger_3_Middle", "HandLeftFinger_4_Ring", "HandLeftFinger_5_Pinky", "HandRightFound", "HandRightPositionX", "HandRightPositionY", "HandRightPositionZ", "HandRightAngleX", "HandRightAngleY", "HandRightAngleZ", "HandRightOpen", "HandRightFinger_1_Thumb", "HandRightFinger_2_Index", "HandRightFinger_3_Middle", "HandRightFinger_4_Ring", "HandRightFinger_5_Pinky", "BothHandsFound", "HandDistance"];
+export type HandInputName = (typeof HAND_INPUT_NAMES)[number];
+export type HandInputs = Partial<Record<HandInputName, number>>;
+/** Whether an input uses the canonical hand vocabulary. */
+export declare function isHandInputName(input: string): input is HandInputName;
+/** Names nizima uses for VTS's numbered fingers and both-hands detection. */
+export declare const NIZIMA_HAND_ALIASES: {
+    readonly HandLeftFingerThumb: "HandLeftFinger_1_Thumb";
+    readonly HandLeftFingerIndex: "HandLeftFinger_2_Index";
+    readonly HandLeftFingerMiddle: "HandLeftFinger_3_Middle";
+    readonly HandLeftFingerRing: "HandLeftFinger_4_Ring";
+    readonly HandLeftFingerPinky: "HandLeftFinger_5_Pinky";
+    readonly HandRightFingerThumb: "HandRightFinger_1_Thumb";
+    readonly HandRightFingerIndex: "HandRightFinger_2_Index";
+    readonly HandRightFingerMiddle: "HandRightFinger_3_Middle";
+    readonly HandRightFingerRing: "HandRightFinger_4_Ring";
+    readonly HandRightFingerPinky: "HandRightFinger_5_Pinky";
+    readonly HandBothFound: "BothHandsFound";
+};
+/** Canonicalize a hand name; aliases share canonical units on the plugin API. */
+export declare function canonicalHandInputName(input: string): HandInputName | null;
+/** Angles are degrees; positions and distance use VTS's ten-unit scale. */
+export declare const HAND_INPUT_RANGES: {
+    readonly HandLeftFound: readonly [0, 1];
+    readonly HandLeftPositionX: readonly [-10, 10];
+    readonly HandLeftPositionY: readonly [-10, 10];
+    readonly HandLeftPositionZ: readonly [-10, 10];
+    readonly HandLeftAngleX: readonly [-180, 180];
+    readonly HandLeftAngleY: readonly [-90, 90];
+    readonly HandLeftAngleZ: readonly [-180, 180];
+    readonly HandLeftOpen: readonly [0, 1];
+    readonly HandLeftFinger_1_Thumb: readonly [0, 1];
+    readonly HandLeftFinger_2_Index: readonly [0, 1];
+    readonly HandLeftFinger_3_Middle: readonly [0, 1];
+    readonly HandLeftFinger_4_Ring: readonly [0, 1];
+    readonly HandLeftFinger_5_Pinky: readonly [0, 1];
+    readonly HandRightFound: readonly [0, 1];
+    readonly HandRightPositionX: readonly [-10, 10];
+    readonly HandRightPositionY: readonly [-10, 10];
+    readonly HandRightPositionZ: readonly [-10, 10];
+    readonly HandRightAngleX: readonly [-180, 180];
+    readonly HandRightAngleY: readonly [-90, 90];
+    readonly HandRightAngleZ: readonly [-180, 180];
+    readonly HandRightOpen: readonly [0, 1];
+    readonly HandRightFinger_1_Thumb: readonly [0, 1];
+    readonly HandRightFinger_2_Index: readonly [0, 1];
+    readonly HandRightFinger_3_Middle: readonly [0, 1];
+    readonly HandRightFinger_4_Ring: readonly [0, 1];
+    readonly HandRightFinger_5_Pinky: readonly [0, 1];
+    readonly BothHandsFound: readonly [0, 1];
+    readonly HandDistance: readonly [0, 10];
+};