@laplace.live/persona-sdk 1.23.1 → 1.25.0

package/README.md

@@ -34,21 +34,21 @@ mouth.set(0.3);
 mouth.release();
 ```
 
-By default the token travels as `?token=` (works in browsers). From Node you can use an
-`Authorization: Bearer` header instead by supplying a socket that can set headers, e.g. the
-[`ws`](https://www.npmjs.com/package/ws) package (install it separately — it is not a
-dependency of this SDK):
+By default the token travels as `?token=` (works in browsers). From Node, `createNodeClient`
+sends it as an `Authorization: Bearer` header instead, over Node's global `WebSocket`, and
+logs the close that ends a session for good (the key revoked, or the session disconnected in
+Persona):
 
 ```ts
-import WebSocket from "ws";
+import { createNodeClient } from "@laplace.live/persona-sdk";
 
-const persona = new PersonaClient({
-  token,
-  auth: "header",
-  createWebSocket: (url, headers) => new WebSocket(url, { headers }),
-});
+const persona = createNodeClient({ token, log: console.warn });
+await persona.connect();
 ```
 
+Any other socket that can set headers, such as the [`ws`](https://www.npmjs.com/package/ws)
+package, plugs into `new PersonaClient({ token, auth: "header", createWebSocket })`.
+
 ## Identifying your app
 
 Pass `clientInfo` so your app shows up by name under **Connected Clients** in Persona's

package/dist/client/client.js

@@ -1,8 +1,8 @@
 import { parseServerMessage } from "../wire/envelope.js";
 import { PersonaApiError } from "../wire/errors.js";
-import { CLOSE_FORCE_DISCONNECTED, CLOSE_KEY_REVOKED, INJECT_HEARTBEAT_MS, injectTargetKey, PROTOCOL_VERSION, SCENE_ACTIVATION_TIMEOUT_MS, } from "../wire/protocol.js";
+import { CLOSE_FORCE_DISCONNECTED, CLOSE_KEY_REVOKED, INJECT_HEARTBEAT_MS, injectTargetKey, PROTOCOL_VERSION, requestTimeoutMs, } from "../wire/protocol.js";
 import { personaWsUrl } from "./address.js";
-import { renameLegacyKinds } from "./legacy-kinds.js";
+import { renameLegacyNames } from "./legacy-names.js";
 const DEFAULTS = {
     url: personaWsUrl(),
     reconnectDelayMs: 500,
@@ -108,8 +108,7 @@ export class PersonaClient {
             const timer = setTimeout(() => {
                 this.pending.delete(id);
                 reject(new Error(`request timed out: ${method}`));
-            }, this.opts.requestTimeoutMs ??
-                (method === 'scene.activate' ? SCENE_ACTIVATION_TIMEOUT_MS : DEFAULTS.requestTimeoutMs));
+            }, this.opts.requestTimeoutMs ?? requestTimeoutMs(method, DEFAULTS.requestTimeoutMs));
             // Only the runtime id ties a response back to `M`, and its result is unvalidated wire JSON.
             this.pending.set(id, { method, resolve: resolve, reject, timer });
             ws.send(JSON.stringify({ kind: 'request', id, method, ...(params === undefined ? {} : { params }) }));
@@ -357,7 +356,7 @@ export class PersonaClient {
             const set = this.listeners.get(msg.event);
             if (!set)
                 return;
-            const data = renameLegacyKinds(msg.event, msg.data);
+            const data = renameLegacyNames(msg.event, msg.data);
             // Only `msg.event` ties these callbacks to their payload type, and the payload is unvalidated wire JSON.
             for (const cb of set)
                 cb(data);
@@ -372,7 +371,7 @@ export class PersonaClient {
         this.pending.delete(id);
         clearTimeout(p.timer);
         if (msg.kind === 'response')
-            p.resolve(renameLegacyKinds(p.method, msg.result));
+            p.resolve(renameLegacyNames(p.method, msg.result));
         else
             p.reject(new PersonaApiError(msg.code, msg.message));
     }

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

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

package/dist/client/{legacy-kinds.js → legacy-names.js}

@@ -1,5 +1,5 @@
 import { isRecord } from "../values/guards.js";
-import { canonicalActionKind } from "../wire/types.js";
+import { canonicalActionKind, canonicalAppCapability } from "../wire/types.js";
 function renameHotkeyActions(state) {
     if (!isRecord(state) || !Array.isArray(state.hotkeys))
         return state;
@@ -23,8 +23,15 @@ function renameActionKinds(list) {
             : automation),
     };
 }
-/** A method result or event payload with the action kinds an older host still sends renamed to current ones. */
-export function renameLegacyKinds(name, data) {
+/** Old capability names folded into current ones, once each; unknown names stay, as `app.info` reports them. */
+function renameCapabilities(info) {
+    if (!isRecord(info) || !Array.isArray(info.capabilities))
+        return info;
+    const names = info.capabilities.map((name) => typeof name === 'string' ? canonicalAppCapability(name) : name);
+    return { ...info, capabilities: [...new Set(names)] };
+}
+/** A method result or event payload with the old names an older host still sends renamed to current ones. */
+export function renameLegacyNames(name, data) {
     switch (name) {
         case 'hotkey.list':
         case 'hotkey.set':
@@ -34,6 +41,8 @@ export function renameLegacyKinds(name, data) {
         case 'automation.list':
         case 'automation.state':
             return renameActionKinds(data);
+        case 'app.info':
+            return renameCapabilities(data);
         default:
             return data;
     }

package/dist/client/node.d.ts

@@ -0,0 +1,13 @@
+import type { PersonaClientOptions } from './client.ts';
+import { PersonaClient } from './client.ts';
+/** A Node app's own identity and log sink; {@link createNodeClient} sets the transport and close handling. */
+export type NodeClientOptions = Omit<PersonaClientOptions, 'auth' | 'connectTimeoutMs' | 'createWebSocket' | 'onWarning' | 'onClose'> & {
+    /** Receives SDK warnings and the notice of a terminal close. */
+    log: (message: string) => void;
+};
+/**
+ * A client for a Node process — the Stream Deck plugin, the MCP server. The API key rides an
+ * `Authorization: Bearer` header, never the URL, and a terminal close (key revoked, session
+ * disconnected in Persona) is logged, since the client stops redialing after one.
+ */
+export declare function createNodeClient({ log, ...options }: NodeClientOptions): PersonaClient;

package/dist/client/node.js

@@ -0,0 +1,29 @@
+import { PersonaClient } from "./client.js";
+/** A key press or tool call must answer promptly; the attempt keeps going in the background. */
+const CONNECT_TIMEOUT_MS = 5000;
+/** Trusts a global WebSocket to be Node's: the DOM typings the SDK compiles under only know the browser one. */
+function takesHeaders(ctor) {
+    return typeof ctor === 'function';
+}
+/**
+ * A client for a Node process — the Stream Deck plugin, the MCP server. The API key rides an
+ * `Authorization: Bearer` header, never the URL, and a terminal close (key revoked, session
+ * disconnected in Persona) is logged, since the client stops redialing after one.
+ */
+export function createNodeClient({ log, ...options }) {
+    const Socket = globalThis.WebSocket;
+    if (!takesHeaders(Socket))
+        throw new Error('createNodeClient needs a global WebSocket (Node 22 or later)');
+    return new PersonaClient({
+        ...options,
+        connectTimeoutMs: CONNECT_TIMEOUT_MS,
+        auth: 'header',
+        createWebSocket: (url, headers) => new Socket(url, { headers }),
+        onWarning: log,
+        onClose: ({ code, reason, terminal }) => {
+            if (!terminal)
+                return;
+            log(`Persona closed the session (${String(code)}${reason === '' ? '' : `: ${reason}`}) — check the API key in Persona's settings`);
+        },
+    });
+}

package/dist/client/scene-hotkeys.d.ts

@@ -0,0 +1,16 @@
+import type { HotkeyState, Scene, SceneModelItem } from '../wire/types.ts';
+import type { PersonaClient } from './client.ts';
+/** One on-stage model's `hotkey.list` answer. */
+export interface ModelHotkeys {
+    model: SceneModelItem;
+    /** First in {@link hotkeyModels} order: the scene's primary model. */
+    primary: boolean;
+    state: HotkeyState;
+}
+/**
+ * `hotkey.list` for each model whose hotkeys are live ({@link hotkeyModels}: every model on stage, the
+ * primary first) — one promise per model, so a caller can settle each alone.
+ */
+export declare function listModelHotkeys(client: Pick<PersonaClient, 'call'>, scene: Pick<Scene, 'items' | 'primaryInstanceId'>): Promise<ModelHotkeys>[];
+/** The active scene's live hotkeys, per model and the primary first; a scene without a model lists none. */
+export declare function listSceneHotkeys(client: Pick<PersonaClient, 'call'>): Promise<ModelHotkeys[]>;

package/dist/client/scene-hotkeys.js

@@ -0,0 +1,17 @@
+import { hotkeyModels } from "../values/hotkeys.js";
+/**
+ * `hotkey.list` for each model whose hotkeys are live ({@link hotkeyModels}: every model on stage, the
+ * primary first) — one promise per model, so a caller can settle each alone.
+ */
+export function listModelHotkeys(client, scene) {
+    return hotkeyModels(scene).map(async (model, index) => ({
+        model,
+        primary: index === 0,
+        state: await client.call('hotkey.list', { modelId: model.ref.id }),
+    }));
+}
+/** The active scene's live hotkeys, per model and the primary first; a scene without a model lists none. */
+export async function listSceneHotkeys(client) {
+    const { scene } = await client.call('scene.get', {});
+    return Promise.all(listModelHotkeys(client, scene));
+}

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export * from './client/address.ts';
 export * from './client/client.ts';
+export * from './client/node.ts';
+export * from './client/scene-hotkeys.ts';
 export * from './values/arkit.ts';
 export * from './values/bindings.ts';
 export * from './values/camera.ts';
@@ -31,6 +33,7 @@ export * from './wire/errors.ts';
 export * from './wire/events.ts';
 export * from './wire/methods.ts';
 export * from './wire/protocol.ts';
+export * from './wire/schemas/fields.ts';
 export * from './wire/schemas/requests.ts';
 export * from './wire/schemas/settings.ts';
 export * from './wire/types.ts';

package/dist/index.js

@@ -2,6 +2,8 @@
 // and the values/registries every Persona app must agree on.
 export * from "./client/address.js";
 export * from "./client/client.js";
+export * from "./client/node.js";
+export * from "./client/scene-hotkeys.js";
 export * from "./values/arkit.js";
 export * from "./values/bindings.js";
 export * from "./values/camera.js";
@@ -33,6 +35,7 @@ export * from "./wire/errors.js";
 export * from "./wire/events.js";
 export * from "./wire/methods.js";
 export * from "./wire/protocol.js";
+export * from "./wire/schemas/fields.js";
 export * from "./wire/schemas/requests.js";
 export * from "./wire/schemas/settings.js";
 export * from "./wire/types.js";

package/dist/values/bindings.d.ts

@@ -6,13 +6,25 @@ export interface Binding {
     /** Summed at their weights before the range map; never empty. The first is the input the list files it under. */
     terms: BindingTerm[];
     output: string;
-    /** The rig author's own name for this binding, when their `.vtube.json` carried one. */
+    /**
+     * The rig author's own name for this binding, when their `.vtube.json` carried one
+     * (`ParameterSettings[].Name`). It outranks `.cdi3.json`, which names only the output parameter.
+     */
     name?: string;
     inRange: [number, number];
     outRange: [number, number];
     clampOutput: boolean;
+    /** VTS's smoothing, per parameter as its manual prescribes, on its own 0-and-up scale; 0 is none. */
     smoothing: number;
+    /**
+     * VTS's auto-blink: the engine's blink closes the output alongside any input. Only on the
+     * model's `EyeBlink` parameters, the ones that blink writes; inert elsewhere.
+     */
     autoBlink: boolean;
+    /**
+     * Response shape over the normalized input, replacing the straight line between the ranges.
+     * Absent until something authors one: `.vtube.json` has no curve.
+     */
     curve?: Curve;
 }
 /** A parameter the rig declares, as the picker lists it. */
@@ -29,23 +41,36 @@ export interface BindingLiveValues {
     /** What each bound parameter reads on the model right now, by output id; empty for a host that cannot read it back. */
     outputs: Record<string, number>;
 }
+/** A `.cdi3.json` parameter group. */
+export interface CubismParameterGroup {
+    id: string;
+    name: string;
+}
+/** The rig author's own naming, from `.cdi3.json`; every map omits ids the file leaves unnamed. */
+export interface CubismDisplayInfo {
+    parameterNames: Record<string, string>;
+    /** Parameter id → group id. Absent for a parameter the rig left ungrouped. */
+    parameterGroups: Record<string, string>;
+    /** Groups in file order — the order the rig author arranged them in. */
+    groups: CubismParameterGroup[];
+}
+/** What `.physics3.json` says about parameters. */
+export interface CubismPhysicsInfo {
+    /** Parameters that drive physics — normal to track. */
+    inputs: string[];
+    /** Parameters physics writes; tracking one of these fights the simulation. */
+    outputs: string[];
+}
+/** What a rig's Cubism sidecars say about its parameters; each side null when absent or unusable. */
+export interface CubismMetadata {
+    display: CubismDisplayInfo | null;
+    physics: CubismPhysicsInfo | null;
+}
 /** Metadata read from a rig's display and physics sidecars. */
 export interface BindingEditorData {
     connections: Binding[];
     parameters: BindableParameter[];
-    metadata: {
-        display: {
-            parameterNames: Record<string, string>;
-            parameterGroups: Record<string, string>;
-            groups: {
-                id: string;
-                name: string;
-            }[];
-        } | null;
-        physics: {
-            inputs: string[];
-            outputs: string[];
-        } | null;
-    };
+    metadata: CubismMetadata;
+    /** The connections came from Persona's sidecar, not the rig's `.vtube.json`. */
     edited: boolean;
 }

package/dist/values/controller.d.ts

@@ -92,6 +92,7 @@ export declare const CONTROLLER_DEAD_ZONE_MAX = 0.5;
 export interface ControllerProfileInfo {
     slot: ControllerSlot;
     deviceId: string;
+    /** User label; absent keeps the numbered controller name. */
     name?: string;
     /** Radial stick dead zone, 0..0.5; absent until tuned, meaning `DEFAULT_CONTROLLER_DEAD_ZONE`. */
     deadZone?: number;
@@ -100,15 +101,17 @@ export interface ControllerConfig {
     enabled: boolean;
     profiles: ControllerProfileInfo[];
 }
+/** A live connection and the saved profile it is identified as, if any. */
+export interface ControllerDeviceInfo {
+    id: string;
+    index: number;
+    mapping: string;
+    slot: ControllerSlot | null;
+}
 /** Stage-owned input sample; hardware is never polled by the remote console. */
 export interface ControllerState {
     profiles: ControllerProfileInfo[];
-    devices: {
-        id: string;
-        index: number;
-        mapping: string;
-        slot: ControllerSlot | null;
-    }[];
+    devices: ControllerDeviceInfo[];
     inputs: Partial<Record<ControllerInputName, number>>;
     pressed: ControllerTriggerName[];
     assigningSlot: ControllerSlot | null;

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

@@ -60,6 +60,23 @@ export interface EffectEnumSpec<T extends string = string> {
     default: T;
     values: readonly T[];
 }
+/** Levels' color channels, run before the master levels; each suffixes its own copy of the params (`inputBlackR`). */
+export declare const LEVEL_CHANNELS: readonly ["R", "G", "B"];
+/** Color Shift's hue bands, around the wheel from red; each suffixes its own copy of the params (`hueRed`). */
+export declare const COLOR_SHIFT_BANDS: readonly ["Red", "Yellow", "Green", "Cyan", "Blue", "Magenta"];
+/** Select Colors' color slots, `color1` up. */
+export declare const SELECT_COLORS_SLOTS: readonly [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+/** A Select Colors slot, one of {@link SELECT_COLORS_SLOTS}. */
+export type SelectColorsSlot = (typeof SELECT_COLORS_SLOTS)[number];
+/** The color slots a layer's bloom can limit its glow to, `color1` up. */
+export declare const BLOOM_COLOR_SLOTS: readonly [1, 2, 3, 4, 5];
+/** A layer bloom color slot, one of {@link BLOOM_COLOR_SLOTS}. */
+export type BloomColorSlot = (typeof BLOOM_COLOR_SLOTS)[number];
+/**
+ * `table` once per suffix, suffix by suffix, each key suffixed (`{ hue }` over `['Red', 'Blue']` is
+ * `{ hueRed, hueBlue }`): how a per-channel parameter set spells its specs, labels and descriptions.
+ */
+export declare function suffixKeys<K extends string, V, S extends string>(table: Readonly<Record<K, V>>, suffixes: readonly S[]): Record<`${K}${S}`, V>;
 export declare const EFFECT_SPECS: Record<EffectKey, Readonly<Record<string, EffectParamSpec>>>;
 /**
  * Hex-color params, keyed like {@link EFFECT_SPECS} — generic walkers (healing,
@@ -71,6 +88,15 @@ export declare const EFFECT_COLOR_SPECS: Partial<Record<EffectKey, Readonly<Reco
 export declare const EFFECT_BOOLEAN_SPECS: Partial<Record<EffectKey, Readonly<Record<string, EffectBooleanSpec>>>>;
 /** Blend-mode order shared by effect editors and shader uniforms. */
 export declare const EFFECT_BLEND_MODES: readonly ["normal", "darken", "multiply", "colorBurn", "linearBurn", "add", "lighten", "screen", "colorDodge", "overlay", "softLight", "hardLight", "vividLight", "linearLight", "pinLight", "hardMix", "difference", "exclusion", "subtract", "divide", "hue", "saturation", "color", "luminosity"];
+export declare const FLARE_MODES: readonly ["add", "screen", "colorDodge"];
+export declare const FLARE_RAYS_MODES: readonly ["sun", "shine", "god"];
+export declare const GRADIENT_TYPES: readonly ["solid", "linear", "circle", "ellipse"];
+export declare const BLUR_MODES: readonly ["gaussian", "bokeh"];
+export declare const BLOOM_MODES: readonly ["normal", "streak", "star"];
+export declare const RIM_MODES: readonly ["single", "double", "sharpenSingle", "sharpenDouble"];
+export declare const COLOR_WHEELS_MODES: readonly ["liftGammaGain", "shadowsMidtonesHighlights"];
+/** Effects quality tiers, lowest first. */
+export declare const EFFECTS_QUALITY_LEVELS: readonly ["low", "medium", "high"];
 /** 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. */

package/dist/values/effect-schema.js

@@ -1,5 +1,5 @@
 // Scope and parameter metadata are plain data; labels and rendering stay with their consumers.
-import { finiteOr, isOneOf, isRecord } from "./guards.js";
+import { finiteOr, isOneOf, isRecord, keysOf } 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 = {
@@ -48,6 +48,57 @@ 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');
+/** Levels' color channels, run before the master levels; each suffixes its own copy of the params (`inputBlackR`). */
+export const LEVEL_CHANNELS = ['R', 'G', 'B'];
+/** Color Shift's hue bands, around the wheel from red; each suffixes its own copy of the params (`hueRed`). */
+export const COLOR_SHIFT_BANDS = ['Red', 'Yellow', 'Green', 'Cyan', 'Blue', 'Magenta'];
+/** Select Colors' color slots, `color1` up. */
+export const SELECT_COLORS_SLOTS = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+/** The color slots a layer's bloom can limit its glow to, `color1` up. */
+export const BLOOM_COLOR_SLOTS = [1, 2, 3, 4, 5];
+/** One channel's levels, shared by the master set and each of {@link LEVEL_CHANNELS}. */
+const LEVEL_SPECS = {
+    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 },
+};
+/** One hue band's offsets, shared by each of {@link COLOR_SHIFT_BANDS}. */
+const COLOR_SHIFT_SPECS = {
+    hue: { default: 0, min: -180, max: 180, step: 1, unit: '°' },
+    saturation: { default: 0, min: -1, max: 1, step: 0.01 },
+    luminance: { default: 0, min: -1, max: 1, step: 0.01 },
+    luminanceSaturation: { default: 0, min: -1, max: 1, step: 0.01 },
+};
+const SELECT_COLORS_DEFAULTS = {
+    1: '#ff0000',
+    2: '#ffff00',
+    3: '#00ff00',
+    4: '#00ffff',
+    5: '#0000ff',
+    6: '#ff00ff',
+    7: '#ffffff',
+    8: '#808080',
+    9: '#000000',
+    10: '#ff8800',
+};
+/**
+ * `table` once per suffix, suffix by suffix, each key suffixed (`{ hue }` over `['Red', 'Blue']` is
+ * `{ hueRed, hueBlue }`): how a per-channel parameter set spells its specs, labels and descriptions.
+ */
+export function suffixKeys(table, suffixes) {
+    // Object.fromEntries widens its keys to string; the entries are exactly the keys named.
+    return Object.fromEntries(suffixes.flatMap(suffix => keysOf(table).map(key => [`${key}${suffix}`, table[key]])));
+}
+/** `spec(slot)` for each color slot, keyed `color${slot}${suffix}` in slot order. */
+function colorSlotSpecs(slots, suffix, spec) {
+    // Object.fromEntries widens its keys to string; the entries are exactly the keys named.
+    return Object.fromEntries(slots.map(slot => [`color${slot}${suffix}`, spec(slot)]));
+}
+// The first slot starts on: with every pick off the mask is zero, so switching selection on
+// would select nothing rather than narrow.
+const slotEnabled = (slot) => ({ default: slot === 1 });
 // 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 = {
@@ -60,28 +111,7 @@ 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 },
-    },
+    levels: suffixKeys(LEVEL_SPECS, ['', ...LEVEL_CHANNELS]),
     colorWheels: {
         lift: { default: 0, min: -1, max: 1, step: 0.01 },
         gamma: { default: 0, min: -1, max: 1, step: 0.01 },
@@ -92,32 +122,7 @@ export const EFFECT_SPECS = {
         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 },
-    },
+    colorShift: suffixKeys(COLOR_SHIFT_SPECS, COLOR_SHIFT_BANDS),
     selectColors: {
         hueRange: { default: 0.08, min: 0, max: 0.5, step: 0.01 },
         saturationRange: { default: 1, min: 0, max: 1, step: 0.01 },
@@ -202,6 +207,7 @@ export const EFFECT_SPECS = {
     },
     outline: {
         size: { default: 0, min: 0, max: 1, step: 0.01 },
+        roundness: { default: 0, min: 0, max: 1, step: 0.01 },
         opacity: { default: 1, min: 0, max: 1, step: 0.01 },
     },
     // VTube Studio's backlight shadow: an offset silhouette copy. VTS hides it at
@@ -288,25 +294,10 @@ export const EFFECT_COLOR_SPECS = {
         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' },
-    },
+    selectColors: colorSlotSpecs(SELECT_COLORS_SLOTS, '', slot => ({ default: SELECT_COLORS_DEFAULTS[slot] })),
     bloom: {
         tint: { default: '#ffffff' },
-        color1: { default: '#ffffff' },
-        color2: { default: '#ffffff' },
-        color3: { default: '#ffffff' },
-        color4: { default: '#ffffff' },
-        color5: { default: '#ffffff' },
+        ...colorSlotSpecs(BLOOM_COLOR_SLOTS, '', () => ({ default: '#ffffff' })),
     },
     rim: {
         color: { default: '#ffeb74' },
@@ -334,26 +325,11 @@ export const EFFECT_BOOLEAN_SPECS = {
     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 },
+        ...colorSlotSpecs(BLOOM_COLOR_SLOTS, 'Enabled', slotEnabled),
     },
     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 },
+        ...colorSlotSpecs(SELECT_COLORS_SLOTS, 'Enabled', slotEnabled),
     },
 };
 /** Blend-mode order shared by effect editors and shader uniforms. */
@@ -383,21 +359,31 @@ export const EFFECT_BLEND_MODES = [
     'color',
     'luminosity',
 ];
+// The wire types derive from these, so every member a type admits also heals and publishes.
+export const FLARE_MODES = ['add', 'screen', 'colorDodge'];
+export const FLARE_RAYS_MODES = ['sun', 'shine', 'god'];
+export const GRADIENT_TYPES = ['solid', 'linear', 'circle', 'ellipse'];
+export const BLUR_MODES = ['gaussian', 'bokeh'];
+export const BLOOM_MODES = ['normal', 'streak', 'star'];
+export const RIM_MODES = ['single', 'double', 'sharpenSingle', 'sharpenDouble'];
+export const COLOR_WHEELS_MODES = ['liftGammaGain', 'shadowsMidtonesHighlights'];
+/** Effects quality tiers, lowest first. */
+export const EFFECTS_QUALITY_LEVELS = ['low', 'medium', 'high'];
 /** Enum defaults and allowed values. */
 export const EFFECT_ENUM_SPECS = {
     flare: {
-        mode: { default: 'add', values: ['add', 'screen', 'colorDodge'] },
-        raysMode: { default: 'sun', values: ['sun', 'shine', 'god'] },
+        mode: { default: 'add', values: FLARE_MODES },
+        raysMode: { default: 'sun', values: FLARE_RAYS_MODES },
     },
     gradient: {
-        type: { default: 'circle', values: ['solid', 'linear', 'circle', 'ellipse'] },
+        type: { default: 'circle', values: GRADIENT_TYPES },
         blendMode: { default: 'normal', values: EFFECT_BLEND_MODES },
     },
-    blur: { mode: { default: 'gaussian', values: ['gaussian', 'bokeh'] } },
-    bloom: { mode: { default: 'normal', values: ['normal', 'streak', 'star'] } },
-    rim: { mode: { default: 'single', values: ['single', 'double', 'sharpenSingle', 'sharpenDouble'] } },
-    outline: { quality: { default: 'medium', values: ['low', 'medium', 'high'] } },
-    colorWheels: { mode: { default: 'liftGammaGain', values: ['liftGammaGain', 'shadowsMidtonesHighlights'] } },
+    blur: { mode: { default: 'gaussian', values: BLUR_MODES } },
+    bloom: { mode: { default: 'normal', values: BLOOM_MODES } },
+    rim: { mode: { default: 'single', values: RIM_MODES } },
+    outline: { quality: { default: 'medium', values: EFFECTS_QUALITY_LEVELS } },
+    colorWheels: { mode: { default: 'liftGammaGain', values: COLOR_WHEELS_MODES } },
 };
 /** Select the layer effects from any value set containing them. */
 export function pickLayerEffects(effects) {

package/dist/values/hotkey-targets.d.ts

@@ -1,6 +1,6 @@
-import type { Hotkey, MotionGroup } from '../wire/types.ts';
+import type { Hotkey, ModelRef, MotionGroup } from '../wire/types.ts';
 /** A hotkey action Persona can run. */
-type HotkeyAction = NonNullable<Hotkey['action']>;
+export type HotkeyAction = NonNullable<Hotkey['action']>;
 /** What a model offers hotkeys: its expressions (a null `file` on formats with none) and its motion groups. */
 export interface HotkeyListing {
     expressions: readonly {
@@ -53,4 +53,11 @@ export declare function modelMatchesFile(file: string, model: {
     vtubeFile?: string | null;
     entryFile?: string;
 }): boolean;
-export {};
+/**
+ * Labels a model's hotkeys by what each points at — an expression's Name, a motion's label, a
+ * load-model's model name — or undefined for an action with no file, or once the target is gone.
+ * Walks the listing once, so a shortcut list builds one per model and asks it per row.
+ * @param models `model.list`'s refs; scene item refs carry no `vtubeFile` (see {@link modelMatchesFile}).
+ * @param groupLabel Display name for a motion group; VRM groups are clip refs, not names.
+ */
+export declare function hotkeyTargetLabels(listing: HotkeyListing, models: readonly Pick<ModelRef, 'name' | 'vtubeFile' | 'entryFile'>[], groupLabel?: (group: string) => string): (h: Pick<Hotkey, 'action' | 'file'>) => string | undefined;