@laplace.live/persona-sdk 0.6.0 → 0.8.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,30 @@
+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[];
+/**
+ * Registry effects that render as scene geometry inside the scene pass rather
+ * than composing into the post chain. A new scene-space effect must join this
+ * list, or its toggle needlessly forces the post path on and rebuilds the graph.
+ */
+export declare const SCENE_SPACE_EFFECT_KEYS: readonly ToggleEffectKey[];
+/** Registry effects the post chain composes — {@link TOGGLE_EFFECT_KEYS} minus the scene-space ones. */
+export declare const POST_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,111 @@
+// 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/.
+//      Scene-space effects (geometry, not a post stage — e.g. snow) also join
+//      SCENE_SPACE_EFFECT_KEYS below.
+//   4. Drop one `<EffectSection>` line into a panel section.
+// Effects that don't fit the pattern (tone mapping, exposure, LUT, shockwave)
+// stay bespoke — extend the pattern before special-casing a third shape.
+//
+// Plain data only — no React, no lingui (labels live in the panel's
+// effect-labels.ts) — so main-process healing and API plugins import it freely.
+// 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 },
+    },
+    // three's webgpu_compute_particles_snow, rescaled to the stage's metre-scale
+    // world. `amount` is the live instance count; buffers allocate the max once.
+    snow: {
+        amount: { default: 2000, min: 100, max: 10000, step: 100 },
+        speed: { default: 1, min: 0, max: 3, step: 0.1, digits: 1, unit: '×' },
+        wind: { default: 0, min: -3, max: 3, step: 0.1, digits: 1, unit: 'm/s' },
+        sway: { default: 1, min: 0, max: 3, step: 0.1, digits: 1 },
+        size: { default: 1, min: 0.4, max: 3, step: 0.05 },
+        melt: { default: 6, min: 0.5, max: 30, step: 0.5, digits: 1, unit: 's' },
+        opacity: { default: 1, min: 0.1, 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);
+/**
+ * Registry effects that render as scene geometry inside the scene pass rather
+ * than composing into the post chain. A new scene-space effect must join this
+ * list, or its toggle needlessly forces the post path on and rebuilds the graph.
+ */
+export const SCENE_SPACE_EFFECT_KEYS = ['snow'];
+/** Registry effects the post chain composes — {@link TOGGLE_EFFECT_KEYS} minus the scene-space ones. */
+export const POST_EFFECT_KEYS = TOGGLE_EFFECT_KEYS.filter(key => !SCENE_SPACE_EFFECT_KEYS.includes(key));
+/** 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,73 @@
+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;
+/** The point disk's 32 fixed taps stay dense across a far wider penumbra than 5 dithered ones. */
+export declare const SCENE_LIGHT_POINT_SHADOW_RADIUS_MAX = 32;
+/** Shadow softness (PCF disk radius, in shadow-map texels) ceiling for a light of `type`. */
+export declare function sceneLightShadowRadiusMax(type: SceneLightType): number;
+/**
+ * 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;
+export declare const STORAGE_KEY_MAX_LENGTH = 128;
+/** Ceiling on one value's JSON-serialized length (UTF-16 units, `JSON.stringify(v).length`). */
+export declare const STORAGE_VALUE_MAX_LENGTH: number;
+/** Keys one API key may hold; a `storage.set` that would exceed it answers `invalid-state`. */
+export declare const STORAGE_KEYS_MAX = 256;
+/** `speech.play` URL ceiling — sized for a ~40 s WAV as a base64 `data:audio/*` payload. */
+export declare const SPEECH_URL_MAX_LENGTH = 8000000;