@laplace.live/persona-sdk 1.24.0 → 1.25.1

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/edit-history.d.ts

@@ -14,10 +14,14 @@ export interface EditHistory<T> {
     redo(): T | null;
     canUndo(): boolean;
     canRedo(): boolean;
+    /** The cursor entry itself, uncloned — read it, never mutate it; null before the first reset. */
+    peek(): T | null;
     /**
      * Rewrite the run of entries around the cursor that share its `runKey`, outward until the key
      * changes on either side — a fold, never a step, so undo and redo across the run all carry it.
      */
     amend(runKey: (value: T) => string, rewrite: (value: T) => void): void;
+    /** Rewrite every entry, the redo tail included — never a step; for an identity every entry must follow. */
+    rewriteAll(rewrite: (value: T) => void): void;
 }
 export declare function createEditHistory<T>(limit?: number): EditHistory<T>;

package/dist/values/edit-history.js

@@ -3,6 +3,12 @@ export function createEditHistory(limit = EDIT_HISTORY_LIMIT) {
     let stack = [];
     let cursor = -1;
     const entryOf = (value, key = JSON.stringify(value)) => ({ value: structuredClone(value), key });
+    // A fold rewrites entries per frame while the camera eases; only the cursor's key is ever compared.
+    const keyOf = (entry) => (entry.key ??= JSON.stringify(entry.value));
+    const rewriteEntry = (entry, rewrite) => {
+        rewrite(entry.value);
+        entry.key = null;
+    };
     return {
         reset(value) {
             stack = [entryOf(value)];
@@ -14,7 +20,7 @@ export function createEditHistory(limit = EDIT_HISTORY_LIMIT) {
             // the redo tail alive.
             const key = JSON.stringify(value);
             const cur = stack[cursor];
-            if (cur && cur.key === key)
+            if (cur && keyOf(cur) === key)
                 return;
             stack.length = cursor + 1;
             stack.push(entryOf(value, key));
@@ -38,27 +44,28 @@ export function createEditHistory(limit = EDIT_HISTORY_LIMIT) {
         },
         canUndo: () => cursor > 0,
         canRedo: () => cursor < stack.length - 1,
+        peek: () => stack[cursor]?.value ?? null,
         amend(runKey, rewrite) {
             const cur = stack[cursor];
             if (!cur)
                 return;
             const from = runKey(cur.value);
-            const apply = (e) => {
-                rewrite(e.value);
-                e.key = JSON.stringify(e.value);
-            };
             for (let i = cursor; i >= 0; i--) {
                 const entry = stack[i];
                 if (runKey(entry.value) !== from)
                     break;
-                apply(entry);
+                rewriteEntry(entry, rewrite);
             }
             for (let i = cursor + 1; i < stack.length; i++) {
                 const entry = stack[i];
                 if (runKey(entry.value) !== from)
                     break;
-                apply(entry);
+                rewriteEntry(entry, rewrite);
             }
         },
+        rewriteAll(rewrite) {
+            for (const entry of stack)
+                rewriteEntry(entry, rewrite);
+        },
     };
 }

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. */