@laplace.live/persona-sdk 0.14.0 → 0.16.0

package/dist/index.d.ts

@@ -3,6 +3,7 @@ export * from './client/client.ts';
 export * from './values/custom-effect.ts';
 export * from './values/effect-schema.ts';
 export * from './values/guards.ts';
+export * from './values/hotkeys.ts';
 export * from './values/labels.ts';
 export * from './values/limits.ts';
 export * from './values/locale.ts';

package/dist/index.js

@@ -5,6 +5,7 @@ export * from "./client/client.js";
 export * from "./values/custom-effect.js";
 export * from "./values/effect-schema.js";
 export * from "./values/guards.js";
+export * from "./values/hotkeys.js";
 export * from "./values/labels.js";
 export * from "./values/limits.js";
 export * from "./values/locale.js";

package/dist/values/hotkeys.d.ts

@@ -0,0 +1,2 @@
+/** True when the combo carries a command modifier and so may be registered globally. */
+export declare function hasCommandModifier(accelerator: string | null): boolean;

package/dist/values/hotkeys.js

@@ -0,0 +1,11 @@
+// Hotkey rules every consumer must agree on: main decides OS registration by them, and a
+// client reading `Hotkey.global` off the wire needs the same rule to know the flag can apply.
+// Shift is deliberately absent: Shift+letter is how text is typed, and a global
+// registration consumes the combo system-wide (VTS can allow it because it observes).
+const COMMAND_MODIFIERS = ['Control', 'Alt', 'Super'];
+/** True when the combo carries a command modifier and so may be registered globally. */
+export function hasCommandModifier(accelerator) {
+    if (accelerator === null)
+        return false;
+    return accelerator.split('+').some(t => COMMAND_MODIFIERS.includes(t));
+}

package/dist/wire/events.d.ts

@@ -25,9 +25,11 @@ export interface EventMap {
         instanceId: string;
         format: ModelFormat;
     };
+    /** `weights` rides along on instances with `expression-weights`; a drag is not echoed (see `expression.setWeight`). */
     'expression.changed': {
         instanceId: string;
         active: string[];
+        weights?: Record<string, number>;
     };
     'motion.started': {
         instanceId: string;

package/dist/wire/methods.d.ts

@@ -190,6 +190,17 @@ export interface ExpressionToggleRequest {
 export interface ExpressionToggleResponse {
     active: string[];
 }
+/** Reweight an expression that is already active — a weight on an inactive one would be invisible. */
+export interface ExpressionSetWeightRequest {
+    instanceId?: string;
+    name: string;
+    /** 0..1. */
+    weight: number;
+}
+export interface ExpressionSetWeightResponse {
+    /** Every active expression's weight, in activation order. */
+    weights: Record<string, number>;
+}
 export interface ExpressionGetPersistenceRequest {
     modelId?: string;
 }
@@ -580,6 +591,10 @@ export interface MethodMap {
         request: ExpressionToggleRequest;
         response: ExpressionToggleResponse;
     };
+    'expression.setWeight': {
+        request: ExpressionSetWeightRequest;
+        response: ExpressionSetWeightResponse;
+    };
     'expression.getPersistence': {
         request: ExpressionGetPersistenceRequest;
         response: ExpressionGetPersistenceResponse;

package/dist/wire/schemas.d.ts

@@ -127,6 +127,8 @@ export declare const requestSchemas: {
             prop: "prop";
             ibl: "ibl";
             lut: "lut";
+            animation: "animation";
+            cameraMotion: "cameraMotion";
         }>>;
     }, z.core.$strip>;
     'settings.patch': z.ZodObject<{

package/dist/wire/schemas.js

@@ -1,6 +1,7 @@
 import * as z from 'zod';
 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 } from "./types.js";
 // Runtime validation for the request side of the wire. Schemas exist for the
 // methods whose params the app's main process consumes directly; methods without
 // one are stage-owned — the renderer validates and heals them (same rules as the
@@ -91,7 +92,9 @@ export const requestSchemas = {
     }),
     'tracking.removeSource': z.object({ id: nonEmpty }),
     'model.register': z.object({ path: nonEmpty }),
-    'asset.register': z.object({ path: nonEmpty, want: z.enum(['image', 'video', 'prop', 'ibl', 'lut']).optional() }),
+    // Straight off ASSET_KINDS: a kind added there has to reach the wire gate too, or
+    // `want` answers invalid-params for a kind the registry already knows how to take.
+    'asset.register': z.object({ path: nonEmpty, want: z.enum(ASSET_KINDS).optional() }),
     'settings.patch': z.object({ settings: SettingsPatchSchema }),
     'tracking.setEnabled': z.object({ enabled: z.boolean() }),
     'tracking.setSource': z.object({ source: z.enum(['vts-ios', 'vts-ios-native', 'ifacialmocap']) }),

package/dist/wire/types.d.ts

@@ -1,8 +1,12 @@
 export type ModelFormat = 'live2d' | 'vrm';
 /** Where an item came from: shipped with the app, or added by the user. */
 export type ContentOrigin = 'bundled' | 'user';
-/** How a registered file is labelled. Wider than an object's content kinds: `.hdr` is only ever an environment map. */
-export declare const ASSET_KINDS: readonly ["image", "video", "prop", "ibl", "lut", "animation"];
+/**
+ * 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
+ * frames a shot, `animation` for one that drives a rig.
+ */
+export declare const ASSET_KINDS: readonly ["image", "video", "prop", "ibl", "lut", "animation", "cameraMotion"];
 export type AssetKind = (typeof ASSET_KINDS)[number];
 /** Narrow a kind string to the set the asset registry owns — models and effects have their own. */
 export declare function isAssetKind(v: unknown): v is AssetKind;
@@ -266,6 +270,11 @@ export interface OrbitTransform {
 export interface SceneCamera {
     orbit: OrbitTransform | null;
     fov: number;
+    /**
+     * A `cameraMotion` asset driving the camera, or null for the user's own orbit. While one
+     * is set it overrides `orbit` and `fov` every frame; neither field is written back.
+     */
+    clipAssetId: string | null;
 }
 export type SceneLightType = 'directional' | 'point' | 'ambient';
 /**
@@ -706,8 +715,16 @@ 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'
+/** `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. */
- | 'speech';
+ | 'speech'
+/**
+ * Draws through the 3D post chain, so the scene's look rows (tone mapping, exposure, LUT)
+ * reach it. Always on VRM; on Live2D only under the `three` renderer, so read it off the
+ * runtime rather than the format.
+ */
+ | 'post-fx';
 export interface InstanceRuntime {
     instanceId: string;
     kind: 'model' | 'object';
@@ -724,6 +741,14 @@ export interface Expression {
     name: string;
     file: string | null;
     active: boolean;
+    /**
+     * A wardrobe piece (`LAPLACE_outfit`), not a face. Group these apart: "Jacket Off"
+     * listed between `blinkLeft` and `happy` reads as an expression when it is not one.
+     * Absent on formats with no wardrobe.
+     */
+    outfit?: boolean;
+    /** Blend weight (0..1) while active; absent unless the instance has `expression-weights`. */
+    weight?: number;
 }
 export interface PlayingMotion {
     group: string;

package/dist/wire/types.js

@@ -1,8 +1,12 @@
 // The API's data model: the entity shapes that requests, responses, and events
 // carry. Structural mirrors of the app's scene/settings models, minus anything
 // filesystem-shaped — model refs are sanitized to ids, never directories.
-/** How a registered file is labelled. Wider than an object's content kinds: `.hdr` is only ever an environment map. */
-export const ASSET_KINDS = ['image', 'video', 'prop', 'ibl', 'lut', 'animation'];
+/**
+ * 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
+ * frames a shot, `animation` for one that drives a rig.
+ */
+export const ASSET_KINDS = ['image', 'video', 'prop', 'ibl', 'lut', 'animation', 'cameraMotion'];
 /** Narrow a kind string to the set the asset registry owns — models and effects have their own. */
 export function isAssetKind(v) {
     return typeof v === 'string' && ASSET_KINDS.includes(v);

package/package.json

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