@laplace.live/persona-sdk 1.21.0 → 1.23.0

package/dist/values/limits.js

@@ -94,6 +94,78 @@ export const SCENE_FOV_MAX = 90;
 /** Nonsingular authored field of view in degrees, including every valid whole-degree VMD key. */
 export const CAMERA_FOV_MIN = 1;
 export const CAMERA_FOV_MAX = 179;
+/** Ceiling for each follow and aim damping, in seconds. */
+export const CAMERA_DAMPING_MAX = 10;
+/** Ceiling for {@link SceneCameraAim}'s lookahead time, in seconds, and its smoothing. */
+export const CAMERA_AIM_LOOKAHEAD_MAX = 1;
+export const CAMERA_AIM_SMOOTHING_MAX = 30;
+/** Ceiling for {@link SceneCameraHandheld}'s speed. */
+export const CAMERA_HANDHELD_SPEED_MAX = 2;
+/** Warudo's Handheld Movement defaults, switched off. */
+export const DEFAULT_CAMERA_HANDHELD = { enabled: false, intensity: 0.5, speed: 1 };
+/**
+ * A fresh follow's damping: Warudo's second of position lag, and half a second on each turn so a
+ * tracked head's jitter never shakes the view.
+ */
+export const DEFAULT_CAMERA_FOLLOW_DAMPING = { x: 1, y: 1, z: 1, yaw: 0.5, pitch: 0.5, roll: 0.5 };
+/** Where a fresh follow, aim or focus tracks a model; an object is always tracked by its root. */
+export const DEFAULT_CAMERA_ANCHOR = { kind: 'bone', bone: 'head' };
+/** A fresh follow's settings: position only. */
+export function defaultCameraFollowSettings() {
+    return { anchor: DEFAULT_CAMERA_ANCHOR, binding: 'world', damping: { ...DEFAULT_CAMERA_FOLLOW_DAMPING } };
+}
+/** A fresh follow of `target`, position only. */
+export function defaultCameraFollow(target) {
+    return { ...target, ...defaultCameraFollowSettings() };
+}
+/** A fresh aim's settings, Warudo's Composer defaults: centred, no dead zone, 0.8 soft zone. */
+export function defaultCameraAimSettings() {
+    return {
+        anchor: DEFAULT_CAMERA_ANCHOR,
+        screenX: 0.5,
+        screenY: 0.5,
+        deadZone: { width: 0, height: 0 },
+        softZone: { width: 0.8, height: 0.8 },
+        bias: { x: 0, y: 0 },
+        damping: { horizontal: 0.5, vertical: 0.5 },
+        lookahead: { time: 0, smoothing: 0.5, ignoreY: false },
+    };
+}
+/** A fresh aim at `target`. */
+export function defaultCameraAim(target) {
+    return { ...target, ...defaultCameraAimSettings() };
+}
+/** A fresh focus's settings, refocusing about as fast as Warudo's default focusing speed. */
+export function defaultCameraFocusSettings() {
+    return { anchor: DEFAULT_CAMERA_ANCHOR, damping: 0.2 };
+}
+/** A fresh focus on `target`. */
+export function defaultCameraFocus(target) {
+    return { ...target, ...defaultCameraFocusSettings() };
+}
+/** A follow's, aim's or focus's settings alone, without the layer it names. */
+export function cameraTrackSettingsOf(track) {
+    const { instanceId: _instanceId, target: _target, ...settings } = track;
+    return settings;
+}
+/** The instance `target` tracks in a scene whose primary model is `primaryInstanceId`. */
+export function cameraTrackInstanceId(target, primaryInstanceId) {
+    return target.target === 'primary' ? primaryInstanceId : target.instanceId;
+}
+/** How a camera can track `item`: by any anchor on a VRM model, by the root of a 3D object, or not at all. */
+export function cameraTrackKind(item) {
+    if (item.kind === 'model')
+        return item.ref.kind === 'vrm' ? 'model' : null;
+    return item.space === '3d' ? 'object' : null;
+}
+/** Rows for the camera's follow, aim and focus pickers, in layer order. One rule, or the console offers a layer the desktop drops. */
+export function cameraTrackCandidates(items) {
+    return items.flatMap(item => {
+        const kind = cameraTrackKind(item);
+        const name = item.kind === 'model' ? item.ref.name : item.name;
+        return kind ? [{ instanceId: item.instanceId, name, model: kind === 'model' }] : [];
+    });
+}
 /** Manual navigation stops short of ±90°; authored camera elevations remain unrestricted. */
 export const ELEVATION_LIMIT = (80 * Math.PI) / 180;
 /** Manual navigation distance bounds; authored cameras retain signed, unrestricted distances. */
@@ -292,11 +364,49 @@ export const WEB_SIZE_MAX = 7680;
 /** Web object paint-rate bounds, frames per second. */
 export const WEB_FPS_MIN = 1;
 export const WEB_FPS_MAX = 60;
+/** Chroma key tolerance bounds, OBS's 1–1000 ÷ 1000; the floor keeps the edge ramps from dividing by zero. */
+export const CHROMA_KEY_TOLERANCE_MIN = 0.001;
+export const CHROMA_KEY_TOLERANCE_MAX = 1;
+/** OBS's Chroma Key defaults: green, similarity 400, smoothness 80, spill reduction 100. */
+export const DEFAULT_CHROMA_KEY = {
+    enabled: false,
+    color: '#00ff00',
+    similarity: 0.4,
+    smoothness: 0.08,
+    spill: 0.1,
+};
+/** Whether a chroma key can reach the content's pixels: image, video and webpage quads. */
+export function isKeyableContent(content) {
+    return content.kind === 'image' || content.kind === 'video' || content.kind === 'web';
+}
+/** Text object bounds: characters, em size in px, and the box and paint extents in px. */
+export const TEXT_LENGTH_MAX = 10_000;
+export const TEXT_SIZE_MIN = 4;
+export const TEXT_SIZE_MAX = 1000;
+export const TEXT_SHEAR_MAX = 1;
+/** Letter and word spacing, em. */
+export const TEXT_SPACING_MIN = -0.5;
+export const TEXT_SPACING_MAX = 2;
+export const TEXT_LINE_HEIGHT_MIN = 0.5;
+export const TEXT_LINE_HEIGHT_MAX = 4;
+export const TEXT_BOX_MAX = 7680;
+export const TEXT_STROKE_MAX = 100;
+export const TEXT_SHADOW_OFFSET_MAX = 200;
+export const TEXT_SHADOW_BLUR_MAX = 100;
+export const TEXT_PLATE_PADDING_MAX = 500;
+export const TEXT_PLATE_RADIUS_MAX = 500;
+/** 3D text: extrusion and bevel in em, bevel segments, and emission strength. */
+export const TEXT_EXTRUDE_MAX = 2;
+export const TEXT_BEVEL_MAX = 0.2;
+export const TEXT_BEVEL_RESOLUTION_MAX = 8;
+export const TEXT_EMISSION_MAX = 4;
+/** A PostScript name: printable ASCII, at most 63 chars, minus the quote and backslash that would escape `local("…")`. */
+export const TEXT_POSTSCRIPT_NAME_RE = /^[\x21\x23-\x5b\x5d-\x7e]{1,63}$/;
 /** A prop is a mesh, so it only exists in the three.js scene; every other kind renders in both. */
 export function objectSupportsSpace(kind, space) {
     return kind === 'prop' ? space === '3d' : true;
 }
-/** The asset an object streams from, or null for kinds that carry their source inline (web, capture). */
+/** The asset an object streams from, or null for kinds that carry their source inline (web, capture, text). */
 export function contentAssetId(content) {
     return content.kind === 'image' || content.kind === 'video' || content.kind === 'prop' ? content.assetId : null;
 }
@@ -367,24 +477,27 @@ export function depthStopIndex(meshes, depth) {
     const at = meshes.indexOf(depth.id);
     return at < 0 ? meshes.length + 1 : at + 1;
 }
-/** A fresh pin onto `parentInstanceId`: root anchor, in front of the model, no response tuning. */
-export function defaultAttach(parentInstanceId) {
+export const DEFAULT_HEAD_ANGLE = {
+    multiplier: 1,
+    parallaxX: 0,
+    parallaxY: 0,
+    smoothing: 15,
+};
+/**
+ * A fresh pin onto `parentInstanceId`: root anchor, in front of the model. A screen-space item (a
+ * Live2D model, a 2D object) follows the host's head at the default response; others take none.
+ */
+export function defaultAttach(parentInstanceId, screenSpace = false) {
     return {
         parentInstanceId,
         anchor: { kind: 'root' },
         followRotation: true,
         depth: { kind: 'front' },
         split: null,
-        headAngle: null,
+        headAngle: screenSpace ? { ...DEFAULT_HEAD_ANGLE } : null,
         elasticity: null,
     };
 }
-export const DEFAULT_HEAD_ANGLE = {
-    multiplier: 1,
-    parallaxX: 0,
-    parallaxY: 0,
-    smoothing: 15,
-};
 export const ATTACH_MULTIPLIER_MIN = -2;
 export const ATTACH_MULTIPLIER_MAX = 2;
 /** Parallax slider ceiling, symmetric: stage px at a full head turn. */

package/dist/values/stage-info.d.ts

@@ -19,6 +19,11 @@ export interface SceneAssetInfo {
     extensions: string[] | null;
     mediaSize: ObjectMediaSize | null;
 }
+/** One scene object's loaded metadata. */
+export interface SceneObjectInfo extends SceneAssetInfo {
+    /** A text object's transient text, null while it shows the saved one; absent on other kinds and older hosts. */
+    liveText?: string | null;
+}
 /** Metadata for the active scene, tagged so a response from a previous scene can be discarded. */
 export interface SceneInspection {
     sceneId: string;
@@ -26,5 +31,5 @@ export interface SceneInspection {
         /** The set's own bounding radius before placement scale, for `cameraDistanceLimits`; omitted by older hosts. */
         radius?: number | null;
     };
-    objects: Record<string, SceneAssetInfo>;
+    objects: Record<string, SceneObjectInfo>;
 }

package/dist/wire/events.d.ts

@@ -30,6 +30,14 @@ export interface EventMap {
         instanceId: string;
         format: ModelFormat;
     };
+    /**
+     * An instance's motion or expression list changed without a reload — a recorded motion, an edited
+     * expression file, or a registered clip a VRM lists: re-run `motion.list` or `expression.list`.
+     */
+    'instance.listing': {
+        instanceId: string;
+        listing: 'motions' | 'expressions';
+    };
     /** `weights` rides along on instances with `expression-weights`; a drag is not echoed (see `expression.setWeight`). */
     'expression.changed': {
         instanceId: string;

package/dist/wire/events.js

@@ -8,6 +8,7 @@ export const EVENT_NAMES = Object.keys({
     'automation.state': true,
     'tracking.status': true,
     'instance.loaded': true,
+    'instance.listing': true,
     'expression.changed': true,
     'motion.started': true,
     'motion.ended': true,

package/dist/wire/methods.d.ts

@@ -5,7 +5,7 @@ import type { LipSyncCalibrationCommand, LipSyncConfig, LipSyncMode, LipSyncStat
 import type { ModelMovementConfig, ModelMovementEdit } from '../values/model-movement.ts';
 import type { SceneInspection } from '../values/stage-info.ts';
 import type { EventName } from './events.ts';
-import type { AnchorOption, AppCapability, AssetKind, AssetRef, Attach, AttachHeadAngle, AutomationInfo, BindingInput, Expression, ExpressionPersistence, HandTrackingMode, HotkeyConfig, HotkeyState, InjectEntry, InjectTarget, InstanceRuntime, JsonValue, LayerEffectKey, LayerEffects, LayerEffectsPatch, MediaPipeConfig, ModelInfo, ModelRef, MotionGroup, MToonTuning, ObjectContent, ObjectLightOverride, ObjectSpace, Place2D, Place3D, PlayingMotion, PoseSourceId, PoseStatus, Scene, SceneItem, SceneLight, SceneLightCameraFollowOptions, ScenePatch, SceneState, ScreenPlacement, Settings, SettingsPatch, TrackingLostBehavior, TrackingSourceConfig, TrackingSourceId, TrackingSourceKind, TrackingStatus, VrmPlacement } from './types.ts';
+import type { AnchorOption, AppCapability, AssetKind, AssetRef, Attach, AttachHeadAngle, AutomationInfo, BindingInput, Expression, ExpressionPersistence, FontFamilyInfo, HandTrackingMode, HotkeyConfig, HotkeyState, InjectEntry, InjectTarget, InstanceRuntime, JsonValue, LayerEffectKey, LayerEffects, LayerEffectsPatch, MediaPipeConfig, ModelInfo, ModelRef, MotionGroup, MToonTuning, ObjectContent, ObjectLightOverride, ObjectSpace, Place2D, Place3D, PlayingMotion, PoseSourceId, PoseStatus, Scene, SceneItem, SceneLight, SceneLightCameraFollowOptions, ScenePatch, SceneState, ScreenPlacement, Settings, SettingsPatch, TrackingLostBehavior, 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. */
@@ -215,6 +215,15 @@ export interface ObjectSetContentRequest {
     content: ObjectContent;
 }
 export type ObjectSetContentResponse = EmptyResponse;
+/** A `text` object's text alone, under `text-objects`. */
+export interface ObjectSetTextRequest {
+    instanceId: string;
+    /** Null drops a transient text, showing the saved one again. */
+    text: string | null;
+    /** Show it without saving: no `scenes.json` write and no undo step. */
+    transient?: boolean;
+}
+export type ObjectSetTextResponse = EmptyResponse;
 export interface ObjectSetSpaceRequest {
     instanceId: string;
     space: ObjectSpace;
@@ -361,6 +370,11 @@ export type AssetListRequest = EmptyRequest;
 export interface AssetListResponse {
     assets: AssetRef[];
 }
+export type FontsListRequest = EmptyRequest;
+/** The host machine's installed families — what a text object's `font` can name. */
+export interface FontsListResponse {
+    families: FontFamilyInfo[];
+}
 /** Register a model entry file under a user-configured plugin folder. */
 export interface ModelRegisterRequest {
     path: string;
@@ -887,6 +901,10 @@ export interface MethodMap {
         request: ObjectSetContentRequest;
         response: ObjectSetContentResponse;
     };
+    'object.setText': {
+        request: ObjectSetTextRequest;
+        response: ObjectSetTextResponse;
+    };
     'object.setSpace': {
         request: ObjectSetSpaceRequest;
         response: ObjectSetSpaceResponse;
@@ -988,6 +1006,10 @@ export interface MethodMap {
         request: AssetListRequest;
         response: AssetListResponse;
     };
+    'fonts.list': {
+        request: FontsListRequest;
+        response: FontsListResponse;
+    };
     'model.register': {
         request: ModelRegisterRequest;
         response: ModelRegisterResponse;

package/dist/wire/methods.js

@@ -35,6 +35,7 @@ export const METHOD_NAMES = Object.keys({
     'object.addMany': true,
     'object.rename': true,
     'object.setContent': true,
+    'object.setText': true,
     'object.setSpace': true,
     'object.setPlacement': true,
     'object.attach': true,
@@ -63,6 +64,7 @@ export const METHOD_NAMES = Object.keys({
     'model.getMovement': true,
     'model.setMovement': true,
     'asset.list': true,
+    'fonts.list': true,
     'asset.register': true,
     'registry.thumbnail': true,
     'settings.get': true,

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

@@ -7,8 +7,8 @@ export declare const SceneTransitionSchema: z.ZodObject<{
         image: "image";
         video: "video";
         circle: "circle";
-        cut: "cut";
         fade: "fade";
+        cut: "cut";
         wipe: "wipe";
     }>;
     durationMs: z.ZodNumber;
@@ -234,6 +234,7 @@ export declare const requestSchemas: {
             lut: "lut";
             animation: "animation";
             cameraMotion: "cameraMotion";
+            lyrics: "lyrics";
         }>>;
     }, z.core.$strip>;
     'settings.patch': z.ZodObject<{
@@ -328,12 +329,13 @@ export declare const requestSchemas: {
         scale: z.ZodOptional<z.ZodNumber>;
         ttlMs: z.ZodOptional<z.ZodNumber>;
         transition: z.ZodOptional<z.ZodObject<{
-            style: z.ZodOptional<z.ZodEnum<{
-                glitch: "glitch";
-                dither: "dither";
+            style: z.ZodOptional<z.ZodPipe<z.ZodEnum<{
                 pop: "pop";
+                glitch: "glitch";
+                fade: "fade";
                 cut: "cut";
-            }>>;
+                dither: "dither";
+            }>, z.ZodTransform<"pop" | "glitch" | "fade" | "cut", "pop" | "glitch" | "fade" | "cut" | "dither">>>;
             inMs: z.ZodOptional<z.ZodNumber>;
             outMs: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strip>>;

package/dist/wire/schemas/requests.js

@@ -1,7 +1,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 { ITEM_TRANSITION_STYLES, LEGACY_DITHER_STYLE } from "../../values/item-transition.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";
@@ -168,7 +168,11 @@ export const requestSchemas = {
         ttlMs: z.number().optional(),
         transition: z
             .object({
-            style: z.enum(ITEM_TRANSITION_STYLES).optional(),
+            // Older clients still send `fade` by its old name.
+            style: z
+                .enum([...ITEM_TRANSITION_STYLES, LEGACY_DITHER_STYLE])
+                .transform(style => (style === LEGACY_DITHER_STYLE ? 'fade' : style))
+                .optional(),
             inMs: z.number().optional(),
             outMs: z.number().optional(),
         })