@laplace.live/persona-sdk 0.8.0 → 0.9.0

package/dist/values/labels.d.ts

@@ -1,6 +1,11 @@
+import type { ShortcutInfo } from '../wire/types.ts';
 /**
  * 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;
+/** English label for one shortcut action kind; kinds newer than this SDK read `Action`. */
+export declare function shortcutActionLabel(kind: string): string;
+/** Display label for an app shortcut: its title, else its action-kind labels joined with ` + `. */
+export declare function shortcutLabel(shortcut: Pick<ShortcutInfo, 'title' | 'actionKinds'>): string;

package/dist/values/labels.js

@@ -7,3 +7,20 @@ export function motionLabel(file) {
     const base = file.split(/[\\/]/).pop() ?? file;
     return base.replace(/\.motion3\.json$|\.exp3\.json$|\.vrma$|\.json$/i, '') || base;
 }
+// English fallbacks; localizing clients keep their own map and use these for unknown kinds.
+const SHORTCUT_ACTION_KIND_LABELS = {
+    'effect-toggle': 'Toggle Effect',
+    'effect-params': 'Effect Settings',
+    'camera-pose': 'Camera Position',
+    'layer-visibility': 'Layer Visibility',
+};
+/** English label for one shortcut action kind; kinds newer than this SDK read `Action`. */
+export function shortcutActionLabel(kind) {
+    return SHORTCUT_ACTION_KIND_LABELS[kind] ?? 'Action';
+}
+/** Display label for an app shortcut: its title, else its action-kind labels joined with ` + `. */
+export function shortcutLabel(shortcut) {
+    if (shortcut.title !== null && shortcut.title !== '')
+        return shortcut.title;
+    return shortcut.actionKinds.map(shortcutActionLabel).join(' + ') || 'Shortcut';
+}

package/dist/wire/errors.js

@@ -4,7 +4,7 @@ export const API_ERROR_CODES = [
     'invalid-request',
     'unknown-method',
     'invalid-params',
-    /** A referenced id (scene, instance, model, asset, hotkey) resolves to nothing. */
+    /** A referenced id (scene, instance, model, asset, hotkey, shortcut, expression) resolves to nothing. */
     'not-found',
     /** The instance's model format cannot perform this method (e.g. MToon on Live2D). */
     'unsupported-for-format',

package/dist/wire/events.d.ts

@@ -1,4 +1,4 @@
-import type { ExpressionPersistence, HotkeyState, ModelFormat, PoseStatus, SceneState, Settings, TrackingStatus } from './types.ts';
+import type { ExpressionPersistence, HotkeyState, ModelFormat, PoseStatus, SceneState, Settings, ShortcutInfo, 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. */
@@ -10,6 +10,10 @@ export interface EventMap {
         modelId: string | null;
         config: HotkeyState;
     };
+    /** The app-shortcut list, its names, or its OS registrations changed. */
+    'shortcut.state': {
+        shortcuts: ShortcutInfo[];
+    };
     /** `sources` maps source id → status; optional so pre-multi-source servers still parse. */
     'tracking.status': {
         tracking: TrackingStatus;

package/dist/wire/events.js

@@ -4,6 +4,7 @@ export const EVENT_NAMES = Object.keys({
     'scene.changed': true,
     'settings.changed': true,
     'hotkey.state': true,
+    'shortcut.state': true,
     'tracking.status': true,
     'instance.loaded': true,
     'expression.changed': true,

package/dist/wire/methods.d.ts

@@ -1,5 +1,5 @@
 import type { EventName } from './events.ts';
-import type { AnchorOption, AppCapability, AssetKind, AssetRef, Attach, Expression, ExpressionPersistence, HotkeyConfig, HotkeyState, InjectEntry, InjectTarget, InstanceRuntime, JsonValue, ModelInfo, ModelRef, MotionGroup, MToonTuning, ObjectContent, ObjectLightOverride, ObjectSpace, Place2D, Place3D, PlayingMotion, PoseSourceId, PoseStatus, Scene, SceneItem, ScenePatch, SceneState, ScreenPlacement, Settings, SettingsPatch, TrackingSourceConfig, TrackingSourceId, TrackingSourceKind, TrackingStatus, VrmPlacement } from './types.ts';
+import type { AnchorOption, AppCapability, AssetKind, AssetRef, Attach, Expression, ExpressionPersistence, HotkeyConfig, HotkeyState, InjectEntry, InjectTarget, InstanceRuntime, JsonValue, ModelInfo, ModelRef, MotionGroup, MToonTuning, ObjectContent, ObjectLightOverride, ObjectSpace, Place2D, Place3D, PlayingMotion, PoseSourceId, PoseStatus, Scene, SceneItem, ScenePatch, SceneState, ScreenPlacement, Settings, SettingsPatch, ShortcutInfo, TrackingSourceConfig, TrackingSourceId, TrackingSourceKind, 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. */
@@ -241,6 +241,14 @@ export interface HotkeyTriggerRequest {
     hotkeyId: string;
 }
 export type HotkeyTriggerResponse = EmptyResponse;
+export type ShortcutListRequest = EmptyRequest;
+export interface ShortcutListResponse {
+    shortcuts: ShortcutInfo[];
+}
+export interface ShortcutTriggerRequest {
+    shortcutId: string;
+}
+export type ShortcutTriggerResponse = EmptyResponse;
 export type ModelListRequest = EmptyRequest;
 export interface ModelListResponse {
     models: ModelRef[];
@@ -612,6 +620,14 @@ export interface MethodMap {
         request: HotkeyTriggerRequest;
         response: HotkeyTriggerResponse;
     };
+    'shortcut.list': {
+        request: ShortcutListRequest;
+        response: ShortcutListResponse;
+    };
+    'shortcut.trigger': {
+        request: ShortcutTriggerRequest;
+        response: ShortcutTriggerResponse;
+    };
     'model.list': {
         request: ModelListRequest;
         response: ModelListResponse;

package/dist/wire/schemas.d.ts

@@ -93,6 +93,9 @@ export declare const requestSchemas: {
     'hotkey.trigger': z.ZodObject<{
         hotkeyId: z.ZodString;
     }, z.core.$strip>;
+    'shortcut.trigger': z.ZodObject<{
+        shortcutId: z.ZodString;
+    }, z.core.$strip>;
     'tracking.addSource': z.ZodObject<{
         kind: z.ZodEnum<{
             "vts-ios": "vts-ios";

package/dist/wire/schemas.js

@@ -76,6 +76,7 @@ export const requestSchemas = {
         config: z.custom(isRecord, 'config must be a hotkey config'),
     }),
     'hotkey.trigger': z.object({ hotkeyId: nonEmpty }),
+    'shortcut.trigger': z.object({ shortcutId: nonEmpty }),
     'tracking.addSource': z.object({
         kind: z.enum(['vts-ios', 'vts-ios-native', 'ifacialmocap', 'vmc']),
         name: z.string().optional(),

package/dist/wire/types.d.ts

@@ -435,7 +435,7 @@ export interface Scene {
     name: string;
     /** Models and objects in one list; array order = z-order (bottom to top) within each space. */
     items: SceneItem[];
-    /** Tracking/pose/hotkey/expression target. null only when `items` holds no model. */
+    /** Hotkey target and the default instance for model-scoped methods. null only when `items` holds no model. */
     primaryInstanceId: string | null;
     background: SceneBackground;
     behavior: SceneBehavior;
@@ -468,7 +468,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"];
+export declare const APP_CAPABILITIES: readonly ["storage", "speech", "shortcuts"];
 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`. */
@@ -533,6 +533,24 @@ export interface HotkeyState extends HotkeyConfig {
     /** Hotkey ids currently registered with the OS (active model only). */
     registered: string[];
 }
+/** Action kinds an app shortcut can carry today; servers may send kinds newer than this list. */
+export declare const SHORTCUT_ACTION_KINDS: readonly ["effect-toggle", "effect-params", "camera-pose", "layer-visibility"];
+export type ShortcutActionKind = (typeof SHORTCUT_ACTION_KINDS)[number];
+/**
+ * One app-level global shortcut (a multi-action macro) as clients see it. Action
+ * payloads stay app-side — `actionKinds` is what drives derived labels.
+ */
+export interface ShortcutInfo {
+    id: string;
+    /** User-given name, or null — derive a label from `actionKinds` (see `shortcutLabel`). */
+    title: string | null;
+    /** Bound key combo, or null for a trigger-only shortcut (`shortcut.trigger` still fires it). */
+    accelerator: string | null;
+    /** May include kinds newer than this SDK; label those generically. */
+    actionKinds: string[];
+    /** Whether the combo is currently registered with the OS. */
+    registered: boolean;
+}
 export interface ExpressionPersistence {
     supported: boolean;
     enabled: boolean;

package/dist/wire/types.js

@@ -12,10 +12,13 @@ export const SHADOW_QUALITY_LEVELS = ['off', 'low', 'medium', 'high', 'extra'];
  * 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'];
+export const APP_CAPABILITIES = ['storage', 'speech', 'shortcuts'];
 export function isAppCapability(v) {
     return typeof v === 'string' && APP_CAPABILITIES.includes(v);
 }
+// ---- App shortcuts --------------------------------------------------------------
+/** Action kinds an app shortcut can carry today; servers may send kinds newer than this list. */
+export const SHORTCUT_ACTION_KINDS = ['effect-toggle', 'effect-params', 'camera-pose', 'layer-visibility'];
 // ---- Settings ------------------------------------------------------------------
 export const TRACKING_SOURCE_IDS = ['vts-ios', 'vts-ios-native', 'ifacialmocap'];
 /** Body-pose protocols. Every one so far is UDP with a configurable port. */

package/package.json

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