@laplace.live/persona-sdk 1.21.0 → 1.22.0

package/dist/client/client.js

@@ -2,6 +2,7 @@ import { parseServerMessage } from "../wire/envelope.js";
 import { PersonaApiError } from "../wire/errors.js";
 import { CLOSE_FORCE_DISCONNECTED, CLOSE_KEY_REVOKED, INJECT_HEARTBEAT_MS, injectTargetKey, PROTOCOL_VERSION, SCENE_ACTIVATION_TIMEOUT_MS, } from "../wire/protocol.js";
 import { personaWsUrl } from "./address.js";
+import { renameLegacyKinds } from "./legacy-kinds.js";
 const DEFAULTS = {
     url: personaWsUrl(),
     reconnectDelayMs: 500,
@@ -109,7 +110,8 @@ export class PersonaClient {
                 reject(new Error(`request timed out: ${method}`));
             }, this.opts.requestTimeoutMs ??
                 (method === 'scene.activate' ? SCENE_ACTIVATION_TIMEOUT_MS : DEFAULTS.requestTimeoutMs));
-            this.pending.set(id, { resolve: resolve, reject, timer });
+            // Only the runtime id ties a response back to `M`, and its result is unvalidated wire JSON.
+            this.pending.set(id, { method, resolve: resolve, reject, timer });
             ws.send(JSON.stringify({ kind: 'request', id, method, ...(params === undefined ? {} : { params }) }));
         });
     }
@@ -355,8 +357,10 @@ export class PersonaClient {
             const set = this.listeners.get(msg.event);
             if (!set)
                 return;
+            const data = renameLegacyKinds(msg.event, msg.data);
+            // Only `msg.event` ties these callbacks to their payload type, and the payload is unvalidated wire JSON.
             for (const cb of set)
-                cb(msg.data);
+                cb(data);
             return;
         }
         const { id } = msg;
@@ -368,7 +372,7 @@ export class PersonaClient {
         this.pending.delete(id);
         clearTimeout(p.timer);
         if (msg.kind === 'response')
-            p.resolve(msg.result);
+            p.resolve(renameLegacyKinds(p.method, msg.result));
         else
             p.reject(new PersonaApiError(msg.code, msg.message));
     }

package/dist/client/legacy-kinds.d.ts

@@ -0,0 +1,2 @@
+/** A method result or event payload with the action kinds an older host still sends renamed to current ones. */
+export declare function renameLegacyKinds(name: string, data: unknown): unknown;

package/dist/client/legacy-kinds.js

@@ -0,0 +1,40 @@
+import { isRecord } from "../values/guards.js";
+import { canonicalActionKind } from "../wire/types.js";
+function renameHotkeyActions(state) {
+    if (!isRecord(state) || !Array.isArray(state.hotkeys))
+        return state;
+    return {
+        ...state,
+        hotkeys: state.hotkeys.map((hotkey) => isRecord(hotkey) && typeof hotkey.action === 'string'
+            ? { ...hotkey, action: canonicalActionKind(hotkey.action) }
+            : hotkey),
+    };
+}
+function renameActionKinds(list) {
+    if (!isRecord(list) || !Array.isArray(list.automations))
+        return list;
+    return {
+        ...list,
+        automations: list.automations.map((automation) => isRecord(automation) && Array.isArray(automation.actionKinds)
+            ? {
+                ...automation,
+                actionKinds: automation.actionKinds.map((kind) => typeof kind === 'string' ? canonicalActionKind(kind) : kind),
+            }
+            : automation),
+    };
+}
+/** A method result or event payload with the action kinds an older host still sends renamed to current ones. */
+export function renameLegacyKinds(name, data) {
+    switch (name) {
+        case 'hotkey.list':
+        case 'hotkey.set':
+            return renameHotkeyActions(data);
+        case 'hotkey.state':
+            return isRecord(data) ? { ...data, config: renameHotkeyActions(data.config) } : data;
+        case 'automation.list':
+        case 'automation.state':
+            return renameActionKinds(data);
+        default:
+            return data;
+    }
+}

package/dist/index.d.ts

@@ -10,6 +10,7 @@ export * from './values/effect-schema.ts';
 export * from './values/gltf-extensions.ts';
 export * from './values/guards.ts';
 export * from './values/hands.ts';
+export * from './values/hotkey-targets.ts';
 export * from './values/hotkeys.ts';
 export * from './values/item-transition.ts';
 export * from './values/labels.ts';

package/dist/index.js

@@ -12,6 +12,7 @@ export * from "./values/effect-schema.js";
 export * from "./values/gltf-extensions.js";
 export * from "./values/guards.js";
 export * from "./values/hands.js";
+export * from "./values/hotkey-targets.js";
 export * from "./values/hotkeys.js";
 export * from "./values/item-transition.js";
 export * from "./values/labels.js";

package/dist/values/hotkey-targets.d.ts

@@ -0,0 +1,56 @@
+import type { Hotkey, MotionGroup } from '../wire/types.ts';
+/** A hotkey action Persona can run. */
+type HotkeyAction = NonNullable<Hotkey['action']>;
+/** What a model offers hotkeys: its expressions (a null `file` on formats with none) and its motion groups. */
+export interface HotkeyListing {
+    expressions: readonly {
+        name: string;
+        file: string | null;
+    }[];
+    motions: readonly MotionGroup[];
+}
+/**
+ * The id an expression is stored and bound by: its exp3 basename on Live2D (VTS parity),
+ * its name on VRM, which declares no per-expression file. Every persisted or hotkey-bound
+ * reference to an expression goes through this, so the two can never disagree.
+ */
+export declare function expressionKey(def: {
+    name: string;
+    file: string | null;
+}): string;
+/** Saved basenames → definition Names, in saved order; unmatched entries dropped. */
+export declare function matchSavedToDefinitions(saved: readonly string[], defs: readonly {
+    Name: string;
+    File: string;
+}[]): string[];
+/** Expression Name for a stored expression key, or null when the model no longer declares it. */
+export declare function resolveExpressionName(listing: HotkeyListing, file: string): string | null;
+/** Motion group and index for a stored motion3 basename, or null when it's gone. */
+export declare function resolveMotion(listing: {
+    motions: readonly MotionGroup[];
+}, file: string): {
+    group: string;
+    index: number;
+} | null;
+/** `file` is a basename throughout — the form hotkeys are stored in. */
+export interface HotkeyTarget {
+    file: string;
+    label: string;
+}
+/**
+ * The files an action's hotkey can point at, with display labels. Deduped by basename,
+ * first occurrence wins — the same rule the resolvers above apply, so the picker always
+ * lists exactly what a hotkey would run.
+ * @param groupLabel Display name for a motion group; VRM groups are clip refs, not names.
+ */
+export declare function hotkeyTargets(listing: HotkeyListing, action: HotkeyAction, groupLabel?: (group: string) => string): HotkeyTarget[];
+/**
+ * Whether a model-load hotkey's stored `File` names this model: its `.vtube.json` name (what VTS
+ * stores) or its entry file, case-insensitively — VTS's own file-name resolution. A `ModelRef`
+ * from an older host lists neither, and matches nothing.
+ */
+export declare function modelMatchesFile(file: string, model: {
+    vtubeFile?: string | null;
+    entryFile?: string;
+}): boolean;
+export {};

package/dist/values/hotkey-targets.js

@@ -0,0 +1,88 @@
+import { fileBasename, motionLabel, motionSlots } from "./labels.js";
+/**
+ * The id an expression is stored and bound by: its exp3 basename on Live2D (VTS parity),
+ * its name on VRM, which declares no per-expression file. Every persisted or hotkey-bound
+ * reference to an expression goes through this, so the two can never disagree.
+ */
+export function expressionKey(def) {
+    return def.file === null ? def.name : fileBasename(def.file);
+}
+/** Saved basenames → definition Names, in saved order; unmatched entries dropped. */
+export function matchSavedToDefinitions(saved, defs) {
+    const byBase = new Map();
+    for (const d of defs) {
+        const base = fileBasename(d.File);
+        if (!byBase.has(base))
+            byBase.set(base, d.Name);
+    }
+    return saved.flatMap(s => {
+        const name = byBase.get(fileBasename(s));
+        return name === undefined ? [] : [name];
+    });
+}
+// A hotkey stores the same id expression persistence does, so a VRM entry binds by name.
+// A keyless entry (a model3 declaring an empty File) is dropped — nothing could bind it.
+function expressionDefs(listing) {
+    return listing.expressions.flatMap(d => {
+        const key = expressionKey(d);
+        return key === '' ? [] : [{ Name: d.name, File: key }];
+    });
+}
+/** Expression Name for a stored expression key, or null when the model no longer declares it. */
+export function resolveExpressionName(listing, file) {
+    return matchSavedToDefinitions([file], expressionDefs(listing))[0] ?? null;
+}
+/** Motion group and index for a stored motion3 basename, or null when it's gone. */
+export function resolveMotion(listing, file) {
+    const base = fileBasename(file);
+    for (const { group, files } of listing.motions) {
+        const slot = motionSlots(files).find(s => fileBasename(s.file) === base);
+        if (slot)
+            return { group, index: slot.index };
+    }
+    return null;
+}
+/**
+ * The files an action's hotkey can point at, with display labels. Deduped by basename,
+ * first occurrence wins — the same rule the resolvers above apply, so the picker always
+ * lists exactly what a hotkey would run.
+ * @param groupLabel Display name for a motion group; VRM groups are clip refs, not names.
+ */
+export function hotkeyTargets(listing, action, groupLabel = g => g) {
+    const seen = new Set();
+    if (action === 'expression-toggle') {
+        return expressionDefs(listing).flatMap(d => {
+            const file = fileBasename(d.File);
+            if (seen.has(file))
+                return [];
+            seen.add(file);
+            return [{ file, label: d.Name }];
+        });
+    }
+    if (action === 'motion-play') {
+        return listing.motions.flatMap(g => motionSlots(g.files).flatMap(({ file: f }) => {
+            const file = fileBasename(f);
+            if (seen.has(file))
+                return [];
+            seen.add(file);
+            // A VRM group is a single clip named for its own file, so the ` · file` half
+            // would just repeat the group.
+            const label = g.group === f ? groupLabel(g.group) : `${groupLabel(g.group)} · ${motionLabel(f)}`;
+            return [{ file, label }];
+        }));
+    }
+    return [];
+}
+/**
+ * Whether a model-load hotkey's stored `File` names this model: its `.vtube.json` name (what VTS
+ * stores) or its entry file, case-insensitively — VTS's own file-name resolution. A `ModelRef`
+ * from an older host lists neither, and matches nothing.
+ */
+export function modelMatchesFile(file, model) {
+    const base = fileBasename(file).toLowerCase();
+    if (base === '')
+        return false;
+    if (model.vtubeFile?.toLowerCase() === base)
+        return true;
+    return model.entryFile !== undefined && fileBasename(model.entryFile).toLowerCase() === base;
+}

package/dist/values/labels.d.ts

@@ -1,4 +1,4 @@
-import type { AutomationBoundaryKind, AutomationInfo } from '../wire/types.ts';
+import type { AutomationInfo, AutomationSetupKind } from '../wire/types.ts';
 /** Last path segment, tolerating both `/` and `\` separators. */
 export declare function fileBasename(path: string): string;
 /**
@@ -20,7 +20,9 @@ export declare function motionSlots(files: readonly string[]): {
 /** English label for one automation action kind; kinds newer than this SDK read `Action`. */
 export declare function automationActionLabel(kind: string): string;
 /** True for an action that prepares the scene before playback. */
-export declare function isAutomationBoundary(kind: string | undefined): kind is AutomationBoundaryKind;
+export declare function isAutomationSetup(kind: string | undefined): kind is AutomationSetupKind;
+/** @deprecated Use `isAutomationSetup`. */
+export declare const isAutomationBoundary: typeof isAutomationSetup;
 /** Join action labels without implying timing that the client summary does not carry. */
 export declare function joinAutomationActionLabels(labels: readonly string[], kinds: readonly string[]): string;
 /** Display label for an app automation: its title, else its joined action-kind labels. */

package/dist/values/labels.js

@@ -1,4 +1,4 @@
-import { AUTOMATION_BOUNDARY_KINDS } from "../wire/types.js";
+import { AUTOMATION_SETUP_KINDS } from "../wire/types.js";
 import { isOneOf } from "./guards.js";
 /** Last path segment, tolerating both `/` and `\` separators. */
 export function fileBasename(path) {
@@ -28,21 +28,27 @@ export function motionSlots(files) {
 // English fallbacks; localizing clients keep their own map and use these for unknown kinds.
 const AUTOMATION_ACTION_KIND_LABELS = {
     'effect-toggle': 'Toggle Effect',
-    'effect-params': 'Effect Settings',
-    'effect-clip': 'Effect Clip',
+    'effect-params': 'Apply Effect Settings',
+    'effect-clip': 'Temporary Effect',
     'camera-pose': 'Camera Position',
-    'reset-camera': 'Reset Camera',
+    'camera-reset': 'Reset Camera',
     'layer-visibility': 'Layer Visibility',
+    'text-set': 'Set Text',
+    'lyrics-play': 'Lyrics',
     'stream-mode': 'Stream Mode',
-    'switch-scene': 'Switch Scene',
-    'toggle-expression': 'Toggle Expression',
-    'play-motion': 'Play Motion',
-    'play-audio': 'Play Audio',
+    'scene-switch': 'Switch Scene',
+    'expression-toggle': 'Toggle Expression',
+    'motion-play': 'Play Motion',
+    'audio-play': 'Play Audio',
     'audio-control': 'Control Audio',
-    'play-camera-motion': 'Play Camera Motion',
-    'stop-camera-motion': 'Stop Camera Motion',
-    'remove-all-expressions': 'Clear All Expressions',
-    'load-model': 'Swap Model',
+    'camera-motion-play': 'Play Camera Motion',
+    'camera-motion-stop': 'Stop Camera Motion',
+    'camera-follow': 'Camera Follow',
+    'camera-aim': 'Camera Aim',
+    'camera-focus': 'Camera Focus',
+    'camera-handheld': 'Handheld Movement',
+    'expression-clear': 'Clear All Expressions',
+    'model-load': 'Swap Model',
     'model-position': 'Model Position',
 };
 /** English label for one automation action kind; kinds newer than this SDK read `Action`. */
@@ -50,9 +56,11 @@ export function automationActionLabel(kind) {
     return AUTOMATION_ACTION_KIND_LABELS[kind] ?? 'Action';
 }
 /** True for an action that prepares the scene before playback. */
-export function isAutomationBoundary(kind) {
-    return isOneOf(kind, AUTOMATION_BOUNDARY_KINDS);
+export function isAutomationSetup(kind) {
+    return isOneOf(kind, AUTOMATION_SETUP_KINDS);
 }
+/** @deprecated Use `isAutomationSetup`. */
+export const isAutomationBoundary = isAutomationSetup;
 /** Join action labels without implying timing that the client summary does not carry. */
 export function joinAutomationActionLabels(labels, kinds) {
     if (labels.length !== kinds.length)

package/dist/values/limits.d.ts

@@ -1,4 +1,4 @@
-import type { AssetRef, Attach, AttachDepth, EnvironmentLook, ModelFormat, MToonTuning, ObjectContent, ObjectSpace, SceneEnvironment, SceneLight, SceneLightCameraFollowOptions, SceneLightType, ScreenPlacement, VrmPlacement } from '../wire/types.ts';
+import type { AssetRef, Attach, AttachDepth, CameraAnchor, CameraFollowDamping, CameraTrackTarget, EnvironmentLook, ModelFormat, MToonTuning, ObjectContent, ObjectSpace, SceneCameraAim, SceneCameraAimSettings, SceneCameraFocus, SceneCameraFocusSettings, SceneCameraFollow, SceneCameraFollowSettings, SceneCameraHandheld, SceneEnvironment, SceneLight, SceneLightCameraFollowOptions, SceneLightType, ScreenPlacement, VrmPlacement } from '../wire/types.ts';
 export declare function clamp(v: number, min: number, max: number): number;
 /** Clamp to the unit interval. */
 export declare function clamp01(v: number): number;
@@ -63,6 +63,66 @@ export declare const SCENE_FOV_MAX = 90;
 /** Nonsingular authored field of view in degrees, including every valid whole-degree VMD key. */
 export declare const CAMERA_FOV_MIN = 1;
 export declare const CAMERA_FOV_MAX = 179;
+/** Ceiling for each follow and aim damping, in seconds. */
+export declare const CAMERA_DAMPING_MAX = 10;
+/** Ceiling for {@link SceneCameraAim}'s lookahead time, in seconds, and its smoothing. */
+export declare const CAMERA_AIM_LOOKAHEAD_MAX = 1;
+export declare const CAMERA_AIM_SMOOTHING_MAX = 30;
+/** Ceiling for {@link SceneCameraHandheld}'s speed. */
+export declare const CAMERA_HANDHELD_SPEED_MAX = 2;
+/** Warudo's Handheld Movement defaults, switched off. */
+export declare const DEFAULT_CAMERA_HANDHELD: SceneCameraHandheld;
+/**
+ * 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 declare const DEFAULT_CAMERA_FOLLOW_DAMPING: CameraFollowDamping;
+/** Where a fresh follow, aim or focus tracks a model; an object is always tracked by its root. */
+export declare const DEFAULT_CAMERA_ANCHOR: CameraAnchor;
+/** A fresh follow's settings: position only. */
+export declare function defaultCameraFollowSettings(): SceneCameraFollowSettings;
+/** A fresh follow of `target`, position only. */
+export declare function defaultCameraFollow(target: CameraTrackTarget): SceneCameraFollow;
+/** A fresh aim's settings, Warudo's Composer defaults: centred, no dead zone, 0.8 soft zone. */
+export declare function defaultCameraAimSettings(): SceneCameraAimSettings;
+/** A fresh aim at `target`. */
+export declare function defaultCameraAim(target: CameraTrackTarget): SceneCameraAim;
+/** A fresh focus's settings, refocusing about as fast as Warudo's default focusing speed. */
+export declare function defaultCameraFocusSettings(): SceneCameraFocusSettings;
+/** A fresh focus on `target`. */
+export declare function defaultCameraFocus(target: CameraTrackTarget): SceneCameraFocus;
+/** A follow's, aim's or focus's settings alone, without the layer it names. */
+export declare function cameraTrackSettingsOf<T extends CameraTrackTarget>(track: T): Omit<T, 'instanceId' | 'target'>;
+/** The instance `target` tracks in a scene whose primary model is `primaryInstanceId`. */
+export declare function cameraTrackInstanceId(target: CameraTrackTarget, primaryInstanceId: string | null): string | null;
+/** 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 declare function cameraTrackKind(item: {
+    kind: 'model';
+    ref: {
+        kind: string;
+    };
+} | {
+    kind: 'object';
+    space: ObjectSpace;
+}): 'model' | '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 declare function cameraTrackCandidates(items: readonly ({
+    kind: 'model';
+    instanceId: string;
+    ref: {
+        kind: string;
+        name: string;
+    };
+} | {
+    kind: 'object';
+    instanceId: string;
+    name: string;
+    space: ObjectSpace;
+})[]): {
+    instanceId: string;
+    name: string;
+    model: boolean;
+}[];
 /** Manual navigation stops short of ±90°; authored camera elevations remain unrestricted. */
 export declare const ELEVATION_LIMIT: number;
 /** Manual navigation distance bounds; authored cameras retain signed, unrestricted distances. */
@@ -172,9 +232,32 @@ export declare const WEB_SIZE_MAX = 7680;
 /** Web object paint-rate bounds, frames per second. */
 export declare const WEB_FPS_MIN = 1;
 export declare const WEB_FPS_MAX = 60;
+/** Text object bounds: characters, em size in px, and the box and paint extents in px. */
+export declare const TEXT_LENGTH_MAX = 10000;
+export declare const TEXT_SIZE_MIN = 4;
+export declare const TEXT_SIZE_MAX = 1000;
+export declare const TEXT_SHEAR_MAX = 1;
+/** Letter and word spacing, em. */
+export declare const TEXT_SPACING_MIN = -0.5;
+export declare const TEXT_SPACING_MAX = 2;
+export declare const TEXT_LINE_HEIGHT_MIN = 0.5;
+export declare const TEXT_LINE_HEIGHT_MAX = 4;
+export declare const TEXT_BOX_MAX = 7680;
+export declare const TEXT_STROKE_MAX = 100;
+export declare const TEXT_SHADOW_OFFSET_MAX = 200;
+export declare const TEXT_SHADOW_BLUR_MAX = 100;
+export declare const TEXT_PLATE_PADDING_MAX = 500;
+export declare const TEXT_PLATE_RADIUS_MAX = 500;
+/** 3D text: extrusion and bevel in em, bevel segments, and emission strength. */
+export declare const TEXT_EXTRUDE_MAX = 2;
+export declare const TEXT_BEVEL_MAX = 0.2;
+export declare const TEXT_BEVEL_RESOLUTION_MAX = 8;
+export declare const TEXT_EMISSION_MAX = 4;
+/** A PostScript name: printable ASCII, at most 63 chars, minus the quote and backslash that would escape `local("…")`. */
+export declare const TEXT_POSTSCRIPT_NAME_RE: RegExp;
 /** A prop is a mesh, so it only exists in the three.js scene; every other kind renders in both. */
 export declare function objectSupportsSpace(kind: ObjectContent['kind'], space: ObjectSpace): boolean;
-/** 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 declare function contentAssetId(content: ObjectContent): string | null;
 /**
  * The one model format a space's objects can ride: the screen layer always composites
@@ -233,9 +316,12 @@ export declare function pinEntersStack(item: {
 export declare function depthStops(meshes: readonly string[]): AttachDepth[];
 /** Which stop a depth sits at; an ArtMesh the host no longer has reads as the frontmost. */
 export declare function depthStopIndex(meshes: readonly string[], depth: AttachDepth): number;
-/** A fresh pin onto `parentInstanceId`: root anchor, in front of the model, no response tuning. */
-export declare function defaultAttach(parentInstanceId: string): Attach;
 export declare const DEFAULT_HEAD_ANGLE: NonNullable<Attach['headAngle']>;
+/**
+ * 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 declare function defaultAttach(parentInstanceId: string, screenSpace?: boolean): Attach;
 export declare const ATTACH_MULTIPLIER_MIN = -2;
 export declare const ATTACH_MULTIPLIER_MAX = 2;
 /** Parallax slider ceiling, symmetric: stage px at a full head turn. */

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,34 @@ 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;
+/** 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 +462,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

@@ -234,6 +234,7 @@ export declare const requestSchemas: {
             lut: "lut";
             animation: "animation";
             cameraMotion: "cameraMotion";
+            lyrics: "lyrics";
         }>>;
     }, z.core.$strip>;
     'settings.patch': z.ZodObject<{
@@ -329,9 +330,9 @@ export declare const requestSchemas: {
         ttlMs: z.ZodOptional<z.ZodNumber>;
         transition: z.ZodOptional<z.ZodObject<{
             style: z.ZodOptional<z.ZodEnum<{
+                pop: "pop";
                 glitch: "glitch";
                 dither: "dither";
-                pop: "pop";
                 cut: "cut";
             }>>;
             inMs: z.ZodOptional<z.ZodNumber>;

package/dist/wire/types.d.ts

@@ -17,7 +17,7 @@ export type ContentOrigin = 'bundled' | 'user';
  * 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", "audio", "prop", "ibl", "lut", "animation", "cameraMotion"];
+export declare const ASSET_KINDS: readonly ["image", "video", "audio", "prop", "ibl", "lut", "animation", "cameraMotion", "lyrics"];
 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;
@@ -48,6 +48,13 @@ export interface ContentRef {
 /** A model as the registry lists it. */
 export interface ModelRef extends ContentRef {
     kind: ModelFormat;
+    /** Entry file basename (`.model3.json`, `.vrm`), with no directory. Absent on older hosts. */
+    entryFile?: string;
+    /**
+     * `.vtube.json` basename, the name a VTS model-load hotkey stores (see `modelMatchesFile`); null
+     * without one. Only `model.list` fills it: absent on scene item refs, `model.register`'s answer, and older hosts.
+     */
+    vtubeFile?: string | null;
 }
 /** A registered object-source file. `exists` is false once the file is gone from disk. */
 export interface AssetRef extends ContentRef {
@@ -209,6 +216,29 @@ export interface SceneModelItem {
 export declare const OBJECT_SPACES: readonly ["2d", "3d"];
 export type ObjectSpace = (typeof OBJECT_SPACES)[number];
 export type CaptureKind = 'display' | 'window';
+export declare const TEXT_ALIGNS: readonly ["left", "center", "right", "justify"];
+export type TextAlign = (typeof TEXT_ALIGNS)[number];
+/** `baseline` is the first line's baseline — Blender's Top Base-Line. */
+export declare const TEXT_VERTICAL_ALIGNS: readonly ["top", "middle", "baseline", "bottom"];
+export type TextVerticalAlign = (typeof TEXT_VERTICAL_ALIGNS)[number];
+/** Blender's text-box overflow: spill past the box, shrink to fit it, or drop the lines that don't fit. */
+export declare const TEXT_OVERFLOWS: readonly ["overflow", "scale", "truncate"];
+export type TextOverflow = (typeof TEXT_OVERFLOWS)[number];
+export declare const TEXT_STROKE_JOINS: readonly ["round", "miter", "bevel"];
+export type TextStrokeJoin = (typeof TEXT_STROKE_JOINS)[number];
+/**
+ * A system font face, named exactly: its PostScript name is the identity, since a family's
+ * nearest weight is not the face the user picked. The rest lets a machine without that face
+ * fall back to the closest one in the same family.
+ */
+export interface TextFont {
+    postscriptName: string;
+    family: string;
+    weight: number;
+    italic: boolean;
+    /** CSS `font-stretch` percent; 100 is normal. */
+    stretch: number;
+}
 /** What an object renders. Mirrors VTube Studio's items and Warudo's screen/prop assets. */
 export type ObjectContent = {
     kind: 'image';
@@ -219,6 +249,8 @@ export type ObjectContent = {
     loop: boolean;
     muted: boolean;
     volume: number;
+    /** Held rather than played while shown, through a restart too; the playback position is not saved. */
+    paused: boolean;
 } | {
     kind: 'prop';
     assetId: string;
@@ -242,11 +274,95 @@ export type ObjectContent = {
     source: CaptureKind;
     sourceId: string;
     label: string;
+} | {
+    kind: 'text';
+    text: string;
+    /** null draws in the platform's default sans-serif. */
+    font: TextFont | null;
+    /** Em size, px; 3D reads px at the image quads' 1000 px per metre. */
+    size: number;
+    color: string;
+    /** Blender's shear: the slant as a fraction of height, -1..1. */
+    shear: number;
+    /** Em fractions added between characters and to each space. */
+    letterSpacing: number;
+    wordSpacing: number;
+    /** Line box as a multiple of `size`. */
+    lineHeight: number;
+    align: TextAlign;
+    verticalAlign: TextVerticalAlign;
+    /** Text box, px; 0 sizes that side to the text, and a set width wraps. */
+    boxWidth: number;
+    boxHeight: number;
+    overflow: TextOverflow;
+    /** Outside the glyphs, px; width 0 draws none. */
+    stroke: {
+        width: number;
+        color: string;
+        join: TextStrokeJoin;
+    };
+    /** px; opacity 0 draws none. */
+    shadow: {
+        color: string;
+        opacity: number;
+        offsetX: number;
+        offsetY: number;
+        blur: number;
+    };
+    /** A backing box around the text, px; opacity 0 draws none. */
+    plate: {
+        color: string;
+        opacity: number;
+        padding: number;
+        radius: number;
+    };
+    /** Karaoke: a lyrics clip paints what is sung in `color`, outlined in `strokeColor` (2D only). */
+    sung: {
+        color: string;
+        strokeColor: string;
+    };
+    /** 3D: extrusion depth and bevel as fractions of `size`; bevel segments. */
+    extrude: number;
+    bevel: number;
+    bevelResolution: number;
+    /** 3D surface: PBR roughness and metalness 0..1, and how strongly the text glows in its own colour. */
+    roughness: number;
+    metalness: number;
+    emission: number;
+    /** 3D: turn the text to face the camera every frame, ignoring the placement's rotation. */
+    faceCamera: boolean;
 };
+/** The video variant of {@link ObjectContent}. */
+export type VideoContent = Extract<ObjectContent, {
+    kind: 'video';
+}>;
 /** The webpage variant of {@link ObjectContent}. */
 export type WebContent = Extract<ObjectContent, {
     kind: 'web';
 }>;
+/** The text variant of {@link ObjectContent}. */
+export type TextContent = Extract<ObjectContent, {
+    kind: 'text';
+}>;
+/** One face of a {@link FontFamilyInfo}. */
+export interface FontFaceInfo {
+    postscriptName: string;
+    /** The subfamily as the font names it: `Semibold`, `W6`, `Bold Italic`. */
+    style: string;
+    weight: number;
+    italic: boolean;
+    /** CSS `font-stretch` percent. */
+    stretch: number;
+    /** A variable font's named instance. */
+    variable: boolean;
+}
+/** An installed font family and its faces. File paths never cross the wire. */
+export interface FontFamilyInfo {
+    family: string;
+    /** Every name the family goes by, localized ones included, canonical first. */
+    names: string[];
+    faces: FontFaceInfo[];
+}
 /** Where on a parent model an object rides. `root` is the model's own transform. */
 export type AttachAnchor = {
     kind: 'root';
@@ -365,6 +481,108 @@ export interface OrbitTransform {
     targetY: number;
     targetZ: number;
 }
+/**
+ * How a following camera turns with its anchor — Warudo's Transposer binding modes. `world` follows
+ * position only; `yaw`, `yaw-pitch` and `full` also turn with it (Lock To Target With World Up, No Roll,
+ * and Lock To Target); `lazy` trails it, turning only as it passes (Simple Follow With World Up).
+ */
+export declare const CAMERA_FOLLOW_BINDINGS: readonly ["world", "yaw", "yaw-pitch", "full", "lazy"];
+export type CameraFollowBinding = (typeof CAMERA_FOLLOW_BINDINGS)[number];
+/** Seconds a following camera takes to settle, 0 locking it: position along the view's own axes, then each turn. */
+export interface CameraFollowDamping {
+    x: number;
+    y: number;
+    z: number;
+    yaw: number;
+    pitch: number;
+    roll: number;
+}
+/** The point a camera follows or aims at on a model: a humanoid bone, or its root. An object is tracked by its own origin. */
+export type CameraAnchor = Extract<AttachAnchor, {
+    kind: 'root' | 'bone';
+}>;
+/**
+ * The layer a scene camera follows, aims at or focuses on: a VRM model or 3D object by id, or whichever model
+ * is primary as the scene changes. An id naming anything else heals to no tracking; a primary model that
+ * cannot be tracked holds the view.
+ */
+export type CameraTrackTarget = {
+    target: 'primary';
+    instanceId?: never;
+} | {
+    target?: never;
+    instanceId: string;
+};
+/** How a following camera tracks its layer, whichever layer that is. */
+export interface SceneCameraFollowSettings {
+    /** Always the root on an object. */
+    anchor: CameraAnchor;
+    binding: CameraFollowBinding;
+    damping: CameraFollowDamping;
+}
+/**
+ * A scene camera following a layer. While set, `orbit` frames the layer as if its anchor rested at the stage
+ * origin, and the view moves with the anchor — placement, motion and tracking alike — without writing
+ * `orbit` back.
+ */
+export type SceneCameraFollow = CameraTrackTarget & SceneCameraFollowSettings;
+/**
+ * A scene camera turning to keep a layer at a spot on screen — Warudo's Composer. Screen values are
+ * fractions of the view: x from the left, y from the top.
+ */
+export interface SceneCameraAimSettings {
+    /** Always the root on an object. */
+    anchor: CameraAnchor;
+    /** Where the anchor sits on screen, 0–1; 0.5 centres it. */
+    screenX: number;
+    screenY: number;
+    /** The camera holds still while the anchor stays inside this zone around its spot. */
+    deadZone: {
+        width: number;
+        height: number;
+    };
+    /** Past the dead zone the camera turns gradually; past this zone, at once. Never narrower than the dead zone. */
+    softZone: {
+        width: number;
+        height: number;
+    };
+    /** Shifts the soft zone off the spot, −0.5–0.5 of the slack between the zones. */
+    bias: {
+        x: number;
+        y: number;
+    };
+    /** Seconds to turn the anchor back into the dead zone, 0 turning at once. */
+    damping: {
+        horizontal: number;
+        vertical: number;
+    };
+    /**
+     * Aims `time` seconds (0–1, 0 off) ahead of a moving anchor, its velocity smoothed over `smoothing` (0–30);
+     * `ignoreY` leaves vertical motion out.
+     */
+    lookahead: {
+        time: number;
+        smoothing: number;
+        ignoreY: boolean;
+    };
+}
+export type SceneCameraAim = CameraTrackTarget & SceneCameraAimSettings;
+/** A scene camera keeping a layer sharp under Depth of Field — Warudo's Focus Character. */
+export interface SceneCameraFocusSettings {
+    /** Always the root on an object. */
+    anchor: CameraAnchor;
+    /** Seconds for the focus plane to catch up with the anchor, 0 at once. */
+    damping: number;
+}
+export type SceneCameraFocus = CameraTrackTarget & SceneCameraFocusSettings;
+/** Noise-driven sway over the scene camera's own framing — Warudo's Handheld Movement. */
+export interface SceneCameraHandheld {
+    enabled: boolean;
+    /** 0–1; the default 0.5 is a mild handheld. */
+    intensity: number;
+    /** 0–2; 1 sways at the authored pace. */
+    speed: number;
+}
 /** Scene-level VRM camera. `orbit: null` = never framed — the first VRM load frames it from model height. */
 export interface SceneCamera {
     orbit: OrbitTransform | null;
@@ -379,6 +597,14 @@ export interface SceneCamera {
      * is set it overrides the framing every frame without writing it back.
      */
     clipAssetId: string | null;
+    /** The layer the view follows, or null. A camera motion overrides it. Absent on older hosts; gate on `camera-follow`. */
+    follow?: SceneCameraFollow | null;
+    /** The layer the view turns to keep on screen, or null. A camera motion overrides it. Absent on older hosts; gate on `camera-aim`. */
+    aim?: SceneCameraAim | null;
+    /** The layer Depth of Field keeps sharp, or null for the look-at point. Absent on older hosts; gate on `camera-focus`. */
+    focus?: SceneCameraFocus | null;
+    /** Handheld sway; a camera motion overrides it. Absent on older hosts; gate on `camera-handheld`. */
+    handheld?: SceneCameraHandheld;
 }
 /**
  * The slice of {@link SceneCamera} a saved pose snapshots and applies — a framing, never
@@ -1061,7 +1287,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", "stage-capture", "model-movement", "object-pin-depth"];
+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", "model-movement", "object-pin-depth", "text-objects", "camera-follow", "camera-aim", "camera-focus", "camera-handheld", "video-sound"];
 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`. */
@@ -1130,7 +1356,7 @@ export interface Hotkey {
     name: string;
     /** The VTS `Action` string verbatim; `action` is null when Persona cannot run it. */
     vtsAction: string;
-    action: 'toggle-expression' | 'play-motion' | 'remove-all-expressions' | 'load-model' | null;
+    action: 'expression-toggle' | 'motion-play' | 'expression-clear' | 'model-load' | null;
     file: string;
     accelerator: string | null;
     global: boolean;
@@ -1153,11 +1379,22 @@ export interface HotkeyState extends HotkeyConfig {
     registered: string[];
 }
 /** Action kinds an app automation can carry today; servers may send kinds newer than this list. */
-export declare const AUTOMATION_ACTION_KINDS: readonly ["effect-toggle", "effect-params", "effect-clip", "camera-pose", "reset-camera", "play-camera-motion", "stop-camera-motion", "layer-visibility", "stream-mode", "switch-scene", "toggle-expression", "play-motion", "play-audio", "audio-control", "remove-all-expressions", "load-model", "model-position"];
+export declare const AUTOMATION_ACTION_KINDS: readonly ["effect-toggle", "effect-params", "effect-clip", "camera-pose", "camera-reset", "camera-motion-play", "camera-motion-stop", "camera-follow", "camera-aim", "camera-focus", "camera-handheld", "layer-visibility", "text-set", "lyrics-play", "stream-mode", "scene-switch", "expression-toggle", "motion-play", "audio-play", "audio-control", "expression-clear", "model-load", "model-position"];
 export type AutomationActionKind = (typeof AUTOMATION_ACTION_KINDS)[number];
+/**
+ * Deprecated action kind names, each mapped to its category-first replacement. Older hosts send them in
+ * `actionKinds` and `Hotkey.action`, and older files store them; the client renames them on receipt.
+ */
+export declare const LEGACY_AUTOMATION_ACTION_KINDS: ReadonlyMap<string, AutomationActionKind>;
+/** The current name of an action kind; kinds that were never renamed, known or not, pass through. */
+export declare function canonicalActionKind(kind: string): string;
 /** Setup kinds that finish loading before the sequence clock starts. */
-export declare const AUTOMATION_BOUNDARY_KINDS: readonly ["switch-scene", "load-model"];
-export type AutomationBoundaryKind = (typeof AUTOMATION_BOUNDARY_KINDS)[number];
+export declare const AUTOMATION_SETUP_KINDS: readonly ["scene-switch", "model-load"];
+export type AutomationSetupKind = (typeof AUTOMATION_SETUP_KINDS)[number];
+/** @deprecated Use `AUTOMATION_SETUP_KINDS`. */
+export declare const AUTOMATION_BOUNDARY_KINDS: readonly ["scene-switch", "model-load"];
+/** @deprecated Use `AutomationSetupKind`. */
+export type AutomationBoundaryKind = AutomationSetupKind;
 /**
  * One app automation as clients see it. Action kinds and scene targets drive derived
  * labels; other action payloads stay app-side.

package/dist/wire/types.js

@@ -13,13 +13,35 @@ import { TIME_INPUT_NAMES, TIME_INPUT_RANGES } from "../values/time.js";
  * 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', 'audio', 'prop', 'ibl', 'lut', 'animation', 'cameraMotion'];
+export const ASSET_KINDS = [
+    'image',
+    'video',
+    'audio',
+    'prop',
+    'ibl',
+    'lut',
+    'animation',
+    'cameraMotion',
+    'lyrics',
+];
 /** Narrow a kind string to the set the asset registry owns — models and effects have their own. */
 export function isAssetKind(v) {
     return isOneOf(v, ASSET_KINDS);
 }
 // ---- Objects -------------------------------------------------------------------
 export const OBJECT_SPACES = ['2d', '3d'];
+export const TEXT_ALIGNS = ['left', 'center', 'right', 'justify'];
+/** `baseline` is the first line's baseline — Blender's Top Base-Line. */
+export const TEXT_VERTICAL_ALIGNS = ['top', 'middle', 'baseline', 'bottom'];
+/** Blender's text-box overflow: spill past the box, shrink to fit it, or drop the lines that don't fit. */
+export const TEXT_OVERFLOWS = ['overflow', 'scale', 'truncate'];
+export const TEXT_STROKE_JOINS = ['round', 'miter', 'bevel'];
+/**
+ * How a following camera turns with its anchor — Warudo's Transposer binding modes. `world` follows
+ * position only; `yaw`, `yaw-pitch` and `full` also turn with it (Lock To Target With World Up, No Roll,
+ * and Lock To Target); `lazy` trails it, turning only as it passes (Simple Follow With World Up).
+ */
+export const CAMERA_FOLLOW_BINDINGS = ['world', 'yaw', 'yaw-pitch', 'full', 'lazy'];
 export const SCENE_LIGHT_TYPES = ['directional', 'point', 'ambient', 'area', 'spot'];
 /**
  * Per-light shadow tier. `off` is the old `castShadow: false`; the rest raise
@@ -61,6 +83,18 @@ export const APP_CAPABILITIES = [
      * one pinned to a Live2D model takes `attach.depth` in that model's stack, as a Live2D item does.
      */
     'object-pin-depth',
+    /** `text` object content and `fonts.list`. */
+    'text-objects',
+    /** `SceneCamera.follow`. */
+    'camera-follow',
+    /** `SceneCamera.aim`. */
+    'camera-aim',
+    /** `SceneCamera.focus`. */
+    'camera-focus',
+    /** `SceneCamera.handheld`. */
+    'camera-handheld',
+    /** `object.setContent` edits a video's `loop`, `muted` and `volume` in place; its sound follows the output device. */
+    'video-sound',
 ];
 export function isAppCapability(v) {
     return isOneOf(v, APP_CAPABILITIES);
@@ -72,25 +106,51 @@ export const AUTOMATION_ACTION_KINDS = [
     'effect-params',
     'effect-clip',
     'camera-pose',
-    'reset-camera',
-    'play-camera-motion',
-    'stop-camera-motion',
+    'camera-reset',
+    'camera-motion-play',
+    'camera-motion-stop',
+    'camera-follow',
+    'camera-aim',
+    'camera-focus',
+    'camera-handheld',
     'layer-visibility',
+    'text-set',
+    'lyrics-play',
     'stream-mode',
-    'switch-scene',
-    'toggle-expression',
-    'play-motion',
-    'play-audio',
+    'scene-switch',
+    'expression-toggle',
+    'motion-play',
+    'audio-play',
     'audio-control',
-    'remove-all-expressions',
-    'load-model',
+    'expression-clear',
+    'model-load',
     'model-position',
 ];
+/**
+ * Deprecated action kind names, each mapped to its category-first replacement. Older hosts send them in
+ * `actionKinds` and `Hotkey.action`, and older files store them; the client renames them on receipt.
+ */
+export const LEGACY_AUTOMATION_ACTION_KINDS = new Map([
+    ['reset-camera', 'camera-reset'],
+    ['play-camera-motion', 'camera-motion-play'],
+    ['stop-camera-motion', 'camera-motion-stop'],
+    ['set-text', 'text-set'],
+    ['lyrics', 'lyrics-play'],
+    ['switch-scene', 'scene-switch'],
+    ['toggle-expression', 'expression-toggle'],
+    ['play-motion', 'motion-play'],
+    ['play-audio', 'audio-play'],
+    ['remove-all-expressions', 'expression-clear'],
+    ['load-model', 'model-load'],
+]);
+/** The current name of an action kind; kinds that were never renamed, known or not, pass through. */
+export function canonicalActionKind(kind) {
+    return LEGACY_AUTOMATION_ACTION_KINDS.get(kind) ?? kind;
+}
 /** Setup kinds that finish loading before the sequence clock starts. */
-export const AUTOMATION_BOUNDARY_KINDS = [
-    'switch-scene',
-    'load-model',
-];
+export const AUTOMATION_SETUP_KINDS = ['scene-switch', 'model-load'];
+/** @deprecated Use `AUTOMATION_SETUP_KINDS`. */
+export const AUTOMATION_BOUNDARY_KINDS = AUTOMATION_SETUP_KINDS;
 // ---- Settings ------------------------------------------------------------------
 export const TRACKING_SOURCE_IDS = ['persona-ios', 'ifacialmocap', 'vts-ios'];
 /** 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": "1.21.0",
+  "version": "1.22.0",
   "description": "TypeScript SDK and wire schema for the LAPLACE Persona plugin API",
   "license": "MIT",
   "type": "module",
@@ -28,7 +28,7 @@
   "devDependencies": {
     "rimraf": "^6.1.3",
     "typescript": "~6.0.3",
-    "vitest": "^5.0.1"
+    "vitest": "^5.0.2"
   },
   "engines": {
     "node": ">=24"