@laplace.live/persona-sdk 0.18.1 → 1.0.0

package/dist/wire/schemas.d.ts

@@ -22,6 +22,9 @@ export declare const InjectEntrySchema: z.ZodObject<{
     weight: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 export declare const SettingsPatchSchema: z.ZodObject<{
+    controller: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
     window: z.ZodOptional<z.ZodObject<{
         alwaysOnTop: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>>;
@@ -33,13 +36,39 @@ export declare const SettingsPatchSchema: z.ZodObject<{
         fpsLimit: z.ZodOptional<z.ZodNumber>;
         selectionOutline: z.ZodOptional<z.ZodBoolean>;
         effectsQuality: z.ZodOptional<z.ZodEnum<{
+            high: "high";
             low: "low";
             medium: "medium";
-            high: "high";
+        }>>;
+        renderScale: z.ZodOptional<z.ZodNumber>;
+        live2dEngine: z.ZodOptional<z.ZodEnum<{
+            pixi: "pixi";
+            three: "three";
         }>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export declare const requestSchemas: {
+    'registry.thumbnail': z.ZodObject<{
+        kind: z.ZodEnum<{
+            model: "model";
+            asset: "asset";
+        }>;
+        id: z.ZodString;
+    }, z.core.$strip>;
+    'controller.rename': z.ZodObject<{
+        slot: z.ZodNumber;
+        name: z.ZodString;
+    }, z.core.$strip>;
+    'controller.setDeadZone': z.ZodObject<{
+        slot: z.ZodNumber;
+        deadZone: z.ZodNumber;
+    }, z.core.$strip>;
+    'controller.remove': z.ZodObject<{
+        slot: z.ZodNumber;
+    }, z.core.$strip>;
+    'controller.assign': z.ZodObject<{
+        slot: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>;
     'scene.get': z.ZodObject<{
         sceneId: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
@@ -97,9 +126,11 @@ export declare const requestSchemas: {
     }, z.core.$strip>;
     'tracking.addSource': z.ZodObject<{
         kind: z.ZodEnum<{
-            "vts-ios": "vts-ios";
+            "persona-ios": "persona-ios";
             ifacialmocap: "ifacialmocap";
+            "vts-ios": "vts-ios";
             vmc: "vmc";
+            mocopi: "mocopi";
         }>;
         name: z.ZodOptional<z.ZodString>;
         phoneIp: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -121,17 +152,20 @@ export declare const requestSchemas: {
     'asset.register': z.ZodObject<{
         path: z.ZodString;
         want: z.ZodOptional<z.ZodEnum<{
+            lut: "lut";
             image: "image";
             video: "video";
             prop: "prop";
             ibl: "ibl";
-            lut: "lut";
             animation: "animation";
             cameraMotion: "cameraMotion";
         }>>;
     }, z.core.$strip>;
     'settings.patch': z.ZodObject<{
         settings: z.ZodObject<{
+            controller: z.ZodOptional<z.ZodObject<{
+                enabled: z.ZodOptional<z.ZodBoolean>;
+            }, z.core.$strip>>;
             window: z.ZodOptional<z.ZodObject<{
                 alwaysOnTop: z.ZodOptional<z.ZodBoolean>;
             }, z.core.$strip>>;
@@ -143,9 +177,14 @@ export declare const requestSchemas: {
                 fpsLimit: z.ZodOptional<z.ZodNumber>;
                 selectionOutline: z.ZodOptional<z.ZodBoolean>;
                 effectsQuality: z.ZodOptional<z.ZodEnum<{
+                    high: "high";
                     low: "low";
                     medium: "medium";
-                    high: "high";
+                }>>;
+                renderScale: z.ZodOptional<z.ZodNumber>;
+                live2dEngine: z.ZodOptional<z.ZodEnum<{
+                    pixi: "pixi";
+                    three: "three";
                 }>>;
             }, z.core.$strip>>;
         }, z.core.$strip>;
@@ -155,8 +194,9 @@ export declare const requestSchemas: {
     }, z.core.$strip>;
     'tracking.setSource': z.ZodObject<{
         source: z.ZodEnum<{
-            "vts-ios": "vts-ios";
+            "persona-ios": "persona-ios";
             ifacialmocap: "ifacialmocap";
+            "vts-ios": "vts-ios";
         }>;
     }, z.core.$strip>;
     'pose.setEnabled': z.ZodObject<{
@@ -165,6 +205,7 @@ export declare const requestSchemas: {
     'pose.setSource': z.ZodObject<{
         source: z.ZodEnum<{
             vmc: "vmc";
+            mocopi: "mocopi";
         }>;
     }, z.core.$strip>;
     'pose.setPort': z.ZodObject<{

package/dist/wire/schemas.js

@@ -1,4 +1,5 @@
 import * as z from 'zod';
+import { CONTROLLER_DEAD_ZONE_MAX } from "../values/controller.js";
 import { isRecord } from "../values/guards.js";
 import { SPEECH_URL_MAX_LENGTH, STORAGE_KEY_MAX_LENGTH, STORAGE_VALUE_MAX_LENGTH } from "../values/limits.js";
 import { ASSET_KINDS, POSE_SOURCE_IDS, TRACKING_SOURCE_IDS, TRACKING_SOURCE_KINDS } from "./types.js";
@@ -19,6 +20,7 @@ export const InjectEntrySchema = InjectTargetSchema.extend({
     weight: z.number().min(0).max(1).optional(),
 });
 export const SettingsPatchSchema = z.object({
+    controller: z.object({ enabled: z.boolean().optional() }).optional(),
     window: z.object({ alwaysOnTop: z.boolean().optional() }).optional(),
     ui: z.object({ trayVisible: z.boolean().optional() }).optional(),
     performance: z
@@ -27,6 +29,8 @@ export const SettingsPatchSchema = z.object({
         fpsLimit: z.number().optional(),
         selectionOutline: z.boolean().optional(),
         effectsQuality: z.enum(['high', 'medium', 'low']).optional(),
+        renderScale: z.number().optional(),
+        live2dEngine: z.enum(['pixi', 'three']).optional(),
     })
         .optional(),
 });
@@ -52,6 +56,14 @@ const speechUrl = z
     }
 }, 'url must be http(s) or data:audio/*');
 export const requestSchemas = {
+    'registry.thumbnail': z.object({ kind: z.enum(['model', 'asset']), id: nonEmpty }),
+    'controller.rename': z.object({ slot: z.number().int().positive(), name: z.string() }),
+    'controller.setDeadZone': z.object({
+        slot: z.number().int().positive(),
+        deadZone: z.number().min(0).max(CONTROLLER_DEAD_ZONE_MAX),
+    }),
+    'controller.remove': z.object({ slot: z.number().int().positive() }),
+    'controller.assign': z.object({ slot: z.number().int().positive().nullable() }),
     'scene.get': z.object({ sceneId: nonEmpty.optional() }),
     'scene.activate': z.object({ sceneId: nonEmpty }),
     'scene.duplicate': z.object({ sceneId: nonEmpty }),

package/dist/wire/types.d.ts

@@ -1,4 +1,6 @@
+import type { ControllerConfig } from '../values/controller.ts';
 import { type ArkitInputName } from '../values/arkit.ts';
+import { type BaseControllerInputName, type ControllerInputName, type ControllerMovementConfig } from '../values/controller.ts';
 export type ModelFormat = 'live2d' | 'vrm';
 /** Where an item came from: shipped with the app, or added by the user. */
 export type ContentOrigin = 'bundled' | 'user';
@@ -44,6 +46,8 @@ export interface AssetRef extends ContentRef {
     /** What the extension makes it — an object created from it starts on this kind. */
     kind: AssetKind;
     exists: boolean;
+    /** Source basename, with no directory. Absent on older hosts. */
+    file?: string;
 }
 /**
  * Content metadata decoupled from any on-disk file — local registry entries and
@@ -140,8 +144,10 @@ export interface SceneModelItem {
      * A dangling or disabled id behaves as null. One source may track several instances (mirroring).
      */
     faceSourceId: string | null;
-    /** Body source (vmc) tracking this instance; null = its pose is untracked. New instances bind to each channel's default source. */
+    /** Body source tracking this instance; null = its pose is untracked. New instances bind to each channel's default source. */
     poseSourceId: string | null;
+    /** Opt-in controller movement, independent of parameter/bone bindings; disabled by default. */
+    controllerMovement: ControllerMovementConfig;
     live2d: ScreenPlacement;
     vrm: VrmPlacement;
     idleAnimation: boolean;
@@ -188,6 +194,8 @@ export type ObjectContent = {
     css: string;
     /** 2D only: composited behind or in front of the whole stage, not interleaved with other layers. */
     layer: WebLayer;
+    /** Close the page while the object is hidden and reload it on show, as an OBS browser source can. */
+    shutdownWhenHidden: boolean;
 } | {
     kind: 'capture';
     source: CaptureKind;
@@ -602,24 +610,6 @@ export type ToggleEffectKey = {
         enabled: boolean;
     } ? K : never;
 }[keyof SceneEffects];
-/**
- * One user-authored effect's placement in a scene. Deliberately a sibling of
- * {@link SceneEffects} rather than a key inside it: `ToggleEffectKey` is derived
- * from that interface, and healing, defaults, hotkey snapshots and the panel all
- * iterate it as a closed compile-time union. Runtime keys in there would erase
- * that guarantee for the built-in effects too.
- */
-export interface SceneCustomEffect {
-    /** Folder name under the config home's `effects/` dir — stable id and module location. */
-    slug: string;
-    enabled: boolean;
-    /**
-     * Author-declared values, keyed by the manifest's param names. Untyped by
-     * construction: the specs arrive from disk at runtime, so these are validated
-     * against the installed manifest rather than checked at compile time.
-     */
-    params: Record<string, number | boolean | string>;
-}
 /**
  * A 3D set's own suggested look — the fog and post settings it was authored against,
  * read from its root `LAPLACE_environment` extension and held on the scene for every client.
@@ -681,14 +671,6 @@ export interface SceneEnvironment {
      * switched off. Healing lists every switched-on effect, so a patch that switches one on adds its layer.
      */
     effectLayers: ToggleEffectKey[];
-    /**
-     * User-authored effects, in the order they compose. They run as a group at one
-     * fixed point in the post chain — after grading and the screen-space warps,
-     * before grain and vignette — so the built-in composition order stays fixed.
-     * An entry whose effect is not installed here is kept, not dropped: it would
-     * cost the user their tuning on a machine that simply lacks the folder.
-     */
-    customEffects: SceneCustomEffect[];
 }
 export interface Scene {
     id: string;
@@ -728,11 +710,13 @@ export interface ScenePatch {
  * App-level features a client gates on (never version-sniff): `hello` and
  * `app.info` report them — the per-app mirror of {@link InstanceRuntime.capabilities}.
  */
-export declare const APP_CAPABILITIES: readonly ["storage", "speech", "shortcuts"];
+export declare const APP_CAPABILITIES: readonly ["storage", "speech", "shortcuts", "controllers", "model-editing", "asset-inspection"];
 export type AppCapability = (typeof APP_CAPABILITIES)[number];
 export declare function isAppCapability(v: unknown): v is AppCapability;
 /** What a loaded model instance can do; absent capabilities answer `unsupported-for-format`. */
 export type InstanceCapability = 'motions' | 'expressions' | 'placement-2d' | 'placement-3d' | 'mtoon' | 'idle-clips' | 'pose' | 'live2d-params'
+/** `instance.setBreath`; the idle breathing loop is Cubism's, so VRM lacks it. */
+ | 'breath'
 /** `expression.setWeight`; Cubism expressions carry no user-settable weight, so Live2D lacks it. */
  | 'expression-weights'
 /** `speech.play` lip-sync; engine-dependent, so gate on the runtime, not the format. */
@@ -752,6 +736,8 @@ export interface InstanceRuntime {
     capabilities: InstanceCapability[];
 }
 export interface MotionGroup {
+    /** Whether this group loops; absent on older hosts. */
+    looping?: boolean;
     group: string;
     files: string[];
 }
@@ -776,20 +762,7 @@ export interface AnchorOption {
     anchor: AttachAnchor;
     label: string;
 }
-/**
- * Panel-style model info block. Format-specific fields mirror the app's `ModelInfo`.
- * `format` stays the union's discriminant here — this is a runtime diagnostic, not
- * content metadata, so it does not follow {@link ContentRef}'s `kind`.
- */
-export interface ModelInfo {
-    format: ModelFormat;
-    name: string;
-    origin: ContentOrigin;
-    file: string;
-    loadMs: number;
-    /** Format-specific details (canvas/params/textures for Live2D, spec/bones for VRM). */
-    [key: string]: unknown;
-}
+export type { ModelInfo } from '../values/model-info.ts';
 export interface Hotkey {
     id: string;
     name: string;
@@ -836,17 +809,17 @@ export interface ExpressionPersistence {
 export type JsonValue = string | number | boolean | null | JsonValue[] | {
     [key: string]: JsonValue;
 };
-export declare const TRACKING_SOURCE_IDS: readonly ["vts-ios", "ifacialmocap"];
+export declare const TRACKING_SOURCE_IDS: readonly ["persona-ios", "ifacialmocap", "vts-ios"];
 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 declare const POSE_SOURCE_IDS: readonly ["vmc", "mocopi"];
 export type PoseSourceId = (typeof POSE_SOURCE_IDS)[number];
 export type TrackingStatus = 'off' | 'waiting' | 'tracking' | 'no-face';
 export type PoseStatus = 'off' | 'waiting' | 'tracking';
-/** Every protocol a tracking source instance can speak; face kinds plus the body (vmc) kind. */
-export declare const TRACKING_SOURCE_KINDS: readonly ["vts-ios", "ifacialmocap", "vmc"];
+/** Every protocol a tracking source instance can speak; face and body kinds. */
+export declare const TRACKING_SOURCE_KINDS: readonly ["persona-ios", "ifacialmocap", "vts-ios", "vmc", "mocopi"];
 export type TrackingSourceKind = (typeof TRACKING_SOURCE_KINDS)[number];
-/** Whether a source kind feeds the face channel (vmc is the body channel). */
+/** Whether a source kind feeds the face channel. */
 export declare function isFaceSourceKind(kind: TrackingSourceKind): kind is TrackingSourceId;
 /**
  * One configured tracking source instance. Several can run at once — one per person —
@@ -860,12 +833,24 @@ export interface TrackingSourceConfig {
     enabled: boolean;
     /**
      * Face kinds: accept only this device/sender IP; null accepts any sender not claimed
-     * by a pinned instance of the same kind. Ignored by vmc (its senders pick the port).
+     * by a pinned instance of the same kind. Ignored by body sources (their senders pick the port).
      */
     phoneIp: string | null;
-    /** vmc only: the UDP port this instance listens on. Null on face kinds — they bind per protocol. */
+    /**
+     * The UDP port this instance listens on: vmc, mocopi, and ifacialmocap (its receive port — the phone's
+     * Send Port must match). Null on persona-ios and vts-ios, whose ports the protocol fixes.
+     */
     port: number | null;
 }
+/** Whether a source feeds the body channel — the narrowing counterpart of `isFaceSourceKind`. */
+export declare function isPoseSource(source: TrackingSourceConfig): source is TrackingSourceConfig & {
+    kind: PoseSourceId;
+};
+/**
+ * Whether another source already holds `port` and would contend for it. iFacialMocap instances
+ * share one socket per port (frames demux by phone); every other pairing EADDRINUSEs a listener.
+ */
+export declare function trackingPortTaken(sources: readonly TrackingSourceConfig[], kind: TrackingSourceKind, port: number, excludeId?: string): boolean;
 export declare const EFFECTS_QUALITY_LEVELS: readonly ["low", "medium", "high"];
 export type EffectsQuality = (typeof EFFECTS_QUALITY_LEVELS)[number];
 /**
@@ -873,11 +858,20 @@ export type EffectsQuality = (typeof EFFECTS_QUALITY_LEVELS)[number];
  * 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];
+/** A stage window content size in device-independent px — what the desktop's window bounds report. */
+export interface StageSize {
+    width: number;
+    height: number;
+}
 /** The curated settings surface the API exposes — never the raw store shape. */
 export interface Settings {
+    /** Absent on hosts without remote controller management. */
+    controller?: ControllerConfig;
     /** `alwaysOnTop` floats the control-panel window, never the stage. */
     window: {
         alwaysOnTop: boolean;
+        /** Read-only; absent on older desktops. */
+        stageSize?: StageSize;
     };
     ui: {
         trayVisible: boolean;
@@ -887,6 +881,9 @@ export interface Settings {
         fpsLimit: number;
         selectionOutline: boolean;
         effectsQuality: EffectsQuality;
+        /** Absent on older hosts. */
+        renderScale?: number;
+        live2dEngine?: 'pixi' | 'three';
     };
     /** `source` mirrors the first face source's kind — the pre-multi-source field, kept for old clients. */
     tracking: {
@@ -894,7 +891,7 @@ export interface Settings {
         source: TrackingSourceId;
         sources: TrackingSourceConfig[];
     };
-    /** `source`/`port` mirror the first vmc source — the pre-multi-source fields, kept for old clients. */
+    /** `source`/`port` mirror the first body source — the pre-multi-source fields, kept for old clients. */
     pose: {
         enabled: boolean;
         source: PoseSourceId;
@@ -902,6 +899,7 @@ export interface Settings {
     };
 }
 export interface SettingsPatch {
+    controller?: Partial<Pick<ControllerConfig, 'enabled'>>;
     window?: {
         alwaysOnTop?: boolean;
     };
@@ -913,17 +911,19 @@ export interface SettingsPatch {
         fpsLimit?: number;
         selectionOutline?: boolean;
         effectsQuality?: EffectsQuality;
+        renderScale?: number;
+        live2dEngine?: 'pixi' | 'three';
     };
 }
 /** VTS's input vocabulary, plus `JawOpen` — the derived half of {@link INPUT_NAMES}. */
 declare const VTS_INPUT_NAMES: readonly ["FaceAngleX", "FaceAngleY", "FaceAngleZ", "FacePositionX", "FacePositionY", "FacePositionZ", "EyeOpenLeft", "EyeOpenRight", "EyeLeftX", "EyeLeftY", "EyeRightX", "EyeRightY", "Brows", "BrowLeftY", "BrowRightY", "MouthSmile", "MouthOpen", "MouthX", "CheekPuff", "JawOpen", "TongueOut"];
 type VtsInputName = (typeof VTS_INPUT_NAMES)[number];
 /**
- * The valid `id`s for `input` inject targets, and the names a model's `.vtube.json`
- * references: VTS's derived vocabulary plus every raw ARKit channel.
+ * Default input vocabulary: VTS face inputs, raw ARKit channels and controller profile 1.
+ * Additional controller profile ids are accepted by isInputName without appearing in this list.
  */
-export declare const INPUT_NAMES: readonly InputName[];
-export type InputName = VtsInputName | ArkitInputName;
+export declare const INPUT_NAMES: readonly (VtsInputName | ArkitInputName | BaseControllerInputName)[];
+export type InputName = VtsInputName | ArkitInputName | ControllerInputName;
 /** Whether an untrusted string names a tracking input — the guard every wire boundary needs. */
 export declare function isInputName(v: string): v is InputName;
 /**
@@ -948,10 +948,12 @@ export declare const BINDING_INPUT_NAMES: readonly BindingInput[];
 /** The id an input is read as: its ARKit twin when it has one, else itself. */
 export declare function arkitTwinOf(input: InputName): BindingInput;
 /**
- * Each input's natural span — the units a sender should write, and the input range a new
- * binding starts from. Head angles are **degrees**; the rest are unitless.
+ * Default inputs' natural spans. Use getInputRange for a dynamically numbered controller input.
+ * Head angles are degrees; the rest are unitless.
  */
-export declare const INPUT_RANGES: Record<InputName, readonly [number, number]>;
+export declare const INPUT_RANGES: Record<VtsInputName | ArkitInputName | BaseControllerInputName, readonly [number, number]>;
+/** Natural span of any valid input, including dynamically numbered controller profiles. */
+export declare function getInputRange(name: InputName): readonly [number, number];
 /**
  * What an injected value drives:
  * - `input` — a VTS-vocabulary tracking input (`MouthOpen`, `FaceAngleX`, …), mapped
@@ -972,4 +974,3 @@ export interface InjectEntry extends InjectTarget {
     /** 0..1 blend over whatever else drives the parameter; default 1. */
     weight?: number;
 }
-export {};

package/dist/wire/types.js

@@ -2,6 +2,7 @@
 // carry. Structural mirrors of the app's scene/settings models, minus anything
 // filesystem-shaped — model refs are sanitized to ids, never directories.
 import { ARKIT_INPUT_NAMES } from "../values/arkit.js";
+import { BASE_CONTROLLER_INPUT_NAMES, BASE_CONTROLLER_INPUT_RANGES, controllerInputRange, isControllerInputName, } from "../values/controller.js";
 /**
  * How a registered file is labelled. Wider than an object's content kinds: `.hdr` is only
  * ever an environment map, and a `.vmd` splits by content — `cameraMotion` for one that
@@ -23,7 +24,14 @@ export const SHADOW_QUALITY_LEVELS = ['off', 'low', 'medium', 'high', 'ultra'];
  * App-level features a client gates on (never version-sniff): `hello` and
  * `app.info` report them — the per-app mirror of {@link InstanceRuntime.capabilities}.
  */
-export const APP_CAPABILITIES = ['storage', 'speech', 'shortcuts'];
+export const APP_CAPABILITIES = [
+    'storage',
+    'speech',
+    'shortcuts',
+    'controllers',
+    'model-editing',
+    'asset-inspection',
+];
 export function isAppCapability(v) {
     return typeof v === 'string' && APP_CAPABILITIES.includes(v);
 }
@@ -38,15 +46,26 @@ export const SHORTCUT_ACTION_KINDS = [
     'stream-mode',
 ];
 // ---- Settings ------------------------------------------------------------------
-export const TRACKING_SOURCE_IDS = ['vts-ios', 'ifacialmocap'];
+export const TRACKING_SOURCE_IDS = ['persona-ios', 'ifacialmocap', 'vts-ios'];
 /** Body-pose protocols. Every one so far is UDP with a configurable port. */
-export const POSE_SOURCE_IDS = ['vmc'];
-/** Every protocol a tracking source instance can speak; face kinds plus the body (vmc) kind. */
+export const POSE_SOURCE_IDS = ['vmc', 'mocopi'];
+/** Every protocol a tracking source instance can speak; face and body kinds. */
 export const TRACKING_SOURCE_KINDS = [...TRACKING_SOURCE_IDS, ...POSE_SOURCE_IDS];
-/** Whether a source kind feeds the face channel (vmc is the body channel). */
+/** Whether a source kind feeds the face channel. */
 export function isFaceSourceKind(kind) {
     return TRACKING_SOURCE_IDS.includes(kind);
 }
+/** Whether a source feeds the body channel — the narrowing counterpart of `isFaceSourceKind`. */
+export function isPoseSource(source) {
+    return !isFaceSourceKind(source.kind);
+}
+/**
+ * Whether another source already holds `port` and would contend for it. iFacialMocap instances
+ * share one socket per port (frames demux by phone); every other pairing EADDRINUSEs a listener.
+ */
+export function trackingPortTaken(sources, kind, port, excludeId) {
+    return sources.some(s => s.id !== excludeId && s.port === port && !(s.kind === 'ifacialmocap' && kind === 'ifacialmocap'));
+}
 export const EFFECTS_QUALITY_LEVELS = ['low', 'medium', 'high'];
 /**
  * Accepted values for `performance.fpsLimit`; 0 = unlimited. Anything else is snapped
@@ -79,14 +98,18 @@ const VTS_INPUT_NAMES = [
     'TongueOut',
 ];
 /**
- * The valid `id`s for `input` inject targets, and the names a model's `.vtube.json`
- * references: VTS's derived vocabulary plus every raw ARKit channel.
+ * Default input vocabulary: VTS face inputs, raw ARKit channels and controller profile 1.
+ * Additional controller profile ids are accepted by isInputName without appearing in this list.
  */
-export const INPUT_NAMES = [...VTS_INPUT_NAMES, ...ARKIT_INPUT_NAMES];
+export const INPUT_NAMES = [
+    ...VTS_INPUT_NAMES,
+    ...ARKIT_INPUT_NAMES,
+    ...BASE_CONTROLLER_INPUT_NAMES,
+];
 const INPUT_NAME_SET = new Set(INPUT_NAMES);
 /** Whether an untrusted string names a tracking input — the guard every wire boundary needs. */
 export function isInputName(v) {
-    return INPUT_NAME_SET.has(v);
+    return INPUT_NAME_SET.has(v) || isControllerInputName(v);
 }
 /**
  * VTS-vocabulary inputs that are the same float as one raw ARKit channel (the desktop derives
@@ -145,12 +168,17 @@ const VTS_INPUT_RANGES = {
 /** ARKit blendshapes are unit-scale by definition, so every raw channel shares one span. */
 const ARKIT_RANGE = [0, 1];
 /**
- * Each input's natural span — the units a sender should write, and the input range a new
- * binding starts from. Head angles are **degrees**; the rest are unitless.
+ * Default inputs' natural spans. Use getInputRange for a dynamically numbered controller input.
+ * Head angles are degrees; the rest are unitless.
  */
 export const INPUT_RANGES = {
     ...VTS_INPUT_RANGES,
+    ...BASE_CONTROLLER_INPUT_RANGES,
     // `fromEntries` widens the key type back to `string`; the annotation above is what keeps
     // this exhaustive, and it fails to typecheck if a name ever lacks a range.
     ...Object.fromEntries(ARKIT_INPUT_NAMES.map(n => [n, ARKIT_RANGE])),
 };
+/** Natural span of any valid input, including dynamically numbered controller profiles. */
+export function getInputRange(name) {
+    return isControllerInputName(name) ? controllerInputRange(name) : INPUT_RANGES[name];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@laplace.live/persona-sdk",
-  "version": "0.18.1",
+  "version": "1.0.0",
   "description": "TypeScript SDK and wire schema for the LAPLACE Persona plugin API",
   "license": "MIT",
   "type": "module",
@@ -16,10 +16,6 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
-    },
-    "./effects": {
-      "types": "./dist/effects.d.ts",
-      "import": "./dist/effects.js"
     }
   },
   "files": [
@@ -30,22 +26,12 @@
     "provenance": true
   },
   "devDependencies": {
-    "@types/three": "^0.185.4",
     "rimraf": "^6.1.3",
-    "three": "0.185.1",
     "typescript": "~6.0.3",
     "vitest": "^4.1.11"
   },
-  "peerDependencies": {
-    "@types/three": "^0.185.0"
-  },
-  "peerDependenciesMeta": {
-    "@types/three": {
-      "optional": true
-    }
-  },
   "engines": {
-    "node": ">=22"
+    "node": ">=24"
   },
   "dependencies": {
     "zod": "^4.5.4"

package/dist/effects.d.ts

@@ -1,79 +0,0 @@
-import type * as TSL from 'three/tsl';
-import type { Color, Node, Vector2, Vector3, Vector4 } from 'three/webgpu';
-export * from './values/custom-effect.ts';
-/** A vec4-typed TSL node with its swizzles — what `sample` returns and `build` composes over. */
-export type CustomEffectVec4 = ReturnType<typeof TSL.nodeObject<Node<'vec4'>>>;
-/** A float-typed TSL node with its operators — what `viewZ` returns. */
-export type CustomEffectFloat = ReturnType<typeof TSL.nodeObject<Node<'float'>>>;
-/** A vec3-typed TSL node with its swizzles — what the camera probes return. */
-export type CustomEffectVec3 = ReturnType<typeof TSL.nodeObject<Node<'vec3'>>>;
-/** What an author's module receives. Not a security boundary — just the useful surface. */
-export interface CustomEffectApi {
-    /** The whole `three/tsl` namespace: `vec4`, `uv`, `uniform`, `mix`, `Fn`, … */
-    tsl: typeof TSL;
-    three: {
-        Color: typeof Color;
-        Vector2: typeof Vector2;
-        Vector3: typeof Vector3;
-        Vector4: typeof Vector4;
-    };
-    /**
-     * Stock three display nodes an effect cannot build for itself. `afterImage`
-     * is the seam for anything temporal: correct frame feedback needs two render
-     * targets ping-ponged plus a renderer reference, and `build()` hands authors
-     * neither. Upstream types return the bare class, hiding the TSL swizzles the
-     * runtime proxy carries; this signature types the echo as what authors use it
-     * as — a sampleable vec4 image.
-     */
-    nodes: {
-        afterImage: (node: Node, damp?: Node | number) => CustomEffectVec4;
-    };
-}
-/** Build-time context for one custom effect. */
-export interface CustomEffectBuildContext {
-    /** Sample the incoming frame at any UV — the seam that makes warps and blurs possible. */
-    sample: (at: unknown) => CustomEffectVec4;
-    /** Screen UV of the pixel being shaded. */
-    uv: typeof TSL.uv;
-    /**
-     * View-space Z of the 3D scene at this pixel — three's convention: 0 at the
-     * camera, more negative with distance, the far plane where nothing was drawn.
-     * The Live2D layer and 2D objects contribute no depth. Costs one depth read,
-     * and only if called.
-     */
-    viewZ: () => CustomEffectFloat;
-    /**
-     * Normalized world-space direction of the scene camera's view ray through
-     * this pixel, fov and aspect folded in. Inside the post pass TSL's own
-     * `cameraPosition`/`cameraWorldMatrix` describe the fullscreen quad's
-     * camera — this is the real one. Anchor a field here instead of `uv()` and
-     * it holds still in the world while the camera orbits.
-     */
-    worldRay: () => CustomEffectVec3;
-    /** The scene camera's world position in metres, as a per-frame uniform. */
-    cameraPosition: () => CustomEffectVec3;
-    /** Hand a build-time disposable (a blur render target) to the chain's transient list. */
-    track: (t: {
-        dispose?: () => void;
-    }) => void;
-}
-/** What an author's module returns. Everything but `build` is optional. */
-export interface CustomEffectModule {
-    /** Uniform nodes keyed by manifest param name; param edits write straight into `.value`. */
-    uniforms?: Record<string, {
-        value: unknown;
-    }>;
-    /** Compose the effect over `input` — the frame so far, already sampleable — and return the result node. */
-    build: (input: Node, ctx: CustomEffectBuildContext) => Node;
-    /** Per-frame CPU state. `dt` and `elapsed` are seconds. */
-    update?: (dt: number, elapsed: number) => void;
-    dispose?: () => void;
-}
-/** The module's default export. Runs once per load — mint uniforms here so they survive rebuilds. */
-export type CustomEffectFactory = (api: CustomEffectApi) => CustomEffectModule;
-/** Why an effect is not rendering, for the panel's error row. */
-export interface CustomEffectFault {
-    slug: string;
-    phase: 'load' | 'build' | 'update';
-    message: string;
-}

package/dist/effects.js

@@ -1,6 +0,0 @@
-// The custom-effect authoring contract: what an effect module receives, what it
-// returns, and (re-exported) the manifest shape naming its params. Everything
-// touching three is type-only — the desktop hands the runtime to the module's
-// factory, because a module loaded from `persona://` can import nothing.
-// Typechecking against this entry needs `@types/three` (optional peer).
-export * from "./values/custom-effect.js";