@laplace.live/persona-sdk 0.0.1

package/dist/events.d.ts

@@ -0,0 +1,42 @@
+import type { HotkeyState, ModelFormat, PoseStatus, SceneState, Settings, TrackingStatus } from './types.ts';
+/** Every push event a session can subscribe to, with its payload. */
+export interface EventMap {
+    /** Any scene mutation: create/delete/rename/activate/shortcut and persisted scene edits. */
+    'scene.changed': SceneState;
+    'settings.changed': {
+        settings: Settings;
+    };
+    'hotkey.state': {
+        modelId: string | null;
+        config: HotkeyState;
+    };
+    'tracking.status': {
+        tracking: TrackingStatus;
+        pose: PoseStatus;
+    };
+    /** A model instance finished loading on stage. */
+    'instance.loaded': {
+        instanceId: string;
+        format: ModelFormat;
+    };
+    'expression.changed': {
+        instanceId: string;
+        active: string[];
+    };
+    'motion.started': {
+        instanceId: string;
+        group: string;
+        index: number;
+    };
+    'motion.ended': {
+        instanceId: string;
+    };
+    /** True while a scene apply or pipeline warm-up is in flight. */
+    'scene.loading': {
+        loading: boolean;
+    };
+}
+export type EventName = keyof EventMap;
+export type EventData<E extends EventName = EventName> = EventMap[E];
+export declare const EVENT_NAMES: readonly EventName[];
+export declare function isEventName(v: unknown): v is EventName;

package/dist/events.js

@@ -0,0 +1,16 @@
+// Built from a `Record<EventName, …>` so a new EventMap key that is missing
+// here fails the build instead of silently failing `isEventName`.
+export const EVENT_NAMES = Object.keys({
+    'scene.changed': true,
+    'settings.changed': true,
+    'hotkey.state': true,
+    'tracking.status': true,
+    'instance.loaded': true,
+    'expression.changed': true,
+    'motion.started': true,
+    'motion.ended': true,
+    'scene.loading': true,
+});
+export function isEventName(v) {
+    return typeof v === 'string' && EVENT_NAMES.includes(v);
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+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';

package/dist/index.js

@@ -0,0 +1,8 @@
+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";

package/dist/methods.d.ts

@@ -0,0 +1,579 @@
+import type { EventName } from './events.ts';
+import type { AnchorOption, AssetKind, AssetRef, Attach, Expression, ExpressionPersistence, HotkeyConfig, HotkeyState, InjectEntry, InjectTarget, InstanceRuntime, ModelInfo, ModelRef, MotionGroup, MToonTuning, ObjectContent, ObjectLightOverride, ObjectSpace, Place2D, Place3D, PlayingMotion, PoseSourceId, PoseStatus, Scene, SceneItem, ScenePatch, SceneState, ScreenPlacement, Settings, SettingsPatch, TrackingSourceId, TrackingStatus, VrmPlacement } from './types.ts';
+/** Marker for methods that take no parameters; the client lets you omit the argument. */
+export type EmptyRequest = Record<never, never>;
+/** Marker for methods whose success response carries no data. */
+export type EmptyResponse = Record<never, never>;
+export type SceneListRequest = EmptyRequest;
+export type SceneListResponse = SceneState;
+/** Omitting `sceneId` reads the active scene. */
+export interface SceneGetRequest {
+    sceneId?: string;
+}
+export interface SceneGetResponse {
+    scene: Scene;
+}
+export interface SceneActivateRequest {
+    sceneId: string;
+}
+export type SceneActivateResponse = SceneState;
+export type SceneCreateRequest = EmptyRequest;
+export type SceneCreateResponse = SceneState;
+export interface SceneDuplicateRequest {
+    sceneId: string;
+}
+export type SceneDuplicateResponse = SceneState;
+export interface SceneRenameRequest {
+    sceneId: string;
+    name: string;
+}
+export type SceneRenameResponse = SceneState;
+export interface SceneDeleteRequest {
+    sceneId: string;
+}
+export type SceneDeleteResponse = SceneState;
+export interface SceneSetShortcutRequest {
+    sceneId: string;
+    /** Electron accelerator string, or null to clear. */
+    accelerator: string | null;
+}
+export type SceneSetShortcutResponse = SceneState;
+export type ScenePatchRequest = ScenePatch;
+export interface ScenePatchResponse {
+    scene: Scene;
+}
+export type InstanceListRequest = EmptyRequest;
+export interface InstanceListResponse {
+    instances: InstanceRuntime[];
+}
+export interface InstanceGetRequest {
+    instanceId?: string;
+}
+export interface InstanceGetResponse {
+    item: SceneItem;
+    runtime: InstanceRuntime;
+}
+export interface InstanceAddRequest {
+    modelId: string;
+}
+export interface InstanceAddResponse {
+    instanceId: string;
+}
+export interface InstanceRemoveRequest {
+    instanceId: string;
+}
+export type InstanceRemoveResponse = EmptyResponse;
+export interface InstanceSetVisibleRequest {
+    instanceId: string;
+    visible: boolean;
+}
+export type InstanceSetVisibleResponse = EmptyResponse;
+export interface InstanceReorderRequest {
+    /** Full z-order within the scene; ids not listed keep their relative order at the end. */
+    orderedInstanceIds: string[];
+}
+export type InstanceReorderResponse = EmptyResponse;
+export interface InstanceSetPrimaryRequest {
+    instanceId: string;
+}
+export type InstanceSetPrimaryResponse = EmptyResponse;
+export interface InstanceSetPlacementRequest {
+    instanceId?: string;
+    live2d?: Partial<ScreenPlacement>;
+    vrm?: Partial<VrmPlacement>;
+}
+export type InstanceSetPlacementResponse = EmptyResponse;
+export interface InstanceSetMToonRequest {
+    instanceId?: string;
+    tuning: Partial<MToonTuning>;
+}
+export type InstanceSetMToonResponse = EmptyResponse;
+export interface InstanceSetIdleRequest {
+    instanceId?: string;
+    idleAnimation?: boolean;
+    idleClip?: string;
+}
+export type InstanceSetIdleResponse = EmptyResponse;
+export interface InstanceInfoRequest {
+    instanceId?: string;
+}
+export interface InstanceInfoResponse {
+    info: ModelInfo;
+}
+export interface ObjectAddRequest {
+    content: ObjectContent;
+    name?: string;
+}
+export interface ObjectAddResponse {
+    instanceId: string;
+}
+export interface ObjectRenameRequest {
+    instanceId: string;
+    name: string;
+}
+export type ObjectRenameResponse = EmptyResponse;
+export interface ObjectSetContentRequest {
+    instanceId: string;
+    content: ObjectContent;
+}
+export type ObjectSetContentResponse = EmptyResponse;
+export interface ObjectSetSpaceRequest {
+    instanceId: string;
+    space: ObjectSpace;
+}
+export type ObjectSetSpaceResponse = EmptyResponse;
+export interface ObjectSetPlacementRequest {
+    instanceId: string;
+    place2d?: Partial<Place2D>;
+    place3d?: Partial<Place3D>;
+}
+export type ObjectSetPlacementResponse = EmptyResponse;
+export interface ObjectAttachRequest {
+    instanceId: string;
+    /** Null detaches. */
+    attach: Attach | null;
+}
+export type ObjectAttachResponse = EmptyResponse;
+export interface ObjectSetLightOverridesRequest {
+    instanceId: string;
+    overrides: Record<string, ObjectLightOverride>;
+}
+export type ObjectSetLightOverridesResponse = EmptyResponse;
+export interface ObjectAnchorsRequest {
+    parentInstanceId: string;
+}
+/** Anchors a loaded model offers for attachment. */
+export interface ObjectAnchorsResponse {
+    anchors: AnchorOption[];
+}
+export interface ExpressionListRequest {
+    instanceId?: string;
+}
+export interface ExpressionListResponse {
+    expressions: Expression[];
+}
+export interface ExpressionActiveRequest {
+    instanceId?: string;
+}
+export interface ExpressionActiveResponse {
+    active: string[];
+}
+export interface ExpressionToggleRequest {
+    instanceId?: string;
+    name: string;
+}
+export interface ExpressionToggleResponse {
+    active: string[];
+}
+export interface ExpressionGetPersistenceRequest {
+    modelId?: string;
+}
+export type ExpressionGetPersistenceResponse = ExpressionPersistence;
+export interface ExpressionSetPersistenceRequest {
+    modelId?: string;
+    enabled: boolean;
+}
+export type ExpressionSetPersistenceResponse = ExpressionPersistence;
+export interface MotionListRequest {
+    instanceId?: string;
+}
+export interface MotionListResponse {
+    groups: MotionGroup[];
+}
+export interface MotionPlayRequest {
+    instanceId?: string;
+    group: string;
+    index: number;
+}
+export type MotionPlayResponse = EmptyResponse;
+export interface MotionPlayingRequest {
+    instanceId?: string;
+}
+export interface MotionPlayingResponse {
+    playing: PlayingMotion | null;
+}
+export interface HotkeyListRequest {
+    modelId?: string;
+}
+export type HotkeyListResponse = HotkeyState;
+export interface HotkeySetRequest {
+    modelId?: string;
+    /** Healed leniently server-side: malformed entries drop, missing ids are minted. */
+    config: HotkeyConfig;
+}
+export type HotkeySetResponse = HotkeyState;
+export interface HotkeyTriggerRequest {
+    hotkeyId: string;
+}
+export type HotkeyTriggerResponse = EmptyResponse;
+export type ModelListRequest = EmptyRequest;
+export interface ModelListResponse {
+    models: ModelRef[];
+}
+export type AssetListRequest = EmptyRequest;
+export interface AssetListResponse {
+    assets: AssetRef[];
+}
+/** Register a model entry file under a user-configured plugin folder. */
+export interface ModelRegisterRequest {
+    path: string;
+}
+export interface ModelRegisterResponse {
+    model: ModelRef;
+}
+/**
+ * Register an asset file under a plugin folder. `want` asserts the kind
+ * (mismatches answer `invalid-params`); `ibl` also accepts plain image files.
+ */
+export interface AssetRegisterRequest {
+    path: string;
+    want?: AssetKind;
+}
+export interface AssetRegisterResponse {
+    asset: AssetRef;
+}
+export type SettingsGetRequest = EmptyRequest;
+export interface SettingsGetResponse {
+    settings: Settings;
+}
+export interface SettingsPatchRequest {
+    settings: SettingsPatch;
+}
+export interface SettingsPatchResponse {
+    settings: Settings;
+}
+export interface TrackingSetEnabledRequest {
+    enabled: boolean;
+}
+export type TrackingSetEnabledResponse = EmptyResponse;
+export interface TrackingSetSourceRequest {
+    source: TrackingSourceId;
+}
+export type TrackingSetSourceResponse = EmptyResponse;
+export interface PoseSetEnabledRequest {
+    enabled: boolean;
+}
+export type PoseSetEnabledResponse = EmptyResponse;
+export interface PoseSetSourceRequest {
+    source: PoseSourceId;
+}
+/** Switching protocol resets the port to that source's default; the response reports it. */
+export interface PoseSetSourceResponse {
+    port: number;
+}
+export interface PoseSetPortRequest {
+    port: number;
+}
+export type PoseSetPortResponse = EmptyResponse;
+export type TrackingStatusRequest = EmptyRequest;
+export interface TrackingStatusResponse {
+    tracking: TrackingStatus;
+    pose: PoseStatus;
+}
+export interface StageResetTransformRequest {
+    instanceId?: string;
+}
+export type StageResetTransformResponse = EmptyResponse;
+export type StageResetCameraRequest = EmptyRequest;
+export type StageResetCameraResponse = EmptyResponse;
+export type StageShockwaveRequest = EmptyRequest;
+export type StageShockwaveResponse = EmptyResponse;
+export type AppInfoRequest = EmptyRequest;
+export interface AppInfoResponse {
+    name: string;
+    version: string;
+    platform: string;
+    protocol: number;
+}
+export type AppLocalAddressesRequest = EmptyRequest;
+export interface AppLocalAddressesResponse {
+    addresses: {
+        iface: string;
+        address: string;
+    }[];
+}
+export type AppStatsRequest = EmptyRequest;
+export interface AppStatsResponse {
+    fps: number | null;
+}
+export interface EventsSubscribeRequest {
+    events: EventName[];
+}
+export interface EventsSubscribeResponse {
+    subscribed: EventName[];
+}
+/** Omitting `events` unsubscribes from everything; unknown names are tolerated. */
+export interface EventsUnsubscribeRequest {
+    events?: EventName[];
+}
+export interface EventsUnsubscribeResponse {
+    subscribed: EventName[];
+}
+export interface ParamInjectRequest {
+    entries: InjectEntry[];
+}
+export type ParamInjectResponse = EmptyResponse;
+export interface ParamReleaseRequest {
+    /** Omitting `targets` releases everything this session holds. */
+    targets?: InjectTarget[];
+}
+export type ParamReleaseResponse = EmptyResponse;
+/**
+ * The full request surface: method → request/response. Model-scoped methods take
+ * an optional `instanceId` defaulting to the scene's primary model instance.
+ */
+export interface MethodMap {
+    'scene.list': {
+        request: SceneListRequest;
+        response: SceneListResponse;
+    };
+    'scene.get': {
+        request: SceneGetRequest;
+        response: SceneGetResponse;
+    };
+    'scene.activate': {
+        request: SceneActivateRequest;
+        response: SceneActivateResponse;
+    };
+    'scene.create': {
+        request: SceneCreateRequest;
+        response: SceneCreateResponse;
+    };
+    'scene.duplicate': {
+        request: SceneDuplicateRequest;
+        response: SceneDuplicateResponse;
+    };
+    'scene.rename': {
+        request: SceneRenameRequest;
+        response: SceneRenameResponse;
+    };
+    'scene.delete': {
+        request: SceneDeleteRequest;
+        response: SceneDeleteResponse;
+    };
+    'scene.setShortcut': {
+        request: SceneSetShortcutRequest;
+        response: SceneSetShortcutResponse;
+    };
+    /** Live edit of the active scene's sections; applies next frame, persists debounced. */
+    'scene.patch': {
+        request: ScenePatchRequest;
+        response: ScenePatchResponse;
+    };
+    'instance.list': {
+        request: InstanceListRequest;
+        response: InstanceListResponse;
+    };
+    'instance.get': {
+        request: InstanceGetRequest;
+        response: InstanceGetResponse;
+    };
+    'instance.add': {
+        request: InstanceAddRequest;
+        response: InstanceAddResponse;
+    };
+    /** Removes any scene item — model or object. */
+    'instance.remove': {
+        request: InstanceRemoveRequest;
+        response: InstanceRemoveResponse;
+    };
+    'instance.setVisible': {
+        request: InstanceSetVisibleRequest;
+        response: InstanceSetVisibleResponse;
+    };
+    'instance.reorder': {
+        request: InstanceReorderRequest;
+        response: InstanceReorderResponse;
+    };
+    'instance.setPrimary': {
+        request: InstanceSetPrimaryRequest;
+        response: InstanceSetPrimaryResponse;
+    };
+    'instance.setPlacement': {
+        request: InstanceSetPlacementRequest;
+        response: InstanceSetPlacementResponse;
+    };
+    'instance.setMToon': {
+        request: InstanceSetMToonRequest;
+        response: InstanceSetMToonResponse;
+    };
+    'instance.setIdle': {
+        request: InstanceSetIdleRequest;
+        response: InstanceSetIdleResponse;
+    };
+    'instance.info': {
+        request: InstanceInfoRequest;
+        response: InstanceInfoResponse;
+    };
+    'object.add': {
+        request: ObjectAddRequest;
+        response: ObjectAddResponse;
+    };
+    'object.rename': {
+        request: ObjectRenameRequest;
+        response: ObjectRenameResponse;
+    };
+    'object.setContent': {
+        request: ObjectSetContentRequest;
+        response: ObjectSetContentResponse;
+    };
+    'object.setSpace': {
+        request: ObjectSetSpaceRequest;
+        response: ObjectSetSpaceResponse;
+    };
+    'object.setPlacement': {
+        request: ObjectSetPlacementRequest;
+        response: ObjectSetPlacementResponse;
+    };
+    'object.attach': {
+        request: ObjectAttachRequest;
+        response: ObjectAttachResponse;
+    };
+    'object.setLightOverrides': {
+        request: ObjectSetLightOverridesRequest;
+        response: ObjectSetLightOverridesResponse;
+    };
+    'object.anchors': {
+        request: ObjectAnchorsRequest;
+        response: ObjectAnchorsResponse;
+    };
+    'expression.list': {
+        request: ExpressionListRequest;
+        response: ExpressionListResponse;
+    };
+    'expression.active': {
+        request: ExpressionActiveRequest;
+        response: ExpressionActiveResponse;
+    };
+    'expression.toggle': {
+        request: ExpressionToggleRequest;
+        response: ExpressionToggleResponse;
+    };
+    'expression.getPersistence': {
+        request: ExpressionGetPersistenceRequest;
+        response: ExpressionGetPersistenceResponse;
+    };
+    'expression.setPersistence': {
+        request: ExpressionSetPersistenceRequest;
+        response: ExpressionSetPersistenceResponse;
+    };
+    'motion.list': {
+        request: MotionListRequest;
+        response: MotionListResponse;
+    };
+    'motion.play': {
+        request: MotionPlayRequest;
+        response: MotionPlayResponse;
+    };
+    'motion.playing': {
+        request: MotionPlayingRequest;
+        response: MotionPlayingResponse;
+    };
+    'hotkey.list': {
+        request: HotkeyListRequest;
+        response: HotkeyListResponse;
+    };
+    'hotkey.set': {
+        request: HotkeySetRequest;
+        response: HotkeySetResponse;
+    };
+    'hotkey.trigger': {
+        request: HotkeyTriggerRequest;
+        response: HotkeyTriggerResponse;
+    };
+    'model.list': {
+        request: ModelListRequest;
+        response: ModelListResponse;
+    };
+    'asset.list': {
+        request: AssetListRequest;
+        response: AssetListResponse;
+    };
+    'model.register': {
+        request: ModelRegisterRequest;
+        response: ModelRegisterResponse;
+    };
+    'asset.register': {
+        request: AssetRegisterRequest;
+        response: AssetRegisterResponse;
+    };
+    'settings.get': {
+        request: SettingsGetRequest;
+        response: SettingsGetResponse;
+    };
+    'settings.patch': {
+        request: SettingsPatchRequest;
+        response: SettingsPatchResponse;
+    };
+    'tracking.setEnabled': {
+        request: TrackingSetEnabledRequest;
+        response: TrackingSetEnabledResponse;
+    };
+    'tracking.setSource': {
+        request: TrackingSetSourceRequest;
+        response: TrackingSetSourceResponse;
+    };
+    'pose.setEnabled': {
+        request: PoseSetEnabledRequest;
+        response: PoseSetEnabledResponse;
+    };
+    'pose.setSource': {
+        request: PoseSetSourceRequest;
+        response: PoseSetSourceResponse;
+    };
+    'pose.setPort': {
+        request: PoseSetPortRequest;
+        response: PoseSetPortResponse;
+    };
+    'tracking.status': {
+        request: TrackingStatusRequest;
+        response: TrackingStatusResponse;
+    };
+    'stage.resetTransform': {
+        request: StageResetTransformRequest;
+        response: StageResetTransformResponse;
+    };
+    'stage.resetCamera': {
+        request: StageResetCameraRequest;
+        response: StageResetCameraResponse;
+    };
+    'stage.shockwave': {
+        request: StageShockwaveRequest;
+        response: StageShockwaveResponse;
+    };
+    'app.info': {
+        request: AppInfoRequest;
+        response: AppInfoResponse;
+    };
+    'app.localAddresses': {
+        request: AppLocalAddressesRequest;
+        response: AppLocalAddressesResponse;
+    };
+    'app.stats': {
+        request: AppStatsRequest;
+        response: AppStatsResponse;
+    };
+    'events.subscribe': {
+        request: EventsSubscribeRequest;
+        response: EventsSubscribeResponse;
+    };
+    'events.unsubscribe': {
+        request: EventsUnsubscribeRequest;
+        response: EventsUnsubscribeResponse;
+    };
+    /**
+     * Write parameter leases. Each entry holds ~1 s from its last write, then
+     * reverts — keep sending to keep driving. Ownership is per-session.
+     */
+    'param.inject': {
+        request: ParamInjectRequest;
+        response: ParamInjectResponse;
+    };
+    'param.release': {
+        request: ParamReleaseRequest;
+        response: ParamReleaseResponse;
+    };
+}
+export type MethodName = keyof MethodMap;
+export type MethodRequest<M extends MethodName> = MethodMap[M]['request'];
+export type MethodResponse<M extends MethodName> = MethodMap[M]['response'];

package/dist/methods.js

@@ -0,0 +1 @@
+export {};

package/dist/protocol.d.ts

@@ -0,0 +1,11 @@
+import type { InjectTarget } from './types.ts';
+/** Bumped on breaking wire changes; the server reports it in `hello` and clients warn on mismatch. */
+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;
+/** 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. */
+export declare const INJECT_HEARTBEAT_MS = 100;
+/** Canonical map key for an injection target — JSON framing so ids containing spaces cannot collide. */
+export declare function injectTargetKey(t: InjectTarget): string;

package/dist/protocol.js

@@ -0,0 +1,12 @@
+/** Bumped on breaking wire changes; the server reports it in `hello` and clients warn on mismatch. */
+export const PROTOCOL_VERSION = 1;
+/** Default port the Persona API server listens on (user-configurable in the app). */
+export const DEFAULT_API_PORT = 25034;
+/** 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. */
+export const INJECT_HEARTBEAT_MS = 100;
+/** Canonical map key for an injection target — JSON framing so ids containing spaces cannot collide. */
+export function injectTargetKey(t) {
+    return JSON.stringify([t.type, t.id, t.instanceId ?? '']);
+}