@laplace.live/persona-sdk 1.17.0 → 1.19.0

package/dist/values/hotkeys.d.ts

@@ -9,6 +9,17 @@ export declare function hasCommandModifier(accelerator: string | null): boolean;
 export declare function canRunInBackground(accelerator: string | null): boolean;
 /** True when a model hotkey is meant to fire while Persona sits in the background — what main registers on, and what the globe shows. */
 export declare function hotkeyRunsInBackground(h: Hotkey): boolean;
+/**
+ * Why a `hold` hotkey toggles instead of holding, or null when it can hold. A combo registered with
+ * the OS reaches Persona as a press alone — Electron reports no key-up for it — and one registration
+ * serves every hotkey on the combo: `'own'` when this hotkey asks for the background itself,
+ * `'shared'` when only another one on its combo does, which `registered` (main's list) alone can tell.
+ */
+export declare function holdBlockedBy(h: Pick<Hotkey, 'hold' | 'global' | 'accelerator'>, registered: boolean): 'own' | 'shared' | null;
+/** VTS's editor limits for a hotkey's fade and auto-off times, in seconds; healing clamps API input to them. */
+export declare const HOTKEY_FADE_SECONDS_MAX = 2;
+export declare const HOTKEY_DEACTIVATE_SECONDS_MIN = 0.1;
+export declare const HOTKEY_DEACTIVATE_SECONDS_MAX = 3600;
 /** Automations are enabled unless explicitly paused. */
 export declare function automationEnabled(s: {
     enabled?: boolean;
@@ -27,3 +38,25 @@ export declare function automationBindable<T extends {
 export declare function duplicateAccelerators(bindings: readonly {
     accelerator: string | null;
 }[]): Set<string>;
+/** The slice of a scene model item the ordering reads; a full `SceneModelItem` comes back as itself. */
+interface HotkeyModelLike {
+    kind: 'model';
+    instanceId: string;
+    ref: {
+        id: string;
+    };
+}
+/**
+ * The models whose hotkeys are live — every model in the scene, the primary first, one per model id
+ * (a model on two layers lists once). The desktop fires all of them, VTS-style, and every shortcut
+ * list shows them in this order; `hotkey.list`/`hotkey.trigger` take each one's `ref.id` as `modelId`.
+ * Generic over the item union so a scene document and the desktop's loaded runtimes both infer.
+ */
+export declare function hotkeyModels<T extends HotkeyModelLike | {
+    kind: 'object';
+    instanceId: string;
+}>(scene: {
+    items: readonly T[];
+    primaryInstanceId: string | null;
+}): Extract<T, HotkeyModelLike>[];
+export {};

package/dist/values/hotkeys.js

@@ -25,6 +25,23 @@ export function canRunInBackground(accelerator) {
 export function hotkeyRunsInBackground(h) {
     return h.global && h.active && h.action !== null && canRunInBackground(h.accelerator);
 }
+/**
+ * Why a `hold` hotkey toggles instead of holding, or null when it can hold. A combo registered with
+ * the OS reaches Persona as a press alone — Electron reports no key-up for it — and one registration
+ * serves every hotkey on the combo: `'own'` when this hotkey asks for the background itself,
+ * `'shared'` when only another one on its combo does, which `registered` (main's list) alone can tell.
+ */
+export function holdBlockedBy(h, registered) {
+    if (h.hold !== true)
+        return null;
+    if (h.global && hasCommandModifier(h.accelerator))
+        return 'own';
+    return registered ? 'shared' : null;
+}
+/** VTS's editor limits for a hotkey's fade and auto-off times, in seconds; healing clamps API input to them. */
+export const HOTKEY_FADE_SECONDS_MAX = 2;
+export const HOTKEY_DEACTIVATE_SECONDS_MIN = 0.1;
+export const HOTKEY_DEACTIVATE_SECONDS_MAX = 3600;
 /** Automations are enabled unless explicitly paused. */
 export function automationEnabled(s) {
     return s.enabled !== false;
@@ -49,3 +66,22 @@ export function duplicateAccelerators(bindings) {
     }
     return dupes;
 }
+/**
+ * The models whose hotkeys are live — every model in the scene, the primary first, one per model id
+ * (a model on two layers lists once). The desktop fires all of them, VTS-style, and every shortcut
+ * list shows them in this order; `hotkey.list`/`hotkey.trigger` take each one's `ref.id` as `modelId`.
+ * Generic over the item union so a scene document and the desktop's loaded runtimes both infer.
+ */
+export function hotkeyModels(scene) {
+    const models = scene.items.filter((i) => i.kind === 'model');
+    const primary = models.find(i => i.instanceId === scene.primaryInstanceId);
+    const out = [];
+    const seen = new Set();
+    for (const item of primary ? [primary, ...models] : models) {
+        if (seen.has(item.ref.id))
+            continue;
+        seen.add(item.ref.id);
+        out.push(item);
+    }
+    return out;
+}

package/dist/values/limits.d.ts

@@ -162,6 +162,10 @@ export declare const SPAWN_ALIVE_MAX = 500;
 export declare const SPAWN_SPREAD_MAX = 20;
 export declare const SPAWN_SPEED_MAX = 50;
 export declare const SPAWN_TTL_MAX_MS = 600000;
+/** `stage.capture` longest-edge bounds and default, px. */
+export declare const STAGE_CAPTURE_EDGE_MIN = 64;
+export declare const STAGE_CAPTURE_EDGE_MAX = 2048;
+export declare const STAGE_CAPTURE_EDGE_DEFAULT = 1024;
 /** Web object viewport bounds, CSS px per side. */
 export declare const WEB_SIZE_MIN = 16;
 export declare const WEB_SIZE_MAX = 7680;

package/dist/values/limits.js

@@ -282,6 +282,10 @@ export const SPAWN_ALIVE_MAX = 500;
 export const SPAWN_SPREAD_MAX = 20;
 export const SPAWN_SPEED_MAX = 50;
 export const SPAWN_TTL_MAX_MS = 600_000;
+/** `stage.capture` longest-edge bounds and default, px. */
+export const STAGE_CAPTURE_EDGE_MIN = 64;
+export const STAGE_CAPTURE_EDGE_MAX = 2048;
+export const STAGE_CAPTURE_EDGE_DEFAULT = 1024;
 /** Web object viewport bounds, CSS px per side. */
 export const WEB_SIZE_MIN = 16;
 export const WEB_SIZE_MAX = 7680;

package/dist/wire/events.d.ts

@@ -6,6 +6,10 @@ export interface EventMap {
     'settings.changed': {
         settings: Settings;
     };
+    /**
+     * One model's live hotkey set changed — every model on stage has one, and a model that just left the
+     * stage arrives empty. Older hosts sent `modelId: null` for an empty stage instead.
+     */
     'hotkey.state': {
         modelId: string | null;
         config: HotkeyState;

package/dist/wire/methods.d.ts

@@ -23,6 +23,7 @@ export interface SceneActivateRequest {
 }
 export type SceneActivateResponse = SceneState;
 export type SceneCreateRequest = EmptyRequest;
+/** The create activates the scene it adds: `activeSceneId` is the new scene's id. */
 export type SceneCreateResponse = SceneState;
 export interface SceneDuplicateRequest {
     sceneId: string;
@@ -339,6 +340,8 @@ export interface HotkeySetRequest {
 export type HotkeySetResponse = HotkeyState;
 export interface HotkeyTriggerRequest {
     hotkeyId: string;
+    /** The model that owns the hotkey — every model on stage has a live set; defaults to the primary. */
+    modelId?: string;
 }
 export type HotkeyTriggerResponse = EmptyResponse;
 export type AutomationListRequest = EmptyRequest;
@@ -493,6 +496,20 @@ export type StageClearSpawnedRequest = EmptyRequest;
 export interface StageClearSpawnedResponse {
     cleared: number;
 }
+/**
+ * A PNG of the stage window as it is displayed — what a client that cannot see the screen
+ * checks its edits against. Each capture costs the stage a frame, so read on demand, never poll.
+ */
+export interface StageCaptureRequest {
+    /** Longest edge in px, `STAGE_CAPTURE_EDGE_MIN`–`STAGE_CAPTURE_EDGE_MAX`; default `STAGE_CAPTURE_EDGE_DEFAULT`. */
+    maxEdge?: number;
+}
+export interface StageCaptureResponse {
+    /** `data:image/png;base64,…`, alpha preserved. */
+    dataUrl: string;
+    width: number;
+    height: number;
+}
 export type AppInfoRequest = EmptyRequest;
 export interface AppInfoResponse {
     name: string;
@@ -1024,6 +1041,11 @@ export interface MethodMap {
         request: StageClearSpawnedRequest;
         response: StageClearSpawnedResponse;
     };
+    /** Needs the `stage-capture` app capability. */
+    'stage.capture': {
+        request: StageCaptureRequest;
+        response: StageCaptureResponse;
+    };
     'app.info': {
         request: AppInfoRequest;
         response: AppInfoResponse;
@@ -1089,3 +1111,4 @@ export interface MethodMap {
 export type MethodName = keyof MethodMap;
 export type MethodRequest<M extends MethodName> = MethodMap[M]['request'];
 export type MethodResponse<M extends MethodName> = MethodMap[M]['response'];
+export declare const METHOD_NAMES: readonly MethodName[];

package/dist/wire/methods.js

@@ -1 +1,109 @@
-export {};
+// Built from a `Record<MethodName, …>` so a new MethodMap key that is missing
+// here fails the build instead of silently dropping out of the runtime list.
+export const METHOD_NAMES = Object.keys({
+    'scene.list': true,
+    'scene.get': true,
+    'scene.activate': true,
+    'scene.create': true,
+    'scene.duplicate': true,
+    'scene.rename': true,
+    'scene.delete': true,
+    'scene.patch': true,
+    'scene.setLightFollowCamera': true,
+    'scene.inspect': true,
+    'instance.list': true,
+    'instance.get': true,
+    'instance.add': true,
+    'instance.setModel': true,
+    'instance.remove': true,
+    'instance.setVisible': true,
+    'instance.setEffects': true,
+    'instance.setTrackingSources': true,
+    'instance.setControllerMovement': true,
+    'instance.reorder': true,
+    'instance.setPrimary': true,
+    'instance.setPlacement': true,
+    'instance.attach': true,
+    'instance.setMToon': true,
+    'instance.setIdle': true,
+    'instance.setBreath': true,
+    'instance.setLipSync': true,
+    'instance.info': true,
+    'selection.set': true,
+    'selection.get': true,
+    'object.add': true,
+    'object.addMany': true,
+    'object.rename': true,
+    'object.setContent': true,
+    'object.setSpace': true,
+    'object.setPlacement': true,
+    'object.attach': true,
+    'object.setLightOverrides': true,
+    'object.anchors': true,
+    'expression.list': true,
+    'expression.active': true,
+    'expression.toggle': true,
+    'expression.setWeight': true,
+    'expression.getPersistence': true,
+    'expression.setPersistence': true,
+    'motion.list': true,
+    'motion.play': true,
+    'motion.playAsset': true,
+    'motion.playing': true,
+    'motion.stop': true,
+    'speech.play': true,
+    'speech.stop': true,
+    'hotkey.list': true,
+    'hotkey.set': true,
+    'hotkey.trigger': true,
+    'automation.list': true,
+    'automation.run': true,
+    'model.list': true,
+    'model.register': true,
+    'asset.list': true,
+    'asset.register': true,
+    'registry.thumbnail': true,
+    'settings.get': true,
+    'settings.patch': true,
+    'tracking.status': true,
+    'tracking.setEnabled': true,
+    'tracking.setSource': true,
+    'tracking.addSource': true,
+    'tracking.updateSource': true,
+    'tracking.removeSource': true,
+    'pose.setEnabled': true,
+    'pose.setSource': true,
+    'pose.setPort': true,
+    'lipSync.state': true,
+    'lipSync.configure': true,
+    'lipSync.restart': true,
+    'lipSync.calibrate': true,
+    'binding.get': true,
+    'binding.preview': true,
+    'binding.set': true,
+    'binding.release': true,
+    'binding.inputs': true,
+    'binding.override': true,
+    'controller.state': true,
+    'controller.rename': true,
+    'controller.setDeadZone': true,
+    'controller.remove': true,
+    'controller.assign': true,
+    'stage.resetTransform': true,
+    'stage.resetCamera': true,
+    'stage.spawn': true,
+    'stage.clearSpawned': true,
+    'stage.capture': true,
+    'app.info': true,
+    'app.localAddresses': true,
+    'app.stats': true,
+    'session.identify': true,
+    'storage.get': true,
+    'storage.set': true,
+    'storage.delete': true,
+    'storage.list': true,
+    'events.subscribe': true,
+    'events.unsubscribe': true,
+    'param.inject': true,
+    'param.release': true,
+});

package/dist/wire/schemas/requests.d.ts

@@ -163,6 +163,7 @@ export declare const requestSchemas: {
     }, z.core.$strip>;
     'hotkey.trigger': z.ZodObject<{
         hotkeyId: z.ZodString;
+        modelId: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
     'automation.run': z.ZodObject<{
         automationId: z.ZodString;
@@ -330,6 +331,9 @@ export declare const requestSchemas: {
             outMs: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strip>>;
     }, z.core.$strip>;
+    'stage.capture': z.ZodObject<{
+        maxEdge: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
     'events.subscribe': z.ZodObject<{
         events: z.ZodArray<z.ZodCustom<keyof import("../events.ts").EventMap, keyof import("../events.ts").EventMap>>;
     }, z.core.$strip>;

package/dist/wire/schemas/requests.js

@@ -2,7 +2,7 @@ import * as z from 'zod';
 import { CONTROLLER_DEAD_ZONE_MAX } from "../../values/controller.js";
 import { isRecord } from "../../values/guards.js";
 import { ITEM_TRANSITION_STYLES } from "../../values/item-transition.js";
-import { OBJECT_ADD_MANY_MAX, SCENE_COLOR_RE, SPEECH_URL_MAX_LENGTH, STORAGE_KEY_MAX_LENGTH, STORAGE_VALUE_MAX_LENGTH, } from "../../values/limits.js";
+import { OBJECT_ADD_MANY_MAX, SCENE_COLOR_RE, SPEECH_URL_MAX_LENGTH, STAGE_CAPTURE_EDGE_MAX, STAGE_CAPTURE_EDGE_MIN, STORAGE_KEY_MAX_LENGTH, STORAGE_VALUE_MAX_LENGTH, } from "../../values/limits.js";
 import { LIP_SYNC_CALIBRATION_ACTIONS, LIP_SYNC_MODES, LIP_SYNC_PHONEMES, } from "../../values/lipsync.js";
 import { SCENE_TRANSITION_DURATION_MAX_MS, SCENE_TRANSITION_DURATION_MIN_MS, SCENE_TRANSITION_FADE_DEFAULT_MS, SCENE_TRANSITION_SWITCH_POINT_MAX, SCENE_TRANSITION_SWITCH_POINT_MIN, SCENE_TRANSITION_TYPES, } from "../../values/scene-transition.js";
 import { ASSET_KINDS, INJECT_TARGET_TYPES, POSE_SOURCE_IDS, TRACKING_SOURCE_IDS, TRACKING_SOURCE_KINDS, } from "../types.js";
@@ -107,7 +107,7 @@ export const requestSchemas = {
         modelId: nonEmpty.optional(),
         config: z.custom(isRecord, 'config must be a hotkey config'),
     }),
-    'hotkey.trigger': z.object({ hotkeyId: nonEmpty }),
+    'hotkey.trigger': z.object({ hotkeyId: nonEmpty, modelId: nonEmpty.optional() }),
     'automation.run': z.object({ automationId: nonEmpty }),
     'tracking.addSource': z.object({
         // Straight off the kind registry, for the same reason as ASSET_KINDS below: a schema
@@ -168,6 +168,9 @@ export const requestSchemas = {
         })
             .optional(),
     }),
+    'stage.capture': z.object({
+        maxEdge: z.number().int().min(STAGE_CAPTURE_EDGE_MIN).max(STAGE_CAPTURE_EDGE_MAX).optional(),
+    }),
     'events.subscribe': z.object({ events: z.array(lenientEventNameSchema).min(1) }),
     'events.unsubscribe': z.object({ events: z.array(lenientEventNameSchema).optional() }),
     'param.inject': z.object({ entries: z.array(InjectEntrySchema).min(1) }),

package/dist/wire/types.d.ts

@@ -1011,7 +1011,7 @@ export interface Scene {
     name: string;
     /** Models and objects in one list; array order = z-order (bottom to top) within each space. */
     items: SceneItem[];
-    /** Hotkey target and the default instance for model-scoped methods. null only when `items` holds no model. */
+    /** The default hotkey target and the default instance for model-scoped methods. null only when `items` holds no model. */
     primaryInstanceId: string | null;
     background: SceneBackground;
     vrmCamera: SceneCamera;
@@ -1041,7 +1041,7 @@ 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", "automations", "controllers", "model-editing", "asset-inspection", "layer-effects", "scene-transitions", "area-lights", "spot-lights", "camera-follow-lights", "shadow-filters", "environment-map-model", "spawn", "tracking-lost", "motion-stop"];
+export declare const APP_CAPABILITIES: readonly ["storage", "speech", "automations", "controllers", "model-editing", "asset-inspection", "layer-effects", "scene-transitions", "area-lights", "spot-lights", "camera-follow-lights", "shadow-filters", "environment-map-model", "spawn", "tracking-lost", "motion-stop", "stage-capture"];
 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`. */
@@ -1115,13 +1115,21 @@ export interface Hotkey {
     accelerator: string | null;
     global: boolean;
     active: boolean;
+    /** Expression: on only while the combo is held down (VTS `DeactivateAfterKeyUp`). Default false. */
+    hold?: boolean;
+    /** Fade time in seconds, in and out, of the expression or motion; null uses the file's own. 0–2. */
+    fadeSeconds?: number | null;
+    /** Expression: switches itself off after this many seconds. Motion: plays at most this long. null is off. 0.1–3600. */
+    deactivateAfterSeconds?: number | null;
+    /** Motion: holds its last frame until the hotkey fires again (VTS `StopsOnLastFrame`). Default false. */
+    stopsOnLastFrame?: boolean;
 }
 export interface HotkeyConfig {
     keyboardEnabled: boolean;
     hotkeys: Hotkey[];
 }
 export interface HotkeyState extends HotkeyConfig {
-    /** Hotkey ids currently registered with the OS (active model only). */
+    /** Hotkey ids currently registered with the OS (models on stage only). */
     registered: string[];
 }
 /** Action kinds an app automation can carry today; servers may send kinds newer than this list. */

package/dist/wire/types.js

@@ -51,6 +51,8 @@ export const APP_CAPABILITIES = [
     'tracking-lost',
     /** `motion.stop`; `motion.playing` and `motion.started` carry `oneShot`. */
     'motion-stop',
+    /** `stage.capture`. */
+    'stage-capture',
 ];
 export function isAppCapability(v) {
     return isOneOf(v, APP_CAPABILITIES);

package/package.json

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