@laplace.live/persona-sdk 1.24.0 → 1.25.0

package/dist/values/hotkeys.d.ts

@@ -1,4 +1,4 @@
-import type { Hotkey } from '../wire/types.ts';
+import type { Hotkey, HotkeyState } from '../wire/types.ts';
 /** True when the combo carries a command modifier and so may be registered globally. */
 export declare function hasCommandModifier(accelerator: string | null): boolean;
 /**
@@ -9,6 +9,12 @@ export declare function hasCommandModifier(accelerator: string | null): boolean;
 export declare function canRunInBackground(accelerator: string | null): boolean;
 /** True when a model hotkey is meant to fire while Persona sits in the background — what main registers on, and what the globe shows. */
 export declare function hotkeyRunsInBackground(h: Hotkey): boolean;
+/**
+ * True when main should hold an OS registration for `h` but doesn't — another app owns its
+ * command-modifier combo. A non-command combo (a controller one included) never registers, so its
+ * absence is not contention; nor is anything under the model's master switch turned off.
+ */
+export declare function hotkeyContended(state: Pick<HotkeyState, 'keyboardEnabled' | 'registered'>, h: Hotkey): boolean;
 /**
  * Why a `hold` hotkey toggles instead of holding, or null when it can hold. A combo registered with
  * the OS reaches Persona as a press alone — Electron reports no key-up for it — and one registration
@@ -16,6 +22,8 @@ export declare function hotkeyRunsInBackground(h: Hotkey): boolean;
  * `'shared'` when only another one on its combo does, which `registered` (main's list) alone can tell.
  */
 export declare function holdBlockedBy(h: Pick<Hotkey, 'hold' | 'global' | 'accelerator'>, registered: boolean): 'own' | 'shared' | null;
+/** A hotkey's playback options, which every writer and healer treats as one group. */
+export type HotkeyOptions = Pick<Hotkey, 'hold' | 'fadeSeconds' | 'deactivateAfterSeconds' | 'stopsOnLastFrame'>;
 /** VTS's editor limits for a hotkey's fade and auto-off times, in seconds; healing clamps API input to them. */
 export declare const HOTKEY_FADE_SECONDS_MAX = 2;
 export declare const HOTKEY_DEACTIVATE_SECONDS_MIN = 0.1;

package/dist/values/hotkeys.js

@@ -25,6 +25,17 @@ export function canRunInBackground(accelerator) {
 export function hotkeyRunsInBackground(h) {
     return h.global && h.active && h.action !== null && canRunInBackground(h.accelerator);
 }
+/**
+ * True when main should hold an OS registration for `h` but doesn't — another app owns its
+ * command-modifier combo. A non-command combo (a controller one included) never registers, so its
+ * absence is not contention; nor is anything under the model's master switch turned off.
+ */
+export function hotkeyContended(state, h) {
+    return (state.keyboardEnabled &&
+        hotkeyRunsInBackground(h) &&
+        hasCommandModifier(h.accelerator) &&
+        !state.registered.includes(h.id));
+}
 /**
  * Why a `hold` hotkey toggles instead of holding, or null when it can hold. A combo registered with
  * the OS reaches Persona as a press alone — Electron reports no key-up for it — and one registration

package/dist/values/labels.js

@@ -26,6 +26,7 @@ export function motionSlots(files) {
     return files.flatMap((file, index) => (file === '' ? [] : [{ file, index }]));
 }
 // English fallbacks; localizing clients keep their own map and use these for unknown kinds.
+// The panel's `KIND_SPECS` labels must read the same — a desktop test holds them together.
 const AUTOMATION_ACTION_KIND_LABELS = {
     'effect-toggle': 'Toggle Effect',
     'effect-params': 'Apply Effect Settings',

package/dist/values/limits.d.ts

@@ -1,9 +1,11 @@
-import type { AssetRef, Attach, AttachDepth, CameraAnchor, CameraFollowDamping, CameraTrackTarget, ChromaKey, EnvironmentLook, KeyableContent, ModelFormat, MToonTuning, ObjectContent, ObjectSpace, SceneCameraAim, SceneCameraAimSettings, SceneCameraFocus, SceneCameraFocusSettings, SceneCameraFollow, SceneCameraFollowSettings, SceneCameraHandheld, SceneEnvironment, SceneLight, SceneLightCameraFollowOptions, SceneLightType, ScreenPlacement, VrmPlacement } from '../wire/types.ts';
+import type { AssetRef, Attach, AttachAnchor, AttachDepth, CameraAnchor, CameraFollowDamping, CameraTrackTarget, ChromaKey, EnvironmentLook, KeyableContent, ModelFormat, MToonTuning, ObjectContent, ObjectSpace, SceneCameraAim, SceneCameraAimSettings, SceneCameraFocus, SceneCameraFocusSettings, SceneCameraFollow, SceneCameraFollowSettings, SceneCameraHandheld, SceneEnvironment, SceneLight, SceneLightCameraFollowOptions, SceneLightType, ScreenPlacement, TextFont, 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;
 /** Wrap an angle into (-π, π]. */
 export declare function wrapAngle(a: number): number;
+/** Wrap degrees into (-180°, 180°], {@link wrapAngle}'s range; whole turns keep in-range values exact. */
+export declare function wrapDegrees(v: number): number;
 export declare const DEFAULT_LIVE2D_PLACEMENT: ScreenPlacement;
 export declare const DEFAULT_VRM_PLACEMENT: VrmPlacement;
 /** Scene colors heal to 6-digit hex; both cases are spelled out because JSON Schema patterns carry no flags. */
@@ -27,6 +29,11 @@ export declare const SCENE_LIGHT_SPOT_ANGLE_MIN = 1;
 export declare const SCENE_LIGHT_SPOT_ANGLE_MAX = 89;
 export declare const DEFAULT_SPOT_ANGLE_DEG = 30;
 export declare const DEFAULT_SPOT_PENUMBRA = 0.3;
+/** Light azimuth and roll bounds in degrees, symmetric: a half turn either way. */
+export declare const SCENE_LIGHT_AZIMUTH_MAX = 180;
+export declare const SCENE_LIGHT_ROLL_MAX = 180;
+/** Light elevation bound in degrees, symmetric: straight up or straight down. */
+export declare const SCENE_LIGHT_ELEVATION_MAX = 90;
 /** Positional lights need falloff headroom; the slider and scene healing share this ceiling. */
 export declare function sceneLightIntensityMax(type: SceneLightType): number;
 /** Whether a light of `type` aims with azimuth/elevation. */
@@ -41,6 +48,7 @@ export declare const LIVE2D_SCALE_MIN = 0.1;
 export declare const LIVE2D_SCALE_MAX = 24;
 export declare const VRM_SCALE_MIN = 0.05;
 export declare const VRM_SCALE_MAX = 10;
+export declare const SCENE_LIGHT_RANGE_MIN = 0.1;
 export declare const SCENE_LIGHT_RANGE_MAX = 20;
 /** Past this the 5-tap kernel spreads thin enough that its dither reads as noise. */
 export declare const SCENE_LIGHT_SHADOW_RADIUS_MAX = 16;
@@ -48,6 +56,8 @@ export declare const SCENE_LIGHT_SHADOW_RADIUS_MAX = 16;
 export declare const SCENE_LIGHT_POINT_SHADOW_RADIUS_MAX = 32;
 export declare const SCENE_LIGHT_SHADOW_SOURCE_SIZE_MAX = 10;
 export declare const DEFAULT_LIGHT_SHADOW_SOURCE_SIZE = 0.1;
+/** A light override's key: the baked light's traversal index, in decimal digits. */
+export declare const LIGHT_OVERRIDE_KEY_RE: RegExp;
 /** Shadow softness (PCF disk radius, in shadow-map texels) ceiling for a light of `type`. */
 export declare function sceneLightShadowRadiusMax(type: SceneLightType): number;
 /**
@@ -68,6 +78,8 @@ 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;
+/** {@link SceneCameraAim}'s bias bound on each axis, symmetric: a share of the slack between its zones. */
+export declare const CAMERA_AIM_BIAS_MAX = 0.5;
 /** Ceiling for {@link SceneCameraHandheld}'s speed. */
 export declare const CAMERA_HANDHELD_SPEED_MAX = 2;
 /** Warudo's Handheld Movement defaults, switched off. */
@@ -105,6 +117,30 @@ export declare function cameraTrackKind(item: {
     kind: 'object';
     space: ObjectSpace;
 }): 'model' | 'object' | null;
+/**
+ * The layer `target` tracks in `scene` — the primary model for a primary pick, else the first model — when it
+ * is one a camera can track.
+ */
+export declare function cameraTrackItem<T extends {
+    kind: 'model';
+    instanceId: string;
+    ref: {
+        kind: string;
+    };
+} | {
+    kind: 'object';
+    instanceId: string;
+    space: ObjectSpace;
+}>(scene: {
+    items: readonly T[];
+    primaryInstanceId: string | null;
+}, target: CameraTrackTarget): T | undefined;
+/** A layer the camera's follow, aim and focus pickers offer; `model` tells a model from an object. */
+export interface CameraTrackCandidate {
+    instanceId: string;
+    name: string;
+    model: boolean;
+}
 /** 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';
@@ -118,11 +154,7 @@ export declare function cameraTrackCandidates(items: readonly ({
     instanceId: string;
     name: string;
     space: ObjectSpace;
-})[]): {
-    instanceId: string;
-    name: string;
-    model: boolean;
-}[];
+})[]): CameraTrackCandidate[];
 /** 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. */
@@ -153,6 +185,23 @@ export declare const MTOON_OUTLINE_WIDTH_MAX = 2;
 /** HDR headroom: past ×1 the point is pushing emissive parts over the bloom threshold. */
 export declare const MTOON_EMISSIVE_MAX = 4;
 export declare const MTOON_UV_ANIMATION_MAX = 4;
+/** Each {@link MToonTuning} field's `[min, max]`: offsets −1..1, `shade` 0..1, multipliers 0 to their ceiling. */
+export declare const MTOON_RANGES: {
+    readonly shade: readonly [0, 1];
+    readonly shadingShift: readonly [-1, 1];
+    readonly shadingToony: readonly [-1, 1];
+    readonly giEqualization: readonly [-1, 1];
+    readonly normalScale: readonly [0, 2];
+    readonly rim: readonly [0, 2];
+    readonly rimLift: readonly [-1, 1];
+    readonly rimFresnelPower: readonly [0, 4];
+    readonly rimLightingMix: readonly [-1, 1];
+    readonly matcap: readonly [0, 4];
+    readonly outlineWidth: readonly [0, 2];
+    readonly outlineLightingMix: readonly [-1, 1];
+    readonly emissive: readonly [0, 4];
+    readonly uvAnimation: readonly [0, 4];
+};
 export declare function defaultMToonTuning(): MToonTuning;
 export declare const DEFAULT_LIGHT_AZIMUTH_DEG = 45;
 export declare const DEFAULT_LIGHT_ELEVATION_DEG: number;
@@ -262,8 +311,26 @@ 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 text font's CSS `font-weight` bounds. */
+export declare const TEXT_FONT_WEIGHT_MIN = 1;
+export declare const TEXT_FONT_WEIGHT_MAX = 1000;
+/** A text font's CSS `font-stretch` bounds, in percent. */
+export declare const TEXT_FONT_STRETCH_MIN = 50;
+export declare const TEXT_FONT_STRETCH_MAX = 200;
+/** CSS's normal face: what a text font, or a font file, that leaves its weight, slope or width unsaid reads as. */
+export declare const DEFAULT_TEXT_FONT_FACE: Pick<TextFont, 'weight' | 'italic' | 'stretch'>;
 /** 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 {@link ObjectContent} kinds that stream from a registered asset; the rest carry their source inline. */
+declare const ASSET_CONTENT_KINDS: readonly ["image", "video", "prop"];
+/** The variants of {@link ObjectContent} that stream from a registered asset. */
+export type AssetContent = Extract<ObjectContent, {
+    kind: (typeof ASSET_CONTENT_KINDS)[number];
+}>;
+/** Whether `kind` — a content kind, or an Inventory row's — is one whose asset streams into a layer. */
+export declare function isAssetContentKind(kind: string): kind is AssetContent['kind'];
+/** Whether the content streams from a registered asset: image, video and prop; the rest carry their source inline. */
+export declare function isAssetContent(content: ObjectContent): content is AssetContent;
 /** 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;
 /**
@@ -281,6 +348,12 @@ export declare function pinRiders(items: readonly {
         parentInstanceId: string;
     } | null;
 }[], instanceId: string): Set<string>;
+/** A pin picker row; `ridesThis` flags a model that already rides the item. */
+interface PinnableParent {
+    instanceId: string;
+    name: string;
+    ridesThis: boolean;
+}
 /**
  * Rows for the pin picker: every other Live2D model, each flagged when it already rides
  * `instanceId` — picking one would put the two in a circle, so both apps offer it disabled
@@ -297,10 +370,20 @@ export declare function pinnableParents(models: readonly {
     attach?: {
         parentInstanceId: string;
     } | null;
-}[], instanceId: string): {
+}[], instanceId: string): PinnableParent[];
+/**
+ * {@link pinnableParents} for an object: every model of the one format its space can ride. Nothing
+ * rides an object, so no row is ever flagged.
+ */
+export declare function objectPinParents(models: readonly {
+    instanceId: string;
+    ref: {
+        kind: string;
+        name: string;
+    };
+}[], space: ObjectSpace): {
     instanceId: string;
     name: string;
-    ridesThis: boolean;
 }[];
 /**
  * Whether pinning puts an item inside its Live2D host's ArtMesh stack, where `attach.depth` places
@@ -323,6 +406,8 @@ 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 stored anchor — a model's root, a VRM bone or a point on a Live2D ArtMesh — as a usable one, or null. */
+export declare function healAttachAnchor(raw: unknown): AttachAnchor | null;
 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
@@ -343,6 +428,8 @@ export declare const STORAGE_KEY_MAX_LENGTH = 128;
 export declare const STORAGE_VALUE_MAX_LENGTH: number;
 /** Keys one API key may hold; a `storage.set` that would exceed it answers `invalid-state`. */
 export declare const STORAGE_KEYS_MAX = 256;
+/** `session.identify` refuses a longer name, so a client composing one trims it to this. */
+export declare const SESSION_NAME_MAX_LENGTH = 64;
 /** `speech.play` URL ceiling — sized for a ~40 s WAV as a base64 `data:audio/*` payload. */
 export declare const SPEECH_URL_MAX_LENGTH = 8000000;
 /**
@@ -364,3 +451,4 @@ export declare const TWO_COLUMN_WIDTH = 672;
 export declare const SAVED_COLORS_MAX = 12;
 /** 3D-stage resolution multipliers offered by both performance pickers. */
 export declare const RENDER_SCALE_PRESETS: readonly [1, 0.85, 0.75, 0.66, 0.5];
+export {};

package/dist/values/limits.js

@@ -1,4 +1,5 @@
 import { effectLayerKeys } from "./effect-schema.js";
+import { isFiniteNumber, isOneOf, isRecord } from "./guards.js";
 export function clamp(v, min, max) {
     return Math.min(max, Math.max(min, v));
 }
@@ -16,6 +17,10 @@ export function wrapAngle(a) {
         r += TAU;
     return r;
 }
+/** Wrap degrees into (-180°, 180°], {@link wrapAngle}'s range; whole turns keep in-range values exact. */
+export function wrapDegrees(v) {
+    return v - 360 * Math.ceil((v - 180) / 360);
+}
 export const DEFAULT_LIVE2D_PLACEMENT = { x: 0, y: 0, scale: 1, rotation: 0 };
 export const DEFAULT_VRM_PLACEMENT = { x: 0, y: 0, z: 0, rotX: 0, rotY: 0, rotZ: 0, scale: 1 };
 /** Scene colors heal to 6-digit hex; both cases are spelled out because JSON Schema patterns carry no flags. */
@@ -43,6 +48,11 @@ export const SCENE_LIGHT_SPOT_ANGLE_MIN = 1;
 export const SCENE_LIGHT_SPOT_ANGLE_MAX = 89;
 export const DEFAULT_SPOT_ANGLE_DEG = 30;
 export const DEFAULT_SPOT_PENUMBRA = 0.3;
+/** Light azimuth and roll bounds in degrees, symmetric: a half turn either way. */
+export const SCENE_LIGHT_AZIMUTH_MAX = 180;
+export const SCENE_LIGHT_ROLL_MAX = 180;
+/** Light elevation bound in degrees, symmetric: straight up or straight down. */
+export const SCENE_LIGHT_ELEVATION_MAX = 90;
 /** Positional lights need falloff headroom; the slider and scene healing share this ceiling. */
 export function sceneLightIntensityMax(type) {
     return type === 'directional' || type === 'ambient' ? SCENE_LIGHT_INTENSITY_MAX : SCENE_LIGHT_POINT_INTENSITY_MAX;
@@ -68,6 +78,7 @@ export const LIVE2D_SCALE_MIN = 0.1;
 export const LIVE2D_SCALE_MAX = 24;
 export const VRM_SCALE_MIN = 0.05;
 export const VRM_SCALE_MAX = 10;
+export const SCENE_LIGHT_RANGE_MIN = 0.1;
 // Range only *cuts off* a point light — three's 1/d² decay has extinguished it
 // by ~18 m even at max intensity, so a slider past 20 changes nothing visible.
 export const SCENE_LIGHT_RANGE_MAX = 20;
@@ -77,6 +88,8 @@ export const SCENE_LIGHT_SHADOW_RADIUS_MAX = 16;
 export const SCENE_LIGHT_POINT_SHADOW_RADIUS_MAX = 32;
 export const SCENE_LIGHT_SHADOW_SOURCE_SIZE_MAX = 10;
 export const DEFAULT_LIGHT_SHADOW_SOURCE_SIZE = 0.1;
+/** A light override's key: the baked light's traversal index, in decimal digits. */
+export const LIGHT_OVERRIDE_KEY_RE = /^\d+$/;
 /** Shadow softness (PCF disk radius, in shadow-map texels) ceiling for a light of `type`. */
 export function sceneLightShadowRadiusMax(type) {
     return type === 'point' ? SCENE_LIGHT_POINT_SHADOW_RADIUS_MAX : SCENE_LIGHT_SHADOW_RADIUS_MAX;
@@ -99,6 +112,8 @@ 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;
+/** {@link SceneCameraAim}'s bias bound on each axis, symmetric: a share of the slack between its zones. */
+export const CAMERA_AIM_BIAS_MAX = 0.5;
 /** Ceiling for {@link SceneCameraHandheld}'s speed. */
 export const CAMERA_HANDHELD_SPEED_MAX = 2;
 /** Warudo's Handheld Movement defaults, switched off. */
@@ -158,6 +173,18 @@ export function cameraTrackKind(item) {
         return item.ref.kind === 'vrm' ? 'model' : null;
     return item.space === '3d' ? 'object' : null;
 }
+/**
+ * The layer `target` tracks in `scene` — the primary model for a primary pick, else the first model — when it
+ * is one a camera can track.
+ */
+export function cameraTrackItem(scene, target) {
+    // Runs per frame for each camera track, so it searches the list rather than filtering a copy.
+    const item = target.target === 'primary'
+        ? (scene.items.find(i => i.kind === 'model' && i.instanceId === scene.primaryInstanceId) ??
+            scene.items.find(i => i.kind === 'model'))
+        : scene.items.find(i => i.instanceId === target.instanceId);
+    return item && cameraTrackKind(item) ? item : undefined;
+}
 /** 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 => {
@@ -196,6 +223,23 @@ export const MTOON_OUTLINE_WIDTH_MAX = 2;
 /** HDR headroom: past ×1 the point is pushing emissive parts over the bloom threshold. */
 export const MTOON_EMISSIVE_MAX = 4;
 export const MTOON_UV_ANIMATION_MAX = 4;
+/** Each {@link MToonTuning} field's `[min, max]`: offsets −1..1, `shade` 0..1, multipliers 0 to their ceiling. */
+export const MTOON_RANGES = {
+    shade: [0, 1],
+    shadingShift: [-1, 1],
+    shadingToony: [-1, 1],
+    giEqualization: [-1, 1],
+    normalScale: [0, MTOON_NORMAL_SCALE_MAX],
+    rim: [0, MTOON_RIM_MAX],
+    rimLift: [-1, 1],
+    rimFresnelPower: [0, MTOON_RIM_FRESNEL_POWER_MAX],
+    rimLightingMix: [-1, 1],
+    matcap: [0, MTOON_MATCAP_MAX],
+    outlineWidth: [0, MTOON_OUTLINE_WIDTH_MAX],
+    outlineLightingMix: [-1, 1],
+    emissive: [0, MTOON_EMISSIVE_MAX],
+    uvAnimation: [0, MTOON_UV_ANIMATION_MAX],
+};
 export function defaultMToonTuning() {
     return {
         shade: 1,
@@ -402,13 +446,35 @@ 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 text font's CSS `font-weight` bounds. */
+export const TEXT_FONT_WEIGHT_MIN = 1;
+export const TEXT_FONT_WEIGHT_MAX = 1000;
+/** A text font's CSS `font-stretch` bounds, in percent. */
+export const TEXT_FONT_STRETCH_MIN = 50;
+export const TEXT_FONT_STRETCH_MAX = 200;
+/** CSS's normal face: what a text font, or a font file, that leaves its weight, slope or width unsaid reads as. */
+export const DEFAULT_TEXT_FONT_FACE = {
+    weight: 400,
+    italic: false,
+    stretch: 100,
+};
 /** 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 {@link ObjectContent} kinds that stream from a registered asset; the rest carry their source inline. */
+const ASSET_CONTENT_KINDS = ['image', 'video', 'prop'];
+/** Whether `kind` — a content kind, or an Inventory row's — is one whose asset streams into a layer. */
+export function isAssetContentKind(kind) {
+    return isOneOf(kind, ASSET_CONTENT_KINDS);
+}
+/** Whether the content streams from a registered asset: image, video and prop; the rest carry their source inline. */
+export function isAssetContent(content) {
+    return isAssetContentKind(content.kind);
+}
 /** 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;
+    return isAssetContent(content) ? content.assetId : null;
 }
 /**
  * The one model format a space's objects can ride: the screen layer always composites
@@ -453,6 +519,14 @@ export function pinnableParents(models, items, instanceId) {
     }
     return out;
 }
+/**
+ * {@link pinnableParents} for an object: every model of the one format its space can ride. Nothing
+ * rides an object, so no row is ever flagged.
+ */
+export function objectPinParents(models, space) {
+    const format = attachableParentFormat(space);
+    return models.filter(m => m.ref.kind === format).map(m => ({ instanceId: m.instanceId, name: m.ref.name }));
+}
 /**
  * Whether pinning puts an item inside its Live2D host's ArtMesh stack, where `attach.depth` places
  * it: a Live2D item, or a 2D object as one quad. A 3D object only ever paints in front.
@@ -477,6 +551,38 @@ export function depthStopIndex(meshes, depth) {
     const at = meshes.indexOf(depth.id);
     return at < 0 ? meshes.length + 1 : at + 1;
 }
+/** Three non-negative finite numbers — whole ones when `int` — or null. */
+function healTriple(raw, int) {
+    if (!Array.isArray(raw) || raw.length !== 3)
+        return null;
+    const usable = (v) => isFiniteNumber(v) && v >= 0 && (!int || Number.isInteger(v));
+    const [a, b, c] = raw;
+    return usable(a) && usable(b) && usable(c) ? [a, b, c] : null;
+}
+/** A stored anchor — a model's root, a VRM bone or a point on a Live2D ArtMesh — as a usable one, or null. */
+export function healAttachAnchor(raw) {
+    if (!isRecord(raw))
+        return null;
+    if (raw.kind === 'root')
+        return { kind: 'root' };
+    if (raw.kind === 'bone')
+        return typeof raw.bone === 'string' && raw.bone !== '' ? { kind: 'bone', bone: raw.bone } : null;
+    if (raw.kind !== 'artMesh' || typeof raw.id !== 'string' || raw.id === '')
+        return null;
+    const verts = healTriple(raw.verts, true);
+    const weights = healTriple(raw.weights, false);
+    if (!verts || !weights)
+        return null;
+    const sum = weights[0] + weights[1] + weights[2];
+    // Finite weights can still sum to Infinity; dividing by it would zero the point.
+    if (!Number.isFinite(sum) || sum <= 0)
+        return null;
+    // Normalized so the point stays inside its triangle whatever was stored. A normalized triple is kept
+    // bit for bit: dividing it again can flip last bits, and hosts key anchor caches on them.
+    if (Math.abs(sum - 1) < 1e-9)
+        return { kind: 'artMesh', id: raw.id, verts, weights };
+    return { kind: 'artMesh', id: raw.id, verts, weights: [weights[0] / sum, weights[1] / sum, weights[2] / sum] };
+}
 export const DEFAULT_HEAD_ANGLE = {
     multiplier: 1,
     parallaxX: 0,
@@ -514,6 +620,8 @@ export const STORAGE_KEY_MAX_LENGTH = 128;
 export const STORAGE_VALUE_MAX_LENGTH = 64 * 1024;
 /** Keys one API key may hold; a `storage.set` that would exceed it answers `invalid-state`. */
 export const STORAGE_KEYS_MAX = 256;
+/** `session.identify` refuses a longer name, so a client composing one trims it to this. */
+export const SESSION_NAME_MAX_LENGTH = 64;
 /** `speech.play` URL ceiling — sized for a ~40 s WAV as a base64 `data:audio/*` payload. */
 export const SPEECH_URL_MAX_LENGTH = 8_000_000;
 /**

package/dist/values/lipsync.d.ts

@@ -54,19 +54,18 @@ export interface LipSyncSample {
     /** Smoothed vowel weights sum to at most one; the remainder represents non-vowel audio. */
     vowels: Record<LipSyncVowel, number>;
 }
+/** A capture or output device as a device picker lists it. */
+export interface MediaDeviceOption {
+    deviceId: string;
+    label: string;
+}
 export interface LipSyncState {
     config: LipSyncConfig;
     status: 'off' | 'starting' | 'listening' | 'error';
     error: 'permission' | 'device' | 'analysis' | null;
-    devices: {
-        deviceId: string;
-        label: string;
-    }[];
+    devices: MediaDeviceOption[];
     sample: LipSyncSample | null;
-    microphone: {
-        deviceId: string;
-        label: string;
-    } | null;
+    microphone: MediaDeviceOption | null;
     profile: Omit<LipSyncProfile, 'samples'> | null;
     calibration: LipSyncCalibrationState | null;
 }

package/dist/values/locale.d.ts

@@ -2,7 +2,8 @@ export type Locale = keyof typeof LOCALE_LABELS;
 /** `ui.language` setting: an explicit locale, or follow the OS language. */
 export type LanguageSetting = 'system' | Locale;
 /** `ui.theme` setting: an explicit appearance, or follow the OS. */
-export type ThemeSetting = 'system' | 'light' | 'dark';
+export declare const THEME_SETTINGS: readonly ["system", "light", "dark"];
+export type ThemeSetting = (typeof THEME_SETTINGS)[number];
 /** Native-language display names for the language picker (deliberately untranslated). */
 export declare const LOCALE_LABELS: {
     en: string;
@@ -12,5 +13,7 @@ export declare const LOCALE_LABELS: {
 };
 /** Locales shipped in the compiled catalogs (`pnpm i18n`). */
 export declare const LOCALES: readonly Locale[];
+/** Every `ui.language` value, `system` first. */
+export declare const LANGUAGE_SETTINGS: readonly LanguageSetting[];
 /** Best supported locale for a BCP 47-ish tag: exact match first, then fuzzy per language. */
 export declare function matchLocaleTag(tag: string): Locale;

package/dist/values/locale.js

@@ -1,4 +1,6 @@
 import { isOneOf, keysOf } from "./guards.js";
+/** `ui.theme` setting: an explicit appearance, or follow the OS. */
+export const THEME_SETTINGS = ['system', 'light', 'dark'];
 /** Native-language display names for the language picker (deliberately untranslated). */
 export const LOCALE_LABELS = {
     en: 'English',
@@ -8,6 +10,8 @@ export const LOCALE_LABELS = {
 };
 /** Locales shipped in the compiled catalogs (`pnpm i18n`). */
 export const LOCALES = keysOf(LOCALE_LABELS);
+/** Every `ui.language` value, `system` first. */
+export const LANGUAGE_SETTINGS = ['system', ...LOCALES];
 /** Best supported locale for a BCP 47-ish tag: exact match first, then fuzzy per language. */
 export function matchLocaleTag(tag) {
     if (isOneOf(tag, LOCALES))

package/dist/values/model-movement.d.ts

@@ -1,3 +1,11 @@
+import type { AttachAnchor } from '../wire/types.ts';
+/**
+ * The point `z` grows and shrinks the model around: its centre (`root`), or a point on one of its
+ * ArtMeshes, taken where that mesh sits in the model's rest pose so head motion never moves it.
+ */
+export type ModelMovementPivot = Extract<AttachAnchor, {
+    kind: 'root' | 'artMesh';
+}>;
 /**
  * VTube Studio's Movement Config: how far tracked face position slides (`x`, `y`) and scales (`z`)
  * a whole Live2D model. It moves the model itself and never writes a parameter, so it stacks with
@@ -9,21 +17,28 @@ export interface ModelMovementConfig {
     x: number;
     y: number;
     z: number;
+    /** Persona-only: VTS has no such setting, so it lives in the sidecar even beside a `.vtube.json`. */
+    pivot: ModelMovementPivot;
     /** Smoothing levels 0–100, read once when the model loads; file-only, as in VTS. */
     smoothingX: number;
     smoothingY: number;
     smoothingZ: number;
 }
-/** VTS's slider limit (`MAX_MOVEMENT`): an edited amount is a whole number within ±20. */
-export declare const MODEL_MOVEMENT_MAX = 20;
+/** The per-axis smoothing levels, read once when the model loads and never edited. */
+export type ModelMovementSmoothing = Pick<ModelMovementConfig, 'smoothingX' | 'smoothingY' | 'smoothingZ'>;
+/**
+ * The editor's limit: an edited amount is a whole number within ±50. VTS's own sliders stop at ±20
+ * (`MAX_MOVEMENT`), and releasing one there writes all three axes back clamped to that.
+ */
+export declare const MODEL_MOVEMENT_MAX = 50;
 /** VTS's `ModelPositionMovement` field initializers — a model nobody configured moves by default. */
 export declare const DEFAULT_MODEL_MOVEMENT: Readonly<ModelMovementConfig>;
 /**
  * A stored or relayed configuration, read per field over the defaults. Amounts are taken as
- * written: VTS clamps its sliders to ±20, never what a file holds.
+ * written: the editors clamp what they write, never what a file holds.
  */
 export declare function healModelMovement(raw: unknown): ModelMovementConfig;
 /** What the Movement Config editor changes; a file's smoothing levels are left as they are. */
-export type ModelMovementEdit = Partial<Pick<ModelMovementConfig, 'enabled' | 'x' | 'y' | 'z'>>;
+export type ModelMovementEdit = Partial<Pick<ModelMovementConfig, 'enabled' | 'x' | 'y' | 'z' | 'pivot'>>;
 /** An edit healed to the editor's limits; an absent or unusable field is dropped, not defaulted. */
 export declare function healModelMovementEdit(raw: unknown): ModelMovementEdit;

package/dist/values/model-movement.js

@@ -1,20 +1,29 @@
 import { finiteOr, isFiniteNumber, isRecord } from "./guards.js";
-import { clamp } from "./limits.js";
-/** VTS's slider limit (`MAX_MOVEMENT`): an edited amount is a whole number within ±20. */
-export const MODEL_MOVEMENT_MAX = 20;
+import { clamp, healAttachAnchor } from "./limits.js";
+/**
+ * The editor's limit: an edited amount is a whole number within ±50. VTS's own sliders stop at ±20
+ * (`MAX_MOVEMENT`), and releasing one there writes all three axes back clamped to that.
+ */
+export const MODEL_MOVEMENT_MAX = 50;
 /** VTS's `ModelPositionMovement` field initializers — a model nobody configured moves by default. */
 export const DEFAULT_MODEL_MOVEMENT = {
     enabled: true,
     x: 6,
     y: 8,
     z: 11,
+    pivot: { kind: 'root' },
     smoothingX: 10,
     smoothingY: 10,
     smoothingZ: 10,
 };
+/** A stored or relayed pivot as a usable one: any anchor but a bone, which no Live2D model has. */
+function healPivot(raw) {
+    const anchor = healAttachAnchor(raw);
+    return anchor?.kind === 'bone' ? null : anchor;
+}
 /**
  * A stored or relayed configuration, read per field over the defaults. Amounts are taken as
- * written: VTS clamps its sliders to ±20, never what a file holds.
+ * written: the editors clamp what they write, never what a file holds.
  */
 export function healModelMovement(raw) {
     const r = isRecord(raw) ? raw : {};
@@ -24,6 +33,7 @@ export function healModelMovement(raw) {
         x: finiteOr(r.x, d.x),
         y: finiteOr(r.y, d.y),
         z: finiteOr(r.z, d.z),
+        pivot: healPivot(r.pivot) ?? d.pivot,
         smoothingX: finiteOr(r.smoothingX, d.smoothingX),
         smoothingY: finiteOr(r.smoothingY, d.smoothingY),
         smoothingZ: finiteOr(r.smoothingZ, d.smoothingZ),
@@ -40,5 +50,8 @@ export function healModelMovementEdit(raw) {
         if (isFiniteNumber(v))
             edit[axis] = clamp(Math.round(v), -MODEL_MOVEMENT_MAX, MODEL_MOVEMENT_MAX);
     }
+    const pivot = healPivot(r.pivot);
+    if (pivot)
+        edit.pivot = pivot;
     return edit;
 }

package/dist/values/volumetric-lighting.d.ts

@@ -1,4 +1,4 @@
-import { type SceneEnvironment, type SceneVolumetricLighting } from '../wire/types.ts';
+import type { SceneEnvironment, SceneVolumetricLighting } from '../wire/types.ts';
 /** Slider and healing metadata for the haze's numeric settings. */
 export declare const SCENE_VOLUMETRIC_LIGHTING_SPECS: {
     readonly density: {

package/dist/values/volumetric-lighting.js

@@ -1,4 +1,4 @@
-import { EFFECTS_QUALITY_LEVELS } from "../wire/types.js";
+import { EFFECTS_QUALITY_LEVELS } from "./effect-schema.js";
 import { finiteOr, isOneOf, isRecord } from "./guards.js";
 import { clamp } from "./limits.js";
 /** Slider and healing metadata for the haze's numeric settings. */

package/dist/wire/envelope.js

@@ -1,7 +1,7 @@
 import { isRecord } from "../values/guards.js";
 import { isApiErrorCode } from "./errors.js";
 import { isEventName } from "./events.js";
-import { isAppCapability } from "./types.js";
+import { canonicalAppCapability, isAppCapability } from "./types.js";
 /**
  * Parse one inbound client frame. Returns the request, or an error code telling
  * the server what to answer: `parse-error` for junk bytes, `invalid-request`
@@ -47,8 +47,11 @@ export function parseServerMessage(raw) {
             const { name, version, platform } = v.app;
             if (typeof name !== 'string' || typeof version !== 'string' || typeof platform !== 'string')
                 return null;
-            // Tolerant both ways: absent on older servers, unknown names from newer ones dropped.
-            const capabilities = Array.isArray(v.app.capabilities) ? v.app.capabilities.filter(isAppCapability) : [];
+            // Tolerant both ways: absent on older servers, unknown names from newer ones dropped. Old names fold
+            // into their replacements, which a newer server also lists.
+            const names = Array.isArray(v.app.capabilities) ? v.app.capabilities : [];
+            const folded = names.map(n => (typeof n === 'string' ? canonicalAppCapability(n) : n));
+            const capabilities = [...new Set(folded.filter(isAppCapability))];
             return { kind: 'hello', protocol: v.protocol, app: { name, version, platform, capabilities } };
         }
         case 'response':