@laplace.live/persona-sdk 0.1.1 → 0.2.0

package/README.md

@@ -43,11 +43,27 @@ import WebSocket from "ws";
 const persona = new PersonaClient({
   token,
   auth: "header",
-  createWebSocket: (url, headers) =>
-    new WebSocket(url, { headers }) as unknown as globalThis.WebSocket,
+  createWebSocket: (url, headers) => new WebSocket(url, { headers }),
 });
 ```
 
+## Identifying your app
+
+Pass `clientInfo` so your app shows up by name under **Connected Clients** in Persona's
+settings (optional — unidentified clients work the same). The SDK re-declares it on every
+reconnect; it is self-declared and display-only, never authorization:
+
+```ts
+const persona = new PersonaClient({
+  token,
+  clientInfo: { name: "My Overlay", version: "1.2.0", developer: "You" },
+});
+```
+
+Two server close codes are terminal and stop the reconnect loop: `CLOSE_KEY_REVOKED` (4001,
+the key was revoked) and `CLOSE_FORCE_DISCONNECTED` (4002, the user disconnected the session
+in Persona). The client reports them via `onWarning` and goes `closed`.
+
 Treat the token like a password: it grants control of the app, including loading registered
 models and web overlays. The server listens on loopback unless LAN access is enabled in
 Persona's settings.

package/dist/client.d.ts

@@ -1,7 +1,25 @@
 import type { EventData, EventName } from './events.ts';
-import type { MethodName, MethodRequest, MethodResponse } from './methods.ts';
+import type { MethodName, MethodRequest, MethodResponse, SessionIdentifyRequest } from './methods.ts';
 import type { InjectTarget } from './types.ts';
 export type PersonaClientState = 'closed' | 'connecting' | 'open' | 'reconnecting';
+/**
+ * The subset of the WebSocket API the client uses. The global `WebSocket`
+ * (browsers, Node ≥22, Bun) and the `ws` package's client both satisfy it
+ * structurally, so `createWebSocket` implementations need no casts.
+ */
+export interface WebSocketLike {
+    readonly readyState: number;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    addEventListener(type: 'message', listener: (event: {
+        data?: unknown;
+    }) => void): void;
+    addEventListener(type: 'close', listener: (event?: {
+        code?: number;
+        reason?: string;
+    }) => void): void;
+    addEventListener(type: 'error', listener: () => void): void;
+}
 export interface PersonaClientOptions {
     /** An API key created in Persona's settings. */
     token: string;
@@ -18,8 +36,13 @@ export interface PersonaClientOptions {
     reconnectDelayMs?: number;
     reconnectDelayMaxMs?: number;
     requestTimeoutMs?: number;
+    /**
+     * Identifies your app in Persona's settings (Connected Clients). Declarative and
+     * display-only, never authorization; sent automatically on every connection.
+     */
+    clientInfo?: SessionIdentifyRequest;
     /** Custom socket factory — for `ws` with headers, or tests. `headers` is set only for `auth: 'header'`. */
-    createWebSocket?: (url: string, headers: Record<string, string> | undefined) => WebSocket;
+    createWebSocket?: (url: string, headers: Record<string, string> | undefined) => WebSocketLike;
     onStateChange?: (state: PersonaClientState) => void;
     /** Non-fatal notices (protocol version mismatch). Default `console.warn`. */
     onWarning?: (message: string) => void;
@@ -84,6 +107,14 @@ export declare class PersonaClient {
     private buildUrl;
     private open;
     private onHello;
+    /**
+     * Subscribe, falling back to one request per event when the *server* refuses the batch:
+     * servers before v0.15 reject the whole array over a single unknown event name.
+     * A dropped socket rejects too, and is not a refusal — the next open re-subscribes.
+     */
+    private subscribe;
+    private subscribeIndividually;
+    private warnUnsupported;
     private onServerMessage;
     private failPending;
     private scheduleReconnect;

package/dist/client.js

@@ -1,6 +1,6 @@
 import { parseServerMessage } from "./envelope.js";
 import { PersonaApiError } from "./errors.js";
-import { DEFAULT_API_PORT, INJECT_HEARTBEAT_MS, injectTargetKey, PROTOCOL_VERSION } from "./protocol.js";
+import { CLOSE_FORCE_DISCONNECTED, CLOSE_KEY_REVOKED, DEFAULT_API_PORT, INJECT_HEARTBEAT_MS, injectTargetKey, PROTOCOL_VERSION, } from "./protocol.js";
 const DEFAULTS = {
     url: `ws://127.0.0.1:${String(DEFAULT_API_PORT)}`,
     reconnectDelayMs: 500,
@@ -89,9 +89,8 @@ export class PersonaClient {
             this.listeners.set(event, set);
         }
         set.add(cb);
-        if (isNew && this.state === 'open') {
-            void this.call('events.subscribe', { events: [event] }).catch(() => undefined);
-        }
+        if (isNew && this.state === 'open')
+            this.subscribe([event]);
         return () => {
             const s = this.listeners.get(event);
             if (!s)
@@ -117,7 +116,10 @@ export class PersonaClient {
             ...(opts?.onError === undefined ? {} : { onError: opts.onError }),
         };
         this.leases.set(key, lease);
-        this.startHeartbeat();
+        // Only while open — onHello resumes held leases, so a lease taken on a closed
+        // client must not start a referenced interval (it would pin a Node process).
+        if (this.state === 'open')
+            this.startHeartbeat();
         this.queueFlush();
         return {
             set: (v) => {
@@ -196,7 +198,7 @@ export class PersonaClient {
                 }
                 this.onServerMessage(msg);
             });
-            ws.addEventListener('close', () => {
+            ws.addEventListener('close', ev => {
                 if (this.ws !== ws)
                     return; // an intentional close already moved on
                 this.ws = null;
@@ -207,6 +209,19 @@ export class PersonaClient {
                     this.setState('closed');
                     return;
                 }
+                const code = ev?.code;
+                if (code === CLOSE_KEY_REVOKED || code === CLOSE_FORCE_DISCONNECTED) {
+                    // Terminal by protocol: redialing would either fail auth forever or undo the user's action.
+                    if (this.reconnectTimer !== null)
+                        clearTimeout(this.reconnectTimer);
+                    this.reconnectTimer = null;
+                    this.stopHeartbeat();
+                    this.warn(code === CLOSE_KEY_REVOKED
+                        ? 'the server revoked this API key — create a new one in Persona and reconnect'
+                        : 'the server disconnected this session — not reconnecting');
+                    this.setState('closed');
+                    return;
+                }
                 if (!this.opts.reconnect || this.state === 'connecting') {
                     // Initial connect failed: report to the caller instead of retrying forever.
                     this.setState('closed');
@@ -225,12 +240,64 @@ export class PersonaClient {
             this.warn(`protocol version mismatch: server speaks v${String(protocol)}, SDK speaks v${String(PROTOCOL_VERSION)}`);
         }
         this.reconnectAttempt = 0;
-        this.setState('open');
+        const info = this.opts.clientInfo;
+        // Identity is session-scoped, so every (re)connect re-declares it. Swallow errors:
+        // pre-feature servers answer `unknown-method`, and a mid-flight drop is not news.
+        if (info)
+            void this.call('session.identify', info).catch(() => undefined);
         const events = [...this.listeners.keys()];
+        // Before `open`, so a listener registered by an onStateChange handler does not
+        // race a second subscribe for the same event.
         if (events.length > 0)
-            void this.call('events.subscribe', { events }).catch(() => undefined);
-        if (this.leases.size > 0)
+            this.subscribe(events);
+        this.setState('open');
+        // Held leases resume here; restart the heartbeat that close()/a terminal close stopped.
+        if (this.leases.size > 0) {
+            this.startHeartbeat();
             this.queueFlush();
+        }
+    }
+    /**
+     * Subscribe, falling back to one request per event when the *server* refuses the batch:
+     * servers before v0.15 reject the whole array over a single unknown event name.
+     * A dropped socket rejects too, and is not a refusal — the next open re-subscribes.
+     */
+    subscribe(events) {
+        void this.call('events.subscribe', { events })
+            .then(r => {
+            const missing = events.filter(e => !r.subscribed.includes(e));
+            if (missing.length > 0)
+                this.warnUnsupported(missing);
+        })
+            .catch((err) => {
+            if (!(err instanceof PersonaApiError))
+                return;
+            if (events.length === 1)
+                this.warnUnsupported(events);
+            else
+                this.subscribeIndividually(events);
+        });
+    }
+    subscribeIndividually(events) {
+        const refused = [];
+        void Promise.all(events.map(e => this.call('events.subscribe', { events: [e] })
+            .then(r => {
+            // A v0.15+ server answers per-event by omission, not rejection.
+            if (!r.subscribed.includes(e))
+                refused.push(e);
+        })
+            .catch((err) => {
+            if (err instanceof PersonaApiError)
+                refused.push(e);
+        }))).then(() => {
+            if (refused.length > 0)
+                this.warnUnsupported(refused);
+        });
+    }
+    warnUnsupported(events) {
+        const app = this.serverInfo?.app;
+        const server = app ? `${app.name} ${app.version}` : 'the connected Persona app';
+        this.warn(`${server} does not support these events: ${events.join(', ')} — update the desktop app to receive them`);
     }
     onServerMessage(msg) {
         if (msg.kind === 'event') {

package/dist/events.d.ts

@@ -1,4 +1,4 @@
-import type { HotkeyState, ModelFormat, PoseStatus, SceneState, Settings, TrackingStatus } from './types.ts';
+import type { ExpressionPersistence, HotkeyState, ModelFormat, PoseStatus, SceneState, Settings, TrackingStatus } from './types.ts';
 /** Every push event a session can subscribe to, with its payload. */
 export interface EventMap {
     /** Any scene mutation: create/delete/rename/activate/shortcut and persisted scene edits. */
@@ -35,6 +35,19 @@ export interface EventMap {
     'scene.loading': {
         loading: boolean;
     };
+    /** The desktop's editing selection moved (any source: stage click, panel, or a plugin); null = cleared. */
+    'selection.changed': {
+        instanceId: string | null;
+    };
+    /** A model or asset was registered: re-run `model.list`/`asset.list` for that kind. */
+    'registry.changed': {
+        kind: 'model' | 'asset';
+    };
+    /** The per-model "remember expressions" flag changed. */
+    'expression.persistence': {
+        modelId: string;
+        persistence: ExpressionPersistence;
+    };
 }
 export type EventName = keyof EventMap;
 export type EventData<E extends EventName = EventName> = EventMap[E];

package/dist/events.js

@@ -10,6 +10,9 @@ export const EVENT_NAMES = Object.keys({
     'motion.started': true,
     'motion.ended': true,
     'scene.loading': true,
+    'selection.changed': true,
+    'registry.changed': true,
+    'expression.persistence': true,
 });
 export function isEventName(v) {
     return typeof v === 'string' && EVENT_NAMES.includes(v);

package/dist/methods.d.ts

@@ -77,6 +77,15 @@ export interface InstanceSetPrimaryRequest {
     instanceId: string;
 }
 export type InstanceSetPrimaryResponse = EmptyResponse;
+export interface SelectionSetRequest {
+    /** Scene item (model or object) to select on the desktop; null clears the selection. */
+    instanceId: string | null;
+}
+export type SelectionSetResponse = EmptyResponse;
+export type SelectionGetRequest = EmptyRequest;
+export interface SelectionGetResponse {
+    instanceId: string | null;
+}
 export interface InstanceSetPlacementRequest {
     instanceId?: string;
     live2d?: Partial<ScreenPlacement>;
@@ -296,6 +305,19 @@ export type AppStatsRequest = EmptyRequest;
 export interface AppStatsResponse {
     fps: number | null;
 }
+/**
+ * Self-declared identity of the connecting app, shown in Persona's settings.
+ * Declarative and unverified — display/attribution only, never authorization.
+ */
+export interface SessionIdentifyRequest {
+    /** Display name of the connecting application. 1–64 chars. */
+    name: string;
+    /** Version of the connecting application. Up to 32 chars. */
+    version?: string;
+    /** Developer/vendor shown alongside the name. Up to 64 chars. */
+    developer?: string;
+}
+export type SessionIdentifyResponse = EmptyResponse;
 export interface EventsSubscribeRequest {
     events: EventName[];
 }
@@ -389,6 +411,16 @@ export interface MethodMap {
         request: InstanceSetPrimaryRequest;
         response: InstanceSetPrimaryResponse;
     };
+    /** Drives the desktop's editing selection (outline + Model tab); ephemeral, never persisted. */
+    'selection.set': {
+        request: SelectionSetRequest;
+        response: SelectionSetResponse;
+    };
+    /** Current editing selection; changes stream as `selection.changed`. */
+    'selection.get': {
+        request: SelectionGetRequest;
+        response: SelectionGetResponse;
+    };
     'instance.setPlacement': {
         request: InstanceSetPlacementRequest;
         response: InstanceSetPlacementResponse;
@@ -553,6 +585,14 @@ export interface MethodMap {
         request: AppStatsRequest;
         response: AppStatsResponse;
     };
+    /**
+     * Declare who this client is (display only, never authorization). Session-scoped:
+     * re-send on every connection — the SDK's `clientInfo` option does it automatically.
+     */
+    'session.identify': {
+        request: SessionIdentifyRequest;
+        response: SessionIdentifyResponse;
+    };
     'events.subscribe': {
         request: EventsSubscribeRequest;
         response: EventsSubscribeResponse;

package/dist/protocol.d.ts

@@ -3,6 +3,10 @@ import type { InjectTarget } from './types.ts';
 export declare const PROTOCOL_VERSION = 1;
 /** Default port the Persona API server listens on (user-configurable in the app). */
 export declare const DEFAULT_API_PORT = 25034;
+/** Server close code: the session's API key was revoked. Terminal — the client must not redial. */
+export declare const CLOSE_KEY_REVOKED = 4001;
+/** Server close code: the user disconnected this session from Persona's settings. Terminal — the client must not redial. */
+export declare const CLOSE_FORCE_DISCONNECTED = 4002;
 /** An injected parameter reverts this long after its last write — the lease, not a setting. */
 export declare const INJECT_LEASE_TTL_MS = 1000;
 /** How often {@link PersonaClient.driveParameter} re-sends held leases to keep them alive. */

package/dist/protocol.js

@@ -2,6 +2,10 @@
 export const PROTOCOL_VERSION = 1;
 /** Default port the Persona API server listens on (user-configurable in the app). */
 export const DEFAULT_API_PORT = 25034;
+/** Server close code: the session's API key was revoked. Terminal — the client must not redial. */
+export const CLOSE_KEY_REVOKED = 4001;
+/** Server close code: the user disconnected this session from Persona's settings. Terminal — the client must not redial. */
+export const CLOSE_FORCE_DISCONNECTED = 4002;
 /** An injected parameter reverts this long after its last write — the lease, not a setting. */
 export const INJECT_LEASE_TTL_MS = 1000;
 /** How often {@link PersonaClient.driveParameter} re-sends held leases to keep them alive. */

package/dist/schemas.d.ts

@@ -34,9 +34,9 @@ export declare const SettingsPatchSchema: z.ZodObject<{
         fpsLimit: z.ZodOptional<z.ZodNumber>;
         selectionOutline: z.ZodOptional<z.ZodBoolean>;
         effectsQuality: z.ZodOptional<z.ZodEnum<{
-            high: "high";
-            medium: "medium";
             low: "low";
+            medium: "medium";
+            high: "high";
         }>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
@@ -116,9 +116,9 @@ export declare const requestSchemas: {
                 fpsLimit: z.ZodOptional<z.ZodNumber>;
                 selectionOutline: z.ZodOptional<z.ZodBoolean>;
                 effectsQuality: z.ZodOptional<z.ZodEnum<{
-                    high: "high";
-                    medium: "medium";
                     low: "low";
+                    medium: "medium";
+                    high: "high";
                 }>>;
             }, z.core.$strip>>;
         }, z.core.$strip>;
@@ -144,6 +144,11 @@ export declare const requestSchemas: {
     'pose.setPort': z.ZodObject<{
         port: z.ZodNumber;
     }, z.core.$strip>;
+    'session.identify': z.ZodObject<{
+        name: z.ZodString;
+        version: z.ZodOptional<z.ZodString>;
+        developer: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
     'events.subscribe': z.ZodObject<{
         events: z.ZodArray<z.ZodCustom<keyof import("./events.ts").EventMap, keyof import("./events.ts").EventMap>>;
     }, z.core.$strip>;

package/dist/schemas.js

@@ -1,5 +1,4 @@
 import * as z from 'zod';
-import { isEventName } from "./events.js";
 // Runtime validation for the request side of the wire. Schemas exist for the
 // methods whose params the app's main process consumes directly; methods without
 // one are stage-owned — the renderer validates and heals them (same rules as the
@@ -31,8 +30,7 @@ export const SettingsPatchSchema = z.object({
     })
         .optional(),
 });
-const eventNameSchema = z.custom(isEventName, 'unknown event name');
-/** Tolerates unknown names (version skew); the server ignores what it cannot map. */
+/** Tolerates unknown names for version skew; the server filters them and reports what took. */
 const lenientEventNameSchema = z.custom(v => typeof v === 'string', 'event names must be strings');
 export const requestSchemas = {
     'scene.get': z.object({ sceneId: nonEmpty.optional() }),
@@ -66,7 +64,12 @@ export const requestSchemas = {
     'pose.setEnabled': z.object({ enabled: z.boolean() }),
     'pose.setSource': z.object({ source: z.enum(['vmc']) }),
     'pose.setPort': z.object({ port: z.number().int().min(1).max(65535) }),
-    'events.subscribe': z.object({ events: z.array(eventNameSchema).min(1) }),
+    'session.identify': z.object({
+        name: z.string().trim().min(1).max(64),
+        version: z.string().max(32).optional(),
+        developer: z.string().max(64).optional(),
+    }),
+    'events.subscribe': z.object({ events: z.array(lenientEventNameSchema).min(1) }),
     'events.unsubscribe': z.object({ events: z.array(lenientEventNameSchema).optional() }),
     'param.inject': z.object({ entries: z.array(InjectEntrySchema).min(1) }),
     'param.release': z.object({ targets: z.array(InjectTargetSchema).optional() }),

package/dist/types.d.ts

@@ -2,16 +2,19 @@ export type ModelFormat = 'live2d' | 'vrm';
 export type ModelKind = 'bundled' | 'user';
 /** A model as the registry lists it. Paths deliberately never cross the wire. */
 export interface ModelRef {
+    /** Stable slug, unique per installed model. */
     id: string;
     name: string;
     kind: ModelKind;
     format: ModelFormat;
 }
+/** How a registered file is labelled. Wider than an object's content kinds: `.hdr` is only ever an environment map. */
 export type AssetKind = 'image' | 'video' | 'prop' | 'ibl' | 'lut';
 /** A registered object-source file. `exists` is false once the file is gone from disk. */
 export interface AssetRef {
     id: string;
     name: string;
+    /** What the extension makes it — an object created from it starts on this kind. */
     kind: AssetKind;
     exists: boolean;
 }
@@ -22,7 +25,7 @@ export interface ScreenPlacement {
     scale: number;
     rotation: number;
 }
-/** World-space VRM placement. Rotations in radians. */
+/** World-space placement. Rotations in radians, applied YXZ; `rotY` composes over the model's base yaw. */
 export interface VrmPlacement {
     x: number;
     y: number;
@@ -32,20 +35,33 @@ export interface VrmPlacement {
     rotZ: number;
     scale: number;
 }
+/** {@link ScreenPlacement} plus the per-object fade. */
 export interface Place2D extends ScreenPlacement {
     opacity: number;
 }
+/** {@link VrmPlacement} plus the per-object fade. */
 export interface Place3D extends VrmPlacement {
     opacity: number;
 }
-/** Per-instance MToon fine-tuning, layered over each material's authored values. */
+/**
+ * Per-instance MToon fine-tuning, layered over each material's authored values —
+ * offsets add, multipliers scale, so materials keep their relative differences.
+ * All-neutral values (1, 0, 0, 0, 1, 1, 1) render the model exactly as authored.
+ */
 export interface MToonTuning {
+    /** 0..1 strength of the authored shading: 1 keeps it, 0 lifts every shade color to its lit color. */
     shade: number;
+    /** -1..1 added to authored shading shift; positive pushes the terminator so less of the model is shaded. */
     shadingShift: number;
+    /** -1..1 added to authored toony; positive hardens the lit/shade edge, negative softens it. */
     shadingToony: number;
+    /** -1..1 added to authored GI equalization: how evenly ambient/IBL light wraps the model. */
     giEqualization: number;
+    /** Multiplier on the parametric rim color. */
     rim: number;
+    /** Multiplier on outline width. */
     outlineWidth: number;
+    /** Multiplier on emissive intensity; >1 pairs with bloom. */
     emissive: number;
 }
 export interface SceneModelItem {
@@ -57,11 +73,14 @@ export interface SceneModelItem {
     vrm: VrmPlacement;
     idleAnimation: boolean;
     idleClip: string;
+    /** MToon material fine-tuning, VRM only. */
     mtoon: MToonTuning;
 }
 export type ObjectSpace = '2d' | '3d';
+/** Where a webpage overlay renders relative to the stage. */
 export type WebLayer = 'behind' | 'front';
 export type CaptureKind = 'display' | 'window';
+/** What an object renders. Mirrors VTube Studio's items and Warudo's screen/prop assets. */
 export type ObjectContent = {
     kind: 'image';
     assetId: string;
@@ -89,36 +108,49 @@ export type ObjectContent = {
     sourceId: string;
     label: string;
 };
-/** Where on a parent model an object rides. */
+/** Where on a parent model an object rides. `root` is the model's own transform. */
 export type AttachAnchor = {
     kind: 'root';
-} | {
+}
+/** VRM humanoid bone name (`hips`, `head`, `leftHand`, …). */
+ | {
     kind: 'bone';
     bone: string;
-} | {
+}
+/** Live2D drawable + the triangle and barycentric weights of the pin: it deforms with the mesh. */
+ | {
     kind: 'artMesh';
     id: string;
     verts: [number, number, number];
     weights: [number, number, number];
 };
+/** Live2D only: smoothed ParamAngleZ × multiplier turns the pinned item (X/Y ride the mesh). */
+export interface AttachHeadAngle {
+    multiplier: number;
+    /** VTS-style 0..50; ~frames of lag at 60 fps (0 = instant). */
+    smoothing: number;
+}
+/** 3D only: spring lag on the follow; absent is rigid. */
+export interface AttachElasticity {
+    stiffness: number;
+    damping: number;
+    maxSpeed: number;
+}
 export interface Attach {
+    /** Always a model instance in the same space; anything else is cleared on load. */
     parentInstanceId: string;
     anchor: AttachAnchor;
     followRotation: boolean;
-    headAngle: {
-        multiplier: number;
-        smoothing: number;
-    } | null;
-    elasticity: {
-        stiffness: number;
-        damping: number;
-        maxSpeed: number;
-    } | null;
+    headAngle: AttachHeadAngle | null;
+    elasticity: AttachElasticity | null;
 }
+/** User override for one light baked into a prop asset. */
 export interface ObjectLightOverride {
     enabled: boolean;
+    /** Scene-slider units, or null to keep the asset's own (normalized) intensity. */
     intensity: number | null;
 }
+/** A non-avatar thing on stage: image, video, screen capture, webpage, or 3D prop. */
 export interface SceneObjectItem {
     kind: 'object';
     instanceId: string;
@@ -128,9 +160,16 @@ export interface SceneObjectItem {
     content: ObjectContent;
     place2d: Place2D;
     place3d: Place3D;
+    /** Riding a model in the same space, with the placement read as an offset; null stands alone. */
     attach: Attach | null;
+    /**
+     * Overrides for lights baked into prop content, keyed by traversal index —
+     * the only stable handle a glb gives. A re-exported asset that reorders its
+     * lights shifts them; they degrade, never break.
+     */
     lightOverrides: Record<string, ObjectLightOverride>;
 }
+/** Anything the stage renders. Array order in {@link Scene.items} is z-order within each space. */
 export type SceneItem = SceneModelItem | SceneObjectItem;
 export type BackgroundMode = 'transparent' | 'color' | 'image';
 /** `imagePath` is accepted but survives only when the app has allowlisted it via its own picker. */
@@ -142,6 +181,7 @@ export interface SceneBackground {
 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;
     elevation: number;
@@ -149,11 +189,18 @@ export interface OrbitTransform {
     targetX: number;
     targetY: number;
 }
+/** Scene-level VRM camera. `orbit: null` = never framed — the first VRM load frames it from model height. */
 export interface SceneCamera {
     orbit: OrbitTransform | null;
     fov: number;
 }
 export type SceneLightType = 'directional' | 'point' | 'ambient';
+/**
+ * One scene light. Angles are degrees. Directional lights aim with
+ * azimuth/elevation and sit at x/y/z (which moves their handle and shadow
+ * coverage, not their parallel shading), point lights use x/y/z + range,
+ * ambient uses none — all fields stay so a type switch keeps them.
+ */
 export interface SceneLight {
     id: string;
     type: SceneLightType;
@@ -165,64 +212,95 @@ export interface SceneLight {
     y: number;
     z: number;
     range: number;
+    /** Ambient light is directionless, so it never casts whatever this says. */
     castShadow: boolean;
+    /** Penumbra width in shadow-map texels — a stylistic dial; the filter widens the edge uniformly. */
     shadowRadius: number;
 }
+/** Distance haze. Only geometry fogs — empty space keeps the window's transparency. */
 export interface SceneFog {
     enabled: boolean;
     color: string;
+    /** Exponential-squared falloff; the useful band is well under 1 at avatar scale. */
     density: number;
 }
+/** Display transform applied after the scene renders. `none` keeps colors exactly as authored. */
 export type SceneToneMapping = 'none' | 'neutral' | 'aces' | 'agx';
-export interface SceneEffects {
-    toneMapping: SceneToneMapping;
-    exposure: number;
-    bloom: {
-        enabled: boolean;
-        intensity: number;
-        threshold: number;
-        radius: number;
-    };
-    vignette: {
-        enabled: boolean;
-        darkness: number;
-        offset: number;
-    };
-    color: {
-        enabled: boolean;
-        hue: number;
-        saturation: number;
-        brightness: number;
-        contrast: number;
-    };
-    chromaticAberration: {
-        enabled: boolean;
-        strength: number;
-    };
-    grain: {
+/** Glow around bright pixels. `threshold` is the luminance floor; `radius` widens the halo. */
+export interface SceneBloom {
+    enabled: boolean;
+    intensity: number;
+    threshold: number;
+    radius: number;
+}
+/** Darkened frame corners. `offset` pushes the falloff outward. */
+export interface SceneVignette {
+    enabled: boolean;
+    darkness: number;
+    offset: number;
+}
+/** Parametric grading. Hue in degrees; the rest are -1..1 around neutral 0. */
+export interface SceneColorGrade {
+    enabled: boolean;
+    hue: number;
+    saturation: number;
+    brightness: number;
+    contrast: number;
+}
+/** RGB fringing toward frame edges. `strength` 0..1. */
+export interface SceneChromaticAberration {
+    enabled: boolean;
+    strength: number;
+}
+/** Animated film grain. `strength` is blend opacity 0..1. */
+export interface SceneFilmGrain {
+    enabled: boolean;
+    strength: number;
+}
+/** Color-grading lookup table (.cube/.3dl asset). Active whenever an asset is set. */
+export interface SceneLut {
+    assetId: string | null;
+    intensity: number;
+}
+/**
+ * Bokeh blur away from the focus plane. Focus tracks the camera's orbit target,
+ * so whatever the user framed stays sharp; `focusRange` widens the sharp band.
+ */
+export interface SceneDepthOfField {
+    enabled: boolean;
+    bokehScale: number;
+    focusRange: number;
+}
+/** Overlay/stylization gimmicks, each independently switchable. */
+export interface SceneStylize {
+    pixelate: {
         enabled: boolean;
-        strength: number;
-    };
-    lut: {
-        assetId: string | null;
-        intensity: number;
+        granularity: number;
     };
-    dof: {
+    glitch: {
         enabled: boolean;
-        bokehScale: number;
-        focusRange: number;
-    };
-    stylize: {
-        pixelate: {
-            enabled: boolean;
-            granularity: number;
-        };
-        glitch: {
-            enabled: boolean;
-        };
     };
 }
+/** Post-processing over the rendered 3D frame. Everything off skips the effect chain entirely. */
+export interface SceneEffects {
+    toneMapping: SceneToneMapping;
+    /** Scene brightness multiplied in before the tone curve; 1 is neutral. Works in every mode, including `none`. */
+    exposure: number;
+    bloom: SceneBloom;
+    vignette: SceneVignette;
+    color: SceneColorGrade;
+    chromaticAberration: SceneChromaticAberration;
+    grain: SceneFilmGrain;
+    lut: SceneLut;
+    dof: SceneDepthOfField;
+    stylize: SceneStylize;
+}
+/**
+ * Image-based lighting for the 3D stage: an environment map, whether to show it
+ * behind the scene, the scene-global fog, and post-processing.
+ */
 export interface SceneEnvironment {
+    /** Equirectangular `.hdr` or image driving the environment lighting, or null. */
     iblAssetId: string | null;
     iblIntensity: number;
     showSkybox: boolean;
@@ -232,13 +310,17 @@ export interface SceneEnvironment {
 export interface Scene {
     id: string;
     name: string;
+    /** Models and objects in one list; array order = z-order (bottom to top) within each space. */
     items: SceneItem[];
+    /** Tracking/pose/hotkey/expression target. 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[];
     environment: SceneEnvironment;
+    /** Electron accelerator that applies this scene, or null. */
     shortcut: string | null;
 }
 export interface SceneState {
@@ -322,9 +404,15 @@ export interface ExpressionPersistence {
 }
 export type TrackingSourceId = 'vts-ios' | 'vts-ios-native' | 'ifacialmocap';
 export type PoseSourceId = 'vmc';
-export type EffectsQuality = 'high' | 'medium' | 'low';
 export type TrackingStatus = 'off' | 'waiting' | 'tracking' | 'no-face';
 export type PoseStatus = 'off' | 'waiting' | 'tracking';
+export declare const EFFECTS_QUALITY_LEVELS: readonly ["low", "medium", "high"];
+export type EffectsQuality = (typeof EFFECTS_QUALITY_LEVELS)[number];
+/**
+ * Accepted values for `performance.fpsLimit`; 0 = unlimited. Anything else is snapped
+ * to the nearest preset by the app, so a picker offering other values would lie.
+ */
+export declare const FPS_LIMIT_PRESETS: readonly [0, 15, 30, 60, 90];
 /** The curated settings surface the API exposes — never the raw store shape. */
 export interface Settings {
     window: {

package/dist/types.js

@@ -1,6 +1,12 @@
 // The API's data model: the entity shapes that requests, responses, and events
 // carry. Structural mirrors of the app's scene/settings models, minus anything
 // filesystem-shaped — model refs are sanitized to ids, never directories.
+export const EFFECTS_QUALITY_LEVELS = ['low', 'medium', 'high'];
+/**
+ * Accepted values for `performance.fpsLimit`; 0 = unlimited. Anything else is snapped
+ * to the nearest preset by the app, so a picker offering other values would lie.
+ */
+export const FPS_LIMIT_PRESETS = [0, 15, 30, 60, 90];
 // ---- Injection -----------------------------------------------------------------
 /** VTS's input vocabulary — the valid `id`s for `input` inject targets (and the names a model's `.vtube.json` references). */
 export const INPUT_NAMES = [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@laplace.live/persona-sdk",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "TypeScript SDK and wire schema for the LAPLACE Persona plugin API",
   "license": "MIT",
   "type": "module",