@laplace.live/persona-sdk 0.5.0 → 0.7.0

package/dist/client/address.d.ts

@@ -0,0 +1,18 @@
+export declare const PORT_MIN = 1;
+export declare const PORT_MAX = 65535;
+export declare function isValidPort(port: number): boolean;
+/** Strict text → port: decimal digits only — rejects the hex/exponent/sign forms `Number()` accepts. */
+export declare function parsePort(text: string): number | null;
+export interface PersonaAddress {
+    host?: string;
+    port?: number;
+    /** `wss://` instead of `ws://` — only for a TLS-terminating proxy in front of the API. */
+    secure?: boolean;
+}
+/**
+ * WebSocket URL for the API server, from structured fields or one free-text
+ * address (`host`, `host:port`, bare or bracketed IPv6, or a full `ws(s)://`
+ * URL taken verbatim). Zone-scoped IPv6 throws — a URL cannot carry a zone id.
+ * The token never belongs in it — {@link PersonaClient} appends `?token=` itself.
+ */
+export declare function personaWsUrl(input?: string | PersonaAddress): string;

package/dist/client/address.js

@@ -0,0 +1,56 @@
+import { DEFAULT_API_HOST, DEFAULT_API_PORT } from "../wire/protocol.js";
+export const PORT_MIN = 1;
+export const PORT_MAX = 65535;
+export function isValidPort(port) {
+    return Number.isInteger(port) && port >= PORT_MIN && port <= PORT_MAX;
+}
+/** Strict text → port: decimal digits only — rejects the hex/exponent/sign forms `Number()` accepts. */
+export function parsePort(text) {
+    const t = text.trim();
+    if (!/^\d+$/.test(t))
+        return null;
+    const port = Number(t);
+    return isValidPort(port) ? port : null;
+}
+/** Bare IPv6 literals must be bracketed in a URL authority; hostnames and IPv4 pass through. */
+function formatHost(host) {
+    const trimmed = host.trim();
+    // WHATWG URL parsers reject an IPv6 zone id even %25-encoded, so fail with the real cause here.
+    if (trimmed.includes('%'))
+        throw new Error(`zone-scoped IPv6 addresses cannot be used in a URL: ${trimmed}`);
+    if (trimmed.startsWith('['))
+        return trimmed;
+    return trimmed.includes(':') ? `[${trimmed}]` : trimmed;
+}
+/**
+ * WebSocket URL for the API server, from structured fields or one free-text
+ * address (`host`, `host:port`, bare or bracketed IPv6, or a full `ws(s)://`
+ * URL taken verbatim). Zone-scoped IPv6 throws — a URL cannot carry a zone id.
+ * The token never belongs in it — {@link PersonaClient} appends `?token=` itself.
+ */
+export function personaWsUrl(input) {
+    if (typeof input === 'string')
+        return urlFromText(input);
+    const { host = DEFAULT_API_HOST, port = DEFAULT_API_PORT, secure = false } = input ?? {};
+    return `${secure ? 'wss' : 'ws'}://${formatHost(host)}:${String(port)}`;
+}
+function urlFromText(raw) {
+    const text = raw.trim();
+    if (text === '')
+        return personaWsUrl({});
+    if (text.includes('://'))
+        return text;
+    const closing = text.indexOf(']');
+    if (closing !== -1) {
+        // Bracketed IPv6, with or without a port.
+        const port = text.slice(closing + 1).replace(/^:/, '');
+        return `ws://${formatHost(text.slice(0, closing + 1))}:${port === '' ? String(DEFAULT_API_PORT) : port}`;
+    }
+    const colons = text.split(':').length - 1;
+    if (colons === 0)
+        return `ws://${text}:${String(DEFAULT_API_PORT)}`;
+    // 2+ colons is a bare IPv6 literal — a port cannot be expressed without brackets.
+    if (colons > 1)
+        return `ws://${formatHost(text.replace(/^\[/, ''))}:${String(DEFAULT_API_PORT)}`;
+    return `ws://${text}`;
+}

package/dist/{client.d.ts → client/client.d.ts}

@@ -1,6 +1,7 @@
-import type { EventData, EventName } from './events.ts';
-import type { MethodName, MethodRequest, MethodResponse, SessionIdentifyRequest } from './methods.ts';
-import type { InjectTarget } from './types.ts';
+import type { AppInfo } from '../wire/envelope.ts';
+import type { EventData, EventName } from '../wire/events.ts';
+import type { MethodName, MethodRequest, MethodResponse, SessionIdentifyRequest } from '../wire/methods.ts';
+import type { InjectTarget } from '../wire/types.ts';
 export type PersonaClientState = 'closed' | 'connecting' | 'open' | 'reconnecting';
 /**
  * The subset of the WebSocket API the client uses. The global `WebSocket`
@@ -14,12 +15,23 @@ export interface WebSocketLike {
     addEventListener(type: 'message', listener: (event: {
         data?: unknown;
     }) => void): void;
-    addEventListener(type: 'close', listener: (event?: {
-        code?: number;
-        reason?: string;
+    addEventListener(type: 'close', listener: (event: {
+        code: number;
+        reason: string;
     }) => void): void;
     addEventListener(type: 'error', listener: () => void): void;
 }
+/** A server- or network-initiated close. `terminal` marks the codes the client stops redialing on. */
+export interface PersonaCloseEvent {
+    code: number;
+    reason: string;
+    terminal: boolean;
+}
+/** The server's `hello`: its protocol version and app identity. */
+export interface ServerInfo {
+    protocol: number;
+    app: AppInfo;
+}
 export interface PersonaClientOptions {
     /** An API key created in Persona's settings. */
     token: string;
@@ -36,6 +48,8 @@ export interface PersonaClientOptions {
     reconnectDelayMs?: number;
     reconnectDelayMaxMs?: number;
     requestTimeoutMs?: number;
+    /** Bound each awaited {@link PersonaClient.connect} — on expiry it rejects while the attempt keeps going. */
+    connectTimeoutMs?: number;
     /**
      * Identifies your app in Persona's settings (Connected Clients). Declarative and
      * display-only, never authorization; sent automatically on every connection.
@@ -44,6 +58,13 @@ export interface PersonaClientOptions {
     /** Custom socket factory — for `ws` with headers, or tests. `headers` is set only for `auth: 'header'`. */
     createWebSocket?: (url: string, headers: Record<string, string> | undefined) => WebSocketLike;
     onStateChange?: (state: PersonaClientState) => void;
+    /**
+     * Server- or network-initiated closes, with the code and reason the raw socket
+     * carried. Fires after the client has settled its own handling (state, pending
+     * calls), so calling `close()` inside it is safe; a `close()` you issued does
+     * not report. When set, terminal closes skip `onWarning` — this is the signal.
+     */
+    onClose?: (event: PersonaCloseEvent) => void;
     /** Non-fatal notices (protocol version mismatch). Default `console.warn`. */
     onWarning?: (message: string) => void;
 }
@@ -70,20 +91,21 @@ export declare class PersonaClient {
     private closedByUser;
     private flushQueued;
     private nextId;
+    private connectPromise;
+    private settleConnect;
     private readonly idPrefix;
     /** The server's `hello`, once connected. */
-    serverInfo: {
-        protocol: number;
-        app: {
-            name: string;
-            version: string;
-            platform: string;
-        };
-    } | null;
+    serverInfo: ServerInfo | null;
     constructor(options: PersonaClientOptions);
     getState(): PersonaClientState;
-    /** Open the connection and wait for the server's `hello`. Rejects on first failure. */
+    /**
+     * Open the connection and wait for the server's `hello`. Rejects on first
+     * failure, and after `connectTimeoutMs` (the attempt then keeps going in the
+     * background). Joins an in-flight attempt instead of stacking a second socket;
+     * while reconnecting between backoff delays it dials immediately.
+     */
     connect(): Promise<void>;
+    private withConnectTimeout;
     /** Close for good: pending calls reject, leases drop server-side via the lease timeout. */
     close(): void;
     /** Send one request and await its typed response. */

package/dist/{client.js → client/client.js}

@@ -1,8 +1,9 @@
-import { parseServerMessage } from "./envelope.js";
-import { PersonaApiError } from "./errors.js";
-import { CLOSE_FORCE_DISCONNECTED, CLOSE_KEY_REVOKED, DEFAULT_API_PORT, INJECT_HEARTBEAT_MS, injectTargetKey, PROTOCOL_VERSION, } from "./protocol.js";
+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, } from "../wire/protocol.js";
+import { personaWsUrl } from "./address.js";
 const DEFAULTS = {
-    url: `ws://127.0.0.1:${String(DEFAULT_API_PORT)}`,
+    url: personaWsUrl(),
     reconnectDelayMs: 500,
     reconnectDelayMaxMs: 10_000,
     requestTimeoutMs: 10_000,
@@ -25,6 +26,8 @@ export class PersonaClient {
     closedByUser = false;
     flushQueued = false;
     nextId = 1;
+    connectPromise = null;
+    settleConnect = null;
     idPrefix = Math.random().toString(36).slice(2, 10);
     /** The server's `hello`, once connected. */
     serverInfo = null;
@@ -39,13 +42,40 @@ export class PersonaClient {
     getState() {
         return this.state;
     }
-    /** Open the connection and wait for the server's `hello`. Rejects on first failure. */
-    async connect() {
-        if (this.state === 'open' || this.state === 'connecting')
-            return;
+    /**
+     * Open the connection and wait for the server's `hello`. Rejects on first
+     * failure, and after `connectTimeoutMs` (the attempt then keeps going in the
+     * background). Joins an in-flight attempt instead of stacking a second socket;
+     * while reconnecting between backoff delays it dials immediately.
+     */
+    connect() {
+        if (this.state === 'open')
+            return Promise.resolve();
         this.closedByUser = false;
+        if (this.connectPromise !== null)
+            return this.withConnectTimeout(this.connectPromise);
+        if (this.reconnectTimer !== null) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        // Dial before announcing 'connecting': a connect() reentered from onStateChange
+        // must find the tracked attempt and join it, not resolve early.
+        const attempt = this.open();
         this.setState('connecting');
-        await this.open();
+        return this.withConnectTimeout(attempt);
+    }
+    withConnectTimeout(attempt) {
+        const ms = this.opts.connectTimeoutMs;
+        if (ms === undefined)
+            return attempt;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                reject(new Error(`timed out connecting after ${String(ms)} ms`));
+            }, ms);
+            attempt.then(resolve, reject).finally(() => {
+                clearTimeout(timer);
+            });
+        });
     }
     /** Close for good: pending calls reject, leases drop server-side via the lease timeout. */
     close() {
@@ -55,6 +85,8 @@ export class PersonaClient {
         this.reconnectTimer = null;
         this.stopHeartbeat();
         this.failPending(new Error('client closed'));
+        // An awaited connect() must reject now — nulling `ws` below makes its close event a no-op.
+        this.settleConnect?.(new Error('client closed'));
         const ws = this.ws;
         this.ws = null;
         ws?.close();
@@ -173,7 +205,7 @@ export class PersonaClient {
                     throw new Error("auth: 'header' needs a createWebSocket factory that can set headers");
                 })();
         this.ws = ws;
-        return new Promise((resolve, reject) => {
+        const attempt = new Promise((resolve, reject) => {
             let settled = false;
             const settle = (err) => {
                 if (settled)
@@ -184,6 +216,8 @@ export class PersonaClient {
                 else
                     resolve();
             };
+            // Lets close() settle an in-flight connect instead of stranding its awaiter.
+            this.settleConnect = settle;
             ws.addEventListener('message', ev => {
                 const data = ev.data;
                 if (typeof data !== 'string')
@@ -205,34 +239,47 @@ export class PersonaClient {
                 this.serverInfo = null;
                 this.failPending(new Error('connection closed'));
                 settle(new Error('connection closed'));
+                const code = ev?.code ?? 1006;
+                const reason = ev?.reason ?? '';
+                const terminal = code === CLOSE_KEY_REVOKED || code === CLOSE_FORCE_DISCONNECTED;
                 if (this.closedByUser) {
                     this.setState('closed');
-                    return;
+                    return; // a close() the caller issued is not news
                 }
-                const code = ev?.code;
-                if (code === CLOSE_KEY_REVOKED || code === CLOSE_FORCE_DISCONNECTED) {
+                if (terminal) {
                     // 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');
+                    // onClose is the richer signal; the warning stays for clients without it.
+                    if (this.opts.onClose === undefined) {
+                        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') {
+                else if (!this.opts.reconnect || this.state === 'connecting') {
                     // Initial connect failed: report to the caller instead of retrying forever.
                     this.setState('closed');
-                    return;
                 }
-                this.scheduleReconnect();
+                else {
+                    this.scheduleReconnect();
+                }
+                // Fired last: everything is settled, so a close() inside the callback is safe.
+                this.opts.onClose?.({ code, reason, terminal });
             });
             ws.addEventListener('error', () => {
                 // The close event follows and carries the terminal handling.
             });
         });
+        const tracked = attempt.finally(() => {
+            if (this.connectPromise === tracked)
+                this.connectPromise = null;
+        });
+        this.connectPromise = tracked;
+        return tracked;
     }
     onHello(protocol, app) {
         this.serverInfo = { protocol, app };

package/dist/index.d.ts

@@ -1,8 +1,14 @@
-export * from './client.ts';
-export * from './envelope.ts';
-export * from './errors.ts';
-export * from './events.ts';
-export * from './methods.ts';
-export * from './protocol.ts';
-export * from './schemas.ts';
-export * from './types.ts';
+export * from './client/address.ts';
+export * from './client/client.ts';
+export * from './values/effect-schema.ts';
+export * from './values/guards.ts';
+export * from './values/labels.ts';
+export * from './values/limits.ts';
+export * from './values/locale.ts';
+export * from './wire/envelope.ts';
+export * from './wire/errors.ts';
+export * from './wire/events.ts';
+export * from './wire/methods.ts';
+export * from './wire/protocol.ts';
+export * from './wire/schemas.ts';
+export * from './wire/types.ts';

package/dist/index.js

@@ -1,8 +1,16 @@
-export * from "./client.js";
-export * from "./envelope.js";
-export * from "./errors.js";
-export * from "./events.js";
-export * from "./methods.js";
-export * from "./protocol.js";
-export * from "./schemas.js";
-export * from "./types.js";
+// One flat public surface over the three layers: the wire contract, the client,
+// and the values/registries every Persona app must agree on.
+export * from "./client/address.js";
+export * from "./client/client.js";
+export * from "./values/effect-schema.js";
+export * from "./values/guards.js";
+export * from "./values/labels.js";
+export * from "./values/limits.js";
+export * from "./values/locale.js";
+export * from "./wire/envelope.js";
+export * from "./wire/errors.js";
+export * from "./wire/events.js";
+export * from "./wire/methods.js";
+export * from "./wire/protocol.js";
+export * from "./wire/schemas.js";
+export * from "./wire/types.js";

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

@@ -0,0 +1,22 @@
+import type { SceneEffects } from '../wire/types.ts';
+/** Slider + healing metadata for one numeric effect parameter. */
+export interface EffectParamSpec {
+    default: number;
+    min: number;
+    max: number;
+    step: number;
+    /** Fixed readout decimals; omitted follows FxSlider's step-based rule. */
+    digits?: number;
+    /** Appended to the readout (`s`, `px`, …). */
+    unit?: string;
+}
+/** Keys of {@link SceneEffects} that follow the `{ enabled } + numeric params` pattern. */
+export type ToggleEffectKey = {
+    [K in keyof SceneEffects]: SceneEffects[K] extends {
+        enabled: boolean;
+    } ? K : never;
+}[keyof SceneEffects];
+export declare const EFFECT_SPECS: Record<ToggleEffectKey, Readonly<Record<string, EffectParamSpec>>>;
+export declare const TOGGLE_EFFECT_KEYS: readonly ToggleEffectKey[];
+/** Every registry effect at its defaults — the derived half of a fresh {@link SceneEffects}. */
+export declare function defaultToggleEffects(): Pick<SceneEffects, ToggleEffectKey>;

package/dist/values/effect-schema.js

@@ -0,0 +1,90 @@
+// 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; label it in the panel's effect-labels.ts (parity-checked).
+//   3. Implement its stage under apps/desktop/src/renderer/vrm/webgpu/effects/.
+//   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.
+// 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 = {
+    color: {
+        hue: { default: 0, min: -180, max: 180, step: 1 },
+        saturation: { default: 0, min: -1, max: 1, step: 0.01 },
+        brightness: { default: 0, min: -1, max: 1, step: 0.01 },
+        contrast: { default: 0, min: -1, max: 1, step: 0.01 },
+    },
+    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 },
+    },
+    dof: {
+        bokehScale: { default: 2, min: 0, max: 8, step: 0.01 },
+        /** World metres of acceptably-sharp depth around the focus plane. */
+        focusRange: { default: 2, min: 0.1, max: 10, step: 0.01 },
+    },
+    chromaticAberration: {
+        strength: { default: 0.2, min: 0, max: 1, step: 0.01 },
+    },
+    grain: {
+        strength: { default: 0.3, min: 0, max: 1, step: 0.01 },
+    },
+    vignette: {
+        darkness: { default: 0.5, min: 0, max: 1, step: 0.01 },
+        offset: { default: 0.5, min: 0, max: 1, step: 0.01 },
+    },
+    pixelate: {
+        // Pixels per block; past ~64 the frame is a handful of tiles.
+        granularity: { default: 8, min: 2, max: 64, step: 1 },
+    },
+    // Canvas UI Glitch ranges, verbatim — the effect is a port and should read the same.
+    glitch: {
+        intensity: { default: 1, min: 0, max: 2, step: 0.05 },
+        speed: { default: 1, min: 0.1, max: 4, step: 0.1, digits: 1, unit: '×' },
+        interval: { default: 3, min: 0, max: 8, step: 0.25, digits: 2, unit: 's' },
+        duration: { default: 0.4, min: 0.1, max: 2, step: 0.05, digits: 2, unit: 's' },
+        slices: { default: 24, min: 4, max: 80, step: 1 },
+        shift: { default: 30, min: 0, max: 120, step: 2, unit: 'px' },
+        rgbShift: { default: 4, min: 0, max: 20, step: 0.5, digits: 1, unit: 'px' },
+        blocks: { default: 0.5, min: 0, max: 1, step: 0.02 },
+        noise: { default: 0.35, min: 0, max: 1, step: 0.02 },
+    },
+    // Canvas UI Droplets ranges, verbatim where the option carried over; direction
+    // and glints are ours (rotatable field, transparent-window visibility).
+    droplets: {
+        intensity: { default: 0.5, min: 0, max: 1.25, step: 0.05 },
+        speed: { default: 1, min: 0, max: 3, step: 0.1, digits: 1, unit: '×' },
+        scale: { default: 0.4, min: 0.4, max: 2.5, step: 0.05 },
+        dropWidth: { default: 1, min: 0.4, max: 1.5, step: 0.05 },
+        dropLength: { default: 1, min: 0.4, max: 2.5, step: 0.05 },
+        refraction: { default: 0.2, min: 0, max: 3, step: 0.1, digits: 1 },
+        fallSpeed: { default: 1, min: 0, max: 3, step: 0.1, digits: 1, unit: '×' },
+        direction: { default: 0, min: -180, max: 180, step: 1, unit: '°' },
+        wiggle: { default: 1, min: 0, max: 2, step: 0.1, digits: 1 },
+        staticDrops: { default: 0.2, min: 0, max: 3, step: 0.1, digits: 1 },
+        glints: { default: 0.6, min: 0, max: 1, step: 0.05 },
+    },
+};
+// Object.keys widens to string[]; the annotation above pins the keys to exactly ToggleEffectKey.
+export const TOGGLE_EFFECT_KEYS = Object.keys(EFFECT_SPECS);
+/** Every registry effect at its defaults — the derived half of a fresh {@link SceneEffects}. */
+export function defaultToggleEffects() {
+    const out = {};
+    for (const key of TOGGLE_EFFECT_KEYS) {
+        const fx = { enabled: false };
+        for (const [param, spec] of Object.entries(EFFECT_SPECS[key]))
+            fx[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;
+}

package/dist/values/guards.d.ts

@@ -0,0 +1,8 @@
+/** Plain-object check: object, non-null, and not an array. */
+export declare function isRecord(v: unknown): v is Record<string, unknown>;
+/** Finite-number type guard (rejects NaN and ±Infinity). */
+export declare function isFiniteNumber(v: unknown): v is number;
+/** The value when it is a finite number, else `fallback`. */
+export declare function finiteOr(v: unknown, fallback: number): number;
+/** The string when it has non-whitespace content (returned untrimmed), else null. */
+export declare function nonEmptyString(v: unknown): string | null;

package/dist/values/guards.js

@@ -0,0 +1,17 @@
+// The tiny type guards the SDK's parsers and every healing pass share.
+/** Plain-object check: object, non-null, and not an array. */
+export function isRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+/** Finite-number type guard (rejects NaN and ±Infinity). */
+export function isFiniteNumber(v) {
+    return typeof v === 'number' && Number.isFinite(v);
+}
+/** The value when it is a finite number, else `fallback`. */
+export function finiteOr(v, fallback) {
+    return isFiniteNumber(v) ? v : fallback;
+}
+/** The string when it has non-whitespace content (returned untrimmed), else null. */
+export function nonEmptyString(v) {
+    return typeof v === 'string' && v.trim() !== '' ? v : null;
+}

package/dist/values/labels.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Display label for a model-relative motion/expression/animation file: the
+ * basename with its format extension stripped. Cubism entries carry no `Name`,
+ * so the basename is the only identifier there is.
+ */
+export declare function motionLabel(file: string): string;

package/dist/values/labels.js

@@ -0,0 +1,9 @@
+/**
+ * Display label for a model-relative motion/expression/animation file: the
+ * basename with its format extension stripped. Cubism entries carry no `Name`,
+ * so the basename is the only identifier there is.
+ */
+export function motionLabel(file) {
+    const base = file.split(/[\\/]/).pop() ?? file;
+    return base.replace(/\.motion3\.json$|\.exp3\.json$|\.vrma$|\.json$/i, '') || base;
+}

package/dist/values/limits.d.ts

@@ -0,0 +1,62 @@
+import type { Attach, ModelFormat, MToonTuning, ObjectContent, ObjectSpace, SceneLight, SceneLightType, ScreenPlacement, VrmPlacement } from '../wire/types.ts';
+export declare function clamp(v: number, min: number, max: number): number;
+/** Clamp to the unit interval. */
+export declare function clamp01(v: number): number;
+export declare const DEFAULT_LIVE2D_PLACEMENT: ScreenPlacement;
+export declare const DEFAULT_VRM_PLACEMENT: VrmPlacement;
+/** Scene colors heal to 6-digit hex. */
+export declare const SCENE_COLOR_RE: RegExp;
+/** Drop the alpha byte a picker's hex input can produce (`#rrggbbaa` → `#rrggbb`). */
+export declare function opaqueHex(hex: string): string;
+export declare const SCENE_LIGHT_INTENSITY_MAX = 2;
+/**
+ * Point lights decay physically (1/d²), so reach rides on power the way Blender's
+ * does: 20 stays visible to ~10 m where 2 self-extinguishes by ~5. The other
+ * types have no falloff to overcome — 20 would just blow the stage out.
+ */
+export declare const SCENE_LIGHT_POINT_INTENSITY_MAX = 20;
+/** Intensity ceiling for a light of `type` — one source for the slider and scene healing. */
+export declare function sceneLightIntensityMax(type: SceneLightType): number;
+export declare const LIVE2D_SCALE_MIN = 0.1;
+export declare const LIVE2D_SCALE_MAX = 24;
+export declare const VRM_SCALE_MIN = 0.05;
+export declare const VRM_SCALE_MAX = 10;
+export declare const SCENE_LIGHT_RANGE_MAX = 20;
+/** Past this the 5-tap kernel spreads thin enough that its dither reads as noise. */
+export declare const SCENE_LIGHT_SHADOW_RADIUS_MAX = 16;
+/**
+ * Exp2 falloff is squared, so a stage measured in metres is fully socked in well
+ * before Unity's nominal 1 — this keeps the slider's useful band across its width.
+ */
+export declare const SCENE_FOG_DENSITY_MAX = 0.5;
+/** ×4 is +2 stops — enough to rescue an AgX-dimmed avatar without turning the slider to mush. */
+export declare const SCENE_EXPOSURE_MAX = 4;
+export declare const MTOON_RIM_MAX = 2;
+export declare const MTOON_OUTLINE_WIDTH_MAX = 2;
+/** HDR headroom: past ×1 the point is pushing emissive parts over the bloom threshold. */
+export declare const MTOON_EMISSIVE_MAX = 4;
+export declare function defaultMToonTuning(): MToonTuning;
+export declare const DEFAULT_LIGHT_AZIMUTH_DEG = 45;
+export declare const DEFAULT_LIGHT_ELEVATION_DEG: number;
+/** A fresh light of `type`, at the defaults that read sensibly for that type. */
+export declare function defaultSceneLightOf(type: SceneLightType): SceneLight;
+export declare const PLACE_2D_SCALE_MIN = 0.01;
+export declare const PLACE_2D_SCALE_MAX = 50;
+export declare const PLACE_3D_SCALE_MIN = 0.01;
+export declare const PLACE_3D_SCALE_MAX = 100;
+/** A prop is a mesh, so it only exists in the three.js scene; every other kind renders in both. */
+export declare function objectSupportsSpace(kind: ObjectContent['kind'], space: ObjectSpace): boolean;
+/**
+ * The one model format a space's objects can ride: the renderers never mix, and
+ * the three canvas always composites over the Pixi one, so a cross-space pin
+ * would z-fight by construction.
+ */
+export declare function attachableParentFormat(space: ObjectSpace): ModelFormat;
+export declare const DEFAULT_HEAD_ANGLE: NonNullable<Attach['headAngle']>;
+export declare const ATTACH_MULTIPLIER_MIN = -2;
+export declare const ATTACH_MULTIPLIER_MAX = 2;
+export declare const ATTACH_SMOOTHING_MAX = 50;
+export declare const DEFAULT_ELASTICITY: NonNullable<Attach['elasticity']>;
+export declare const ELASTICITY_STIFFNESS_MAX = 100;
+export declare const ELASTICITY_DAMPING_MAX = 10;
+export declare const ELASTICITY_MAX_SPEED_MAX = 100;

package/dist/values/limits.js

@@ -0,0 +1,98 @@
+export function clamp(v, min, max) {
+    return Math.min(max, Math.max(min, v));
+}
+/** Clamp to the unit interval. */
+export function clamp01(v) {
+    return v < 0 ? 0 : v > 1 ? 1 : v;
+}
+export const DEFAULT_LIVE2D_PLACEMENT = { x: 0, y: 0, scale: 1, rotation: 0 };
+export const DEFAULT_VRM_PLACEMENT = { x: 0, y: 0, z: 0, rotX: 0, rotY: 0, rotZ: 0, scale: 1 };
+/** Scene colors heal to 6-digit hex. */
+export const SCENE_COLOR_RE = /^#[0-9a-f]{6}$/i;
+/** Drop the alpha byte a picker's hex input can produce (`#rrggbbaa` → `#rrggbb`). */
+export function opaqueHex(hex) {
+    return /^#[0-9a-f]{8}$/i.test(hex) ? hex.slice(0, 7) : hex;
+}
+export const SCENE_LIGHT_INTENSITY_MAX = 2;
+/**
+ * Point lights decay physically (1/d²), so reach rides on power the way Blender's
+ * does: 20 stays visible to ~10 m where 2 self-extinguishes by ~5. The other
+ * types have no falloff to overcome — 20 would just blow the stage out.
+ */
+export const SCENE_LIGHT_POINT_INTENSITY_MAX = 20;
+/** Intensity ceiling for a light of `type` — one source for the slider and scene healing. */
+export function sceneLightIntensityMax(type) {
+    return type === 'point' ? SCENE_LIGHT_POINT_INTENSITY_MAX : SCENE_LIGHT_INTENSITY_MAX;
+}
+// Live2D bounds are the zoom clamp (zoom.ts re-exports these); VRM scales a world-space root.
+export const LIVE2D_SCALE_MIN = 0.1;
+export const LIVE2D_SCALE_MAX = 24;
+export const VRM_SCALE_MIN = 0.05;
+export const VRM_SCALE_MAX = 10;
+// Range only *cuts off* a point light — three's 1/d² decay has extinguished it
+// by ~18 m even at max intensity, so a slider past 20 changes nothing visible.
+export const SCENE_LIGHT_RANGE_MAX = 20;
+/** Past this the 5-tap kernel spreads thin enough that its dither reads as noise. */
+export const SCENE_LIGHT_SHADOW_RADIUS_MAX = 16;
+/**
+ * Exp2 falloff is squared, so a stage measured in metres is fully socked in well
+ * before Unity's nominal 1 — this keeps the slider's useful band across its width.
+ */
+export const SCENE_FOG_DENSITY_MAX = 0.5;
+/** ×4 is +2 stops — enough to rescue an AgX-dimmed avatar without turning the slider to mush. */
+export const SCENE_EXPOSURE_MAX = 4;
+export const MTOON_RIM_MAX = 2;
+export const MTOON_OUTLINE_WIDTH_MAX = 2;
+/** HDR headroom: past ×1 the point is pushing emissive parts over the bloom threshold. */
+export const MTOON_EMISSIVE_MAX = 4;
+export function defaultMToonTuning() {
+    return { shade: 1, shadingShift: 0, shadingToony: 0, giEqualization: 0, rim: 1, outlineWidth: 1, emissive: 1 };
+}
+// Ranges for toggle-style effect params live in effect-schema.ts (EFFECT_SPECS).
+// Angles at which lightDirection reproduces (1,1,1).normalize() — the app's original hardcoded light.
+export const DEFAULT_LIGHT_AZIMUTH_DEG = 45;
+export const DEFAULT_LIGHT_ELEVATION_DEG = (Math.asin(1 / Math.sqrt(3)) * 180) / Math.PI;
+/** A fresh light of `type`, at the defaults that read sensibly for that type. */
+export function defaultSceneLightOf(type) {
+    return {
+        id: crypto.randomUUID(),
+        type,
+        color: '#ffffff',
+        intensity: 1,
+        azimuth: DEFAULT_LIGHT_AZIMUTH_DEG,
+        elevation: DEFAULT_LIGHT_ELEVATION_DEG,
+        x: 0,
+        y: 1.4,
+        z: 1,
+        range: 10,
+        // A point light shadow is six cube faces, so it stays opt-in where a
+        // directional light's single depth pass can be on by default.
+        shadowQuality: type === 'directional' ? 'high' : 'off',
+        shadowRadius: 6,
+    };
+}
+export const PLACE_2D_SCALE_MIN = 0.01;
+export const PLACE_2D_SCALE_MAX = 50;
+export const PLACE_3D_SCALE_MIN = 0.01;
+export const PLACE_3D_SCALE_MAX = 100;
+/** A prop is a mesh, so it only exists in the three.js scene; every other kind renders in both. */
+export function objectSupportsSpace(kind, space) {
+    return kind === 'prop' ? space === '3d' : true;
+}
+/**
+ * The one model format a space's objects can ride: the renderers never mix, and
+ * the three canvas always composites over the Pixi one, so a cross-space pin
+ * would z-fight by construction.
+ */
+export function attachableParentFormat(space) {
+    return space === '2d' ? 'live2d' : 'vrm';
+}
+export const DEFAULT_HEAD_ANGLE = { multiplier: 1, smoothing: 15 };
+export const ATTACH_MULTIPLIER_MIN = -2;
+export const ATTACH_MULTIPLIER_MAX = 2;
+export const ATTACH_SMOOTHING_MAX = 50;
+// Warudo Attachable defaults and slider ceilings, verbatim.
+export const DEFAULT_ELASTICITY = { stiffness: 2, damping: 3, maxSpeed: 2 };
+export const ELASTICITY_STIFFNESS_MAX = 100;
+export const ELASTICITY_DAMPING_MAX = 10;
+export const ELASTICITY_MAX_SPEED_MAX = 100;

package/dist/values/locale.d.ts

@@ -0,0 +1,9 @@
+/** Locales shipped in the compiled catalogs (`pnpm i18n`). */
+export declare const LOCALES: readonly ["en", "ja", "zh-CN", "zh-TW"];
+export type Locale = (typeof LOCALES)[number];
+/** `ui.language` setting: an explicit locale, or follow the OS language. */
+export type LanguageSetting = 'system' | Locale;
+/** Native-language display names for the language picker (deliberately untranslated). */
+export declare const LOCALE_LABELS: Record<Locale, string>;
+/** Best supported locale for a BCP 47-ish tag: exact match first, then fuzzy per language. */
+export declare function matchLocaleTag(tag: string): Locale;

package/dist/values/locale.js

@@ -0,0 +1,21 @@
+/** Locales shipped in the compiled catalogs (`pnpm i18n`). */
+export const LOCALES = ['en', 'ja', 'zh-CN', 'zh-TW'];
+/** Native-language display names for the language picker (deliberately untranslated). */
+export const LOCALE_LABELS = {
+    en: 'English',
+    ja: '日本語',
+    'zh-CN': '简体中文',
+    'zh-TW': '繁體中文',
+};
+/** Best supported locale for a BCP 47-ish tag: exact match first, then fuzzy per language. */
+export function matchLocaleTag(tag) {
+    if (LOCALES.includes(tag))
+        return tag;
+    const t = tag.toLowerCase();
+    // Most systems/browsers report `zh-TW`/`zh-HK` with no `hant` subtag, so match the regions too.
+    if (t.startsWith('zh'))
+        return /hant|tw|hk|mo/.test(t) ? 'zh-TW' : 'zh-CN';
+    if (t.startsWith('ja'))
+        return 'ja';
+    return 'en';
+}

package/dist/{envelope.d.ts → wire/envelope.d.ts}

@@ -12,11 +12,7 @@ export interface RequestMessage<M extends MethodName = MethodName> {
 export interface HelloMessage {
     kind: 'hello';
     protocol: number;
-    app: {
-        name: string;
-        version: string;
-        platform: string;
-    };
+    app: AppInfo;
 }
 export interface ResponseMessage {
     kind: 'response';
@@ -37,6 +33,12 @@ export interface EventMessage<E extends EventName = EventName> {
 }
 export type ServerMessage = HelloMessage | ResponseMessage | ErrorMessage | EventMessage;
 export type ClientMessage = RequestMessage;
+/** The desktop app's identity, as `hello` reports it. */
+export interface AppInfo {
+    name: string;
+    version: string;
+    platform: string;
+}
 /**
  * Parse one inbound client frame. Returns the request, or an error code telling
  * the server what to answer: `parse-error` for junk bytes, `invalid-request`

package/dist/{envelope.js → wire/envelope.js}

@@ -1,8 +1,6 @@
+import { isRecord } from "../values/guards.js";
 import { isApiErrorCode } from "./errors.js";
 import { isEventName } from "./events.js";
-function isRecord(v) {
-    return typeof v === 'object' && v !== null && !Array.isArray(v);
-}
 /**
  * Parse one inbound client frame. Returns the request, or an error code telling
  * the server what to answer: `parse-error` for junk bytes, `invalid-request`

package/dist/{protocol.d.ts → wire/protocol.d.ts}

@@ -3,10 +3,14 @@ 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;
+/** Default host clients dial: the server binds loopback unless LAN is opted in. */
+export declare const DEFAULT_API_HOST = "127.0.0.1";
 /** 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;
+/** Standard going-away code the server sends when it stops; reconnecting is expected once it returns. */
+export declare const CLOSE_SERVER_STOPPING = 1001;
 /** 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 → wire/protocol.js}

@@ -2,10 +2,14 @@
 export const PROTOCOL_VERSION = 1;
 /** Default port the Persona API server listens on (user-configurable in the app). */
 export const DEFAULT_API_PORT = 25034;
+/** Default host clients dial: the server binds loopback unless LAN is opted in. */
+export const DEFAULT_API_HOST = '127.0.0.1';
 /** 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;
+/** Standard going-away code the server sends when it stops; reconnecting is expected once it returns. */
+export const CLOSE_SERVER_STOPPING = 1001;
 /** 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.js → wire/schemas.js}

@@ -1,12 +1,10 @@
 import * as z from 'zod';
+import { isRecord } from "../values/guards.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
 // panel). Fields marked z.custom are deliberately gated shallowly here because
 // the app heals them into shape server-side.
-function isRecord(v) {
-    return typeof v === 'object' && v !== null && !Array.isArray(v);
-}
 const nonEmpty = z.string().min(1);
 export const InjectTargetSchema = z.object({
     type: z.enum(['input', 'live2d-param', 'vrm-expression']),

package/dist/{types.d.ts → wire/types.d.ts}

@@ -345,6 +345,32 @@ export interface ScenePixelate {
     enabled: boolean;
     granularity: number;
 }
+/** Rain droplets running down a glass pane in front of the frame, refracting it. */
+export interface SceneDroplets {
+    enabled: boolean;
+    /** How much rain falls, from a light drizzle to a downpour (0 to 1.25). */
+    intensity: number;
+    /** Animation speed multiplier. */
+    speed: number;
+    /** Size of the droplet pattern. Higher means smaller drops. */
+    scale: number;
+    /** Width of the droplets and their trails. */
+    dropWidth: number;
+    /** How elongated the falling droplets are. */
+    dropLength: number;
+    /** How strongly droplets refract the frame behind them. */
+    refraction: number;
+    /** How fast the running drops slide down. */
+    fallSpeed: number;
+    /** Fall direction in degrees: 0 falls down, ±90 sideways, ±180 up. */
+    direction: number;
+    /** Horizontal wiggle of the running drops. */
+    wiggle: number;
+    /** Multiplier for the small static droplets. */
+    staticDrops: number;
+    /** Specular glint on drops where the frame is transparent, so rain reads over the desktop (0 to 1). */
+    glints: number;
+}
 /**
  * Post-processing over the rendered 3D frame. Everything off skips the effect
  * chain entirely. Deliberately flat: every toggle-plus-numbers effect sits at
@@ -364,6 +390,7 @@ export interface SceneEffects {
     dof: SceneDepthOfField;
     pixelate: ScenePixelate;
     glitch: SceneGlitch;
+    droplets: SceneDroplets;
 }
 /**
  * Image-based lighting for the 3D stage: an environment map, whether to show it
@@ -476,8 +503,11 @@ export interface ExpressionPersistence {
     enabled: boolean;
     saved: string[];
 }
-export type TrackingSourceId = 'vts-ios' | 'vts-ios-native' | 'ifacialmocap';
-export type PoseSourceId = 'vmc';
+export declare const TRACKING_SOURCE_IDS: readonly ["vts-ios", "vts-ios-native", "ifacialmocap"];
+export type TrackingSourceId = (typeof TRACKING_SOURCE_IDS)[number];
+/** Body-pose protocols. Every one so far is UDP with a configurable port. */
+export declare const POSE_SOURCE_IDS: readonly ["vmc"];
+export type PoseSourceId = (typeof POSE_SOURCE_IDS)[number];
 export type TrackingStatus = 'off' | 'waiting' | 'tracking' | 'no-face';
 export type PoseStatus = 'off' | 'waiting' | 'tracking';
 export declare const EFFECTS_QUALITY_LEVELS: readonly ["low", "medium", "high"];

package/dist/{types.js → wire/types.js}

@@ -7,6 +7,10 @@
  * directional light covers with one map, so it gets the smaller of the pair.
  */
 export const SHADOW_QUALITY_LEVELS = ['off', 'low', 'medium', 'high', 'extra'];
+// ---- Settings ------------------------------------------------------------------
+export const TRACKING_SOURCE_IDS = ['vts-ios', 'vts-ios-native', 'ifacialmocap'];
+/** Body-pose protocols. Every one so far is UDP with a configurable port. */
+export const POSE_SOURCE_IDS = ['vmc'];
 export const EFFECTS_QUALITY_LEVELS = ['low', 'medium', 'high'];
 /**
  * Accepted values for `performance.fpsLimit`; 0 = unlimited. Anything else is snapped

package/package.json

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