@laplace.live/persona-sdk 1.16.0 → 1.18.0

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;
@@ -173,9 +177,8 @@ export declare function objectSupportsSpace(kind: ObjectContent['kind'], space:
 /** The asset an object streams from, or null for kinds that carry their source inline (web, capture). */
 export declare function contentAssetId(content: ObjectContent): string | null;
 /**
- * The one model format a space's objects can ride: the renderers never mix, and
- * the three canvas always composites over the Pixi one, so a cross-space pin
- * would z-fight by construction.
+ * The one model format a space's objects can ride: the screen layer always composites
+ * over the world scene, so a cross-space pin would z-fight by construction.
  */
 export declare function attachableParentFormat(space: ObjectSpace): ModelFormat;
 /**

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;
@@ -297,9 +301,8 @@ export function contentAssetId(content) {
     return content.kind === 'image' || content.kind === 'video' || content.kind === 'prop' ? content.assetId : null;
 }
 /**
- * The one model format a space's objects can ride: the renderers never mix, and
- * the three canvas always composites over the Pixi one, so a cross-space pin
- * would z-fight by construction.
+ * The one model format a space's objects can ride: the screen layer always composites
+ * over the world scene, so a cross-space pin would z-fight by construction.
  */
 export function attachableParentFormat(space) {
     return space === '2d' ? 'live2d' : 'vrm';

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;
@@ -493,6 +494,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 +1039,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 +1109,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/protocol.d.ts

@@ -18,9 +18,10 @@ 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;
 /**
- * How often the binding editor's live indicators sample the tracking inputs (~20/s) — both the
- * stage's push and the editor's poll of it, which must agree. Fast enough to read as live on a
- * level bar, slow enough that neither the worker port nor the panel relay carries per-frame traffic.
+ * Least gap between the stage's refreshes of the tracking inputs behind the binding editor's live
+ * indicators (~20/s at most). The refresh rides the stage's frames, so a capped frame rate
+ * stretches it. Fast enough to read as live, slow enough that the worker port carries no
+ * per-frame traffic.
  */
 export declare const TRACKING_INPUTS_MS = 50;
 /**

package/dist/wire/protocol.js

@@ -17,9 +17,10 @@ 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;
 /**
- * How often the binding editor's live indicators sample the tracking inputs (~20/s) — both the
- * stage's push and the editor's poll of it, which must agree. Fast enough to read as live on a
- * level bar, slow enough that neither the worker port nor the panel relay carries per-frame traffic.
+ * Least gap between the stage's refreshes of the tracking inputs behind the binding editor's live
+ * indicators (~20/s at most). The refresh rides the stage's frames, so a capped frame rate
+ * stretches it. Fast enough to read as live, slow enough that the worker port carries no
+ * per-frame traffic.
  */
 export const TRACKING_INPUTS_MS = 50;
 /**

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

@@ -255,10 +255,6 @@ export declare const requestSchemas: {
                     medium: "medium";
                 }>>;
                 renderScale: z.ZodOptional<z.ZodNumber>;
-                live2dEngine: z.ZodOptional<z.ZodEnum<{
-                    pixi: "pixi";
-                    three: "three";
-                }>>;
             }, z.core.$strip>>;
         }, z.core.$strip>;
     }, z.core.$strip>;
@@ -334,6 +330,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";
@@ -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/schemas/settings.d.ts

@@ -1,10 +1,6 @@
 import * as z from 'zod';
 /** Shared field definitions; parsing validates values without adding defaults or healing them. */
 export declare const PortSchema: z.ZodNumber;
-export declare const Live2DEngineSchema: z.ZodEnum<{
-    pixi: "pixi";
-    three: "three";
-}>;
 export declare const EffectsQualitySchema: z.ZodEnum<{
     high: "high";
     low: "low";
@@ -110,10 +106,6 @@ export declare const PerformanceSettingsSchema: z.ZodObject<{
         medium: "medium";
     }>;
     renderScale: z.ZodNumber;
-    live2dEngine: z.ZodEnum<{
-        pixi: "pixi";
-        three: "three";
-    }>;
 }, z.core.$strip>;
 /** Stage content dimensions in device-independent pixels. */
 export declare const StageSizeSchema: z.ZodObject<{
@@ -201,10 +193,6 @@ export declare const SettingsSchema: z.ZodObject<{
             medium: "medium";
         }>;
         renderScale: z.ZodOptional<z.ZodNumber>;
-        live2dEngine: z.ZodOptional<z.ZodEnum<{
-            pixi: "pixi";
-            three: "three";
-        }>>;
     }, z.core.$strip>;
     tracking: z.ZodObject<{
         enabled: z.ZodBoolean;
@@ -276,9 +264,5 @@ export declare const SettingsPatchSchema: z.ZodObject<{
             medium: "medium";
         }>>;
         renderScale: z.ZodOptional<z.ZodNumber>;
-        live2dEngine: z.ZodOptional<z.ZodEnum<{
-            pixi: "pixi";
-            three: "three";
-        }>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;

package/dist/wire/schemas/settings.js

@@ -2,10 +2,9 @@ import * as z from 'zod';
 import { CONTROLLER_DEAD_ZONE_MAX } from "../../values/controller.js";
 import { LIP_SYNC_GAIN_MAX, LIP_SYNC_MAX_SAMPLES, LIP_SYNC_MFCC_COEFFICIENTS, LIP_SYNC_MIN_SAMPLES, LIP_SYNC_NOISE_GATE_MIN, LIP_SYNC_PHONEMES, LIP_SYNC_SMOOTHING_MAX, } from "../../values/lipsync.js";
 import { LOCALES } from "../../values/locale.js";
-import { EFFECTS_QUALITY_LEVELS, LIVE2D_ENGINES, MEDIAPIPE_DELEGATES, POSE_SOURCE_IDS, TRACKING_SOURCE_IDS, TRACKING_SOURCE_KINDS, } from "../types.js";
+import { EFFECTS_QUALITY_LEVELS, MEDIAPIPE_DELEGATES, POSE_SOURCE_IDS, TRACKING_SOURCE_IDS, TRACKING_SOURCE_KINDS, } from "../types.js";
 /** Shared field definitions; parsing validates values without adding defaults or healing them. */
 export const PortSchema = z.number().int().min(1).max(65535).describe('Network port, from 1 through 65535.');
-export const Live2DEngineSchema = z.enum(LIVE2D_ENGINES).describe('Engine used to render Live2D models.');
 export const EffectsQualitySchema = z.enum(EFFECTS_QUALITY_LEVELS).describe('Scene and layer effects quality tier.');
 export const LanguageSettingSchema = z
     .enum(['system', ...LOCALES])
@@ -75,7 +74,6 @@ export const PerformanceSettingsSchema = z.object({
     fpsLimit: z.number().describe('Frame-rate cap; zero is unlimited. The desktop snaps changes to supported presets.'),
     effectsQuality: EffectsQualitySchema,
     renderScale: z.number().describe('Render resolution multiplier. The desktop snaps changes to supported presets.'),
-    live2dEngine: Live2DEngineSchema,
 });
 /** Stage content dimensions in device-independent pixels. */
 export const StageSizeSchema = z.object({
@@ -107,7 +105,7 @@ export const SettingsSchema = z.object({
     ui: z
         .object({ trayVisible: z.boolean().describe('Show the tray or menu bar icon.') })
         .describe('Public interface preferences.'),
-    performance: PerformanceSettingsSchema.partial({ renderScale: true, live2dEngine: true }).describe('Renderer settings; renderScale and live2dEngine are absent on older hosts.'),
+    performance: PerformanceSettingsSchema.partial({ renderScale: true }).describe('Renderer settings; renderScale is absent on older hosts.'),
     tracking: TrackingSettingsSchema.describe('Network face master switch and all configured tracking sources.'),
     pose: PoseSettingsSchema.describe('Network body master switch and legacy source mirrors.'),
 });

package/dist/wire/types.d.ts

@@ -286,7 +286,7 @@ export interface AttachElasticity {
  * value: the two ends clear the parent's whole stack, and `artMesh` slots the item in directly
  * above that ArtMesh, so every parent mesh over it paints on top. Ids rather than positions,
  * because Cubism re-sorts the stack as motions play, and an id carries to any rig that has it.
- * Live2D parents on the three engine only: elsewhere an item always paints in front.
+ * Live2D parents only: on a VRM an item always paints in front.
  */
 export type AttachDepth = {
     kind: 'front';
@@ -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`. */
@@ -1052,12 +1052,15 @@ export type InstanceCapability = 'motions' | 'expressions' | 'placement-2d' | 'p
  | '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. */
+/**
+ * `speech.play` lip-sync. Loaded Live2D models only; 0.53 and earlier hosts also omit it under
+ * the Pixi engine, so gate on the runtime, not the format.
+ */
  | '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.
+ * reach it. Every model; 0.53 and earlier hosts omit it on Pixi-engine Live2D, so read it off
+ * the runtime rather than the format.
  */
  | 'post-fx';
 export interface InstanceRuntime {
@@ -1157,8 +1160,6 @@ export interface ExpressionPersistence {
 export type JsonValue = string | number | boolean | null | JsonValue[] | {
     [key: string]: JsonValue;
 };
-export declare const LIVE2D_ENGINES: readonly ["pixi", "three"];
-export type Live2DEngine = (typeof LIVE2D_ENGINES)[number];
 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. */

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);
@@ -82,7 +84,6 @@ export const AUTOMATION_BOUNDARY_KINDS = [
     'load-model',
 ];
 // ---- Settings ------------------------------------------------------------------
-export const LIVE2D_ENGINES = ['pixi', 'three'];
 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', 'mocopi'];

package/package.json

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