@laplace.live/persona-sdk 1.3.0 → 1.5.0

package/dist/values/labels.d.ts

@@ -1,4 +1,4 @@
-import type { ShortcutInfo } from '../wire/types.ts';
+import type { AutomationInfo } from '../wire/types.ts';
 /** Last path segment, tolerating both `/` and `\` separators. */
 export declare function fileBasename(path: string): string;
 /**
@@ -7,7 +7,12 @@ export declare function fileBasename(path: string): string;
  * so the basename is the only identifier there is.
  */
 export declare function motionLabel(file: string): string;
-/** English label for one shortcut action kind; kinds newer than this SDK read `Action`. */
-export declare function shortcutActionLabel(kind: string): string;
-/** Display label for an app shortcut: its title, else its action-kind labels joined with ` + `. */
-export declare function shortcutLabel(shortcut: Pick<ShortcutInfo, 'title' | 'actionKinds'>): string;
+/** English label for one automation action kind; kinds newer than this SDK read `Action`. */
+export declare function automationActionLabel(kind: string): string;
+/**
+ * Join one automation's action labels: a wait ends a batch, so it reads as an arrow, while
+ * actions inside a batch read as ` + `. `kinds` must match `labels` in length and position.
+ */
+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. */
+export declare function automationLabel(automation: Pick<AutomationInfo, 'title' | 'actionKinds'>): string;

package/dist/values/labels.js

@@ -12,21 +12,32 @@ export function motionLabel(file) {
     return base.replace(/\.motion3\.json$|\.exp3\.json$|\.vrma$|\.json$/i, '') || base;
 }
 // English fallbacks; localizing clients keep their own map and use these for unknown kinds.
-const SHORTCUT_ACTION_KIND_LABELS = {
+const AUTOMATION_ACTION_KIND_LABELS = {
     'effect-toggle': 'Toggle Effect',
     'effect-params': 'Effect Settings',
     'camera-pose': 'Camera Position',
     'reset-camera': 'Reset Camera',
     'layer-visibility': 'Layer Visibility',
     'stream-mode': 'Stream Mode',
+    delay: 'Wait',
 };
-/** English label for one shortcut action kind; kinds newer than this SDK read `Action`. */
-export function shortcutActionLabel(kind) {
-    return SHORTCUT_ACTION_KIND_LABELS[kind] ?? 'Action';
+/** English label for one automation action kind; kinds newer than this SDK read `Action`. */
+export function automationActionLabel(kind) {
+    return AUTOMATION_ACTION_KIND_LABELS[kind] ?? 'Action';
 }
-/** Display label for an app shortcut: its title, else its action-kind labels joined with ` + `. */
-export function shortcutLabel(shortcut) {
-    if (shortcut.title !== null && shortcut.title !== '')
-        return shortcut.title;
-    return shortcut.actionKinds.map(shortcutActionLabel).join(' + ') || 'Shortcut';
+/**
+ * Join one automation's action labels: a wait ends a batch, so it reads as an arrow, while
+ * actions inside a batch read as ` + `. `kinds` must match `labels` in length and position.
+ */
+export function joinAutomationActionLabels(labels, kinds) {
+    if (labels.length !== kinds.length)
+        throw new RangeError('automation action labels and kinds must have the same length');
+    return labels.reduce((out, label, i) => out + (i === 0 ? '' : kinds[i] === 'delay' || kinds[i - 1] === 'delay' ? ' → ' : ' + ') + label, '');
+}
+/** Display label for an app automation: its title, else its joined action-kind labels. */
+export function automationLabel(automation) {
+    if (automation.title !== null && automation.title !== '')
+        return automation.title;
+    return (joinAutomationActionLabels(automation.actionKinds.map(automationActionLabel), automation.actionKinds) ||
+        'Automation');
 }

package/dist/values/lipsync.d.ts

@@ -72,8 +72,6 @@ export declare function healLipSyncProfile(raw: unknown): LipSyncProfile | null;
 export declare function healLipSyncConfig(raw: unknown): LipSyncConfig;
 /** Whether a persisted per-model mode is supported. */
 export declare function isLipSyncMode(value: unknown): value is LipSyncMode;
-export declare const VOICE_INPUT_NAMES: readonly ["VoiceVolume", "VoiceFrequency", "VoiceVolumePlusMouthOpen", "VoiceFrequencyPlusMouthSmile", "VoiceA", "VoiceI", "VoiceU", "VoiceE", "VoiceO", "VoiceSilence", "VoiceMouthOpen", "VoiceMouthSpread"];
-export type VoiceInputName = (typeof VOICE_INPUT_NAMES)[number];
 export declare const VOICE_INPUT_RANGES: {
     readonly VoiceVolume: readonly [0, 1];
     readonly VoiceFrequency: readonly [0, 1];
@@ -88,6 +86,8 @@ export declare const VOICE_INPUT_RANGES: {
     readonly VoiceMouthOpen: readonly [0, 1];
     readonly VoiceMouthSpread: readonly [-1, 1];
 };
+export declare const VOICE_INPUT_NAMES: readonly VoiceInputName[];
+export type VoiceInputName = keyof typeof VOICE_INPUT_RANGES;
 /** Semantic import aliases; source analyzer amplitudes need not match Persona's. */
 export declare const NIZIMA_VOICE_ALIASES: {
     readonly LipSyncVolume: "VoiceVolume";

package/dist/values/lipsync.js

@@ -1,4 +1,4 @@
-import { finiteOr, isFiniteNumber, isRecord, nonEmptyString } from "./guards.js";
+import { finiteOr, isFiniteNumber, isRecord, keysOf, nonEmptyString } from "./guards.js";
 import { clamp } from "./limits.js";
 export const LIP_SYNC_VOWELS = ['A', 'I', 'U', 'E', 'O'];
 export const LIP_SYNC_PHONEMES = [...LIP_SYNC_VOWELS, 'S'];
@@ -56,20 +56,6 @@ export function healLipSyncConfig(raw) {
 export function isLipSyncMode(value) {
     return LIP_SYNC_MODES.some(mode => mode === value);
 }
-export const VOICE_INPUT_NAMES = [
-    'VoiceVolume',
-    'VoiceFrequency',
-    'VoiceVolumePlusMouthOpen',
-    'VoiceFrequencyPlusMouthSmile',
-    'VoiceA',
-    'VoiceI',
-    'VoiceU',
-    'VoiceE',
-    'VoiceO',
-    'VoiceSilence',
-    'VoiceMouthOpen',
-    'VoiceMouthSpread',
-];
 export const VOICE_INPUT_RANGES = {
     VoiceVolume: [0, 1],
     VoiceFrequency: [0, 1],
@@ -84,6 +70,7 @@ export const VOICE_INPUT_RANGES = {
     VoiceMouthOpen: [0, 1],
     VoiceMouthSpread: [-1, 1],
 };
+export const VOICE_INPUT_NAMES = keysOf(VOICE_INPUT_RANGES);
 /** Semantic import aliases; source analyzer amplitudes need not match Persona's. */
 export const NIZIMA_VOICE_ALIASES = {
     LipSyncVolume: 'VoiceVolume',

package/dist/values/locale.d.ts

@@ -1,11 +1,16 @@
-/** Locales shipped in the compiled catalogs (`pnpm i18n`). */
-export declare const LOCALES: readonly ["en", "ja", "zh-CN", "zh-TW"];
-export type Locale = (typeof LOCALES)[number];
+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';
 /** Native-language display names for the language picker (deliberately untranslated). */
-export declare const LOCALE_LABELS: Record<Locale, string>;
+export declare const LOCALE_LABELS: {
+    en: string;
+    ja: string;
+    'zh-CN': string;
+    'zh-TW': string;
+};
+/** Locales shipped in the compiled catalogs (`pnpm i18n`). */
+export declare const LOCALES: readonly Locale[];
 /** 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,5 +1,4 @@
-/** Locales shipped in the compiled catalogs (`pnpm i18n`). */
-export const LOCALES = ['en', 'ja', 'zh-CN', 'zh-TW'];
+import { isOneOf, keysOf } from "./guards.js";
 /** Native-language display names for the language picker (deliberately untranslated). */
 export const LOCALE_LABELS = {
     en: 'English',
@@ -7,9 +6,11 @@ export const LOCALE_LABELS = {
     'zh-CN': '简体中文',
     'zh-TW': '繁體中文',
 };
+/** Locales shipped in the compiled catalogs (`pnpm i18n`). */
+export const LOCALES = keysOf(LOCALE_LABELS);
 /** Best supported locale for a BCP 47-ish tag: exact match first, then fuzzy per language. */
 export function matchLocaleTag(tag) {
-    if (LOCALES.includes(tag))
+    if (isOneOf(tag, LOCALES))
         return tag;
     const t = tag.toLowerCase();
     // Most systems/browsers report `zh-TW`/`zh-HK` with no `hant` subtag, so match the regions too.

package/dist/values/scene-transition.d.ts

@@ -0,0 +1,14 @@
+import type { AssetRef, SceneTransition } from '../wire/types.ts';
+export declare const SCENE_TRANSITION_TYPES: readonly ["cut", "fade", "wipe", "circle", "image", "video"];
+export declare const SCENE_TRANSITION_DURATION_MIN_MS = 100;
+export declare const SCENE_TRANSITION_DURATION_MAX_MS = 10000;
+export declare const SCENE_TRANSITION_SWITCH_POINT_MIN = 0.05;
+export declare const SCENE_TRANSITION_SWITCH_POINT_MAX = 0.95;
+/** The destination scene's entrance effect; existing scenes keep an immediate cut. */
+export declare function defaultSceneTransition(): SceneTransition;
+/** The media kind a transition type plays, or null for the built-in effects. */
+export declare function sceneTransitionMedia(type: SceneTransition['type']): 'image' | 'video' | null;
+/** Whether `asset` can back the transition: an available image or video, matching the type when it plays media. */
+export declare function sceneTransitionAssetUsable(transition: SceneTransition, asset: Pick<AssetRef, 'kind' | 'exists'> | null | undefined): boolean;
+/** Heal saved transition settings independently, retaining media while another effect is selected. */
+export declare function healSceneTransition(raw: unknown): SceneTransition;

package/dist/values/scene-transition.js

@@ -0,0 +1,36 @@
+import { finiteOr, isOneOf, isRecord, nonEmptyString } from "./guards.js";
+import { clamp, hexColorOr } from "./limits.js";
+export const SCENE_TRANSITION_TYPES = ['cut', 'fade', 'wipe', 'circle', 'image', 'video'];
+export const SCENE_TRANSITION_DURATION_MIN_MS = 100;
+export const SCENE_TRANSITION_DURATION_MAX_MS = 10_000;
+export const SCENE_TRANSITION_SWITCH_POINT_MIN = 0.05;
+export const SCENE_TRANSITION_SWITCH_POINT_MAX = 0.95;
+/** The destination scene's entrance effect; existing scenes keep an immediate cut. */
+export function defaultSceneTransition() {
+    return { type: 'cut', durationMs: 1000, color: '#000000', assetId: null, switchPoint: 0.5, autoFade: false };
+}
+/** The media kind a transition type plays, or null for the built-in effects. */
+export function sceneTransitionMedia(type) {
+    return type === 'image' || type === 'video' ? type : null;
+}
+/** Whether `asset` can back the transition: an available image or video, matching the type when it plays media. */
+export function sceneTransitionAssetUsable(transition, asset) {
+    if (!asset?.exists || (asset.kind !== 'image' && asset.kind !== 'video'))
+        return false;
+    const media = sceneTransitionMedia(transition.type);
+    return media === null || asset.kind === media;
+}
+/** Heal saved transition settings independently, retaining media while another effect is selected. */
+export function healSceneTransition(raw) {
+    const d = defaultSceneTransition();
+    if (!isRecord(raw))
+        return d;
+    return {
+        type: isOneOf(raw.type, SCENE_TRANSITION_TYPES) ? raw.type : d.type,
+        durationMs: clamp(finiteOr(raw.durationMs, d.durationMs), SCENE_TRANSITION_DURATION_MIN_MS, SCENE_TRANSITION_DURATION_MAX_MS),
+        color: hexColorOr(raw.color, d.color),
+        assetId: nonEmptyString(raw.assetId),
+        switchPoint: clamp(finiteOr(raw.switchPoint, d.switchPoint), SCENE_TRANSITION_SWITCH_POINT_MIN, SCENE_TRANSITION_SWITCH_POINT_MAX),
+        autoFade: typeof raw.autoFade === 'boolean' ? raw.autoFade : d.autoFade,
+    };
+}

package/dist/wire/errors.js

@@ -1,10 +1,11 @@
+import { isOneOf } from "../values/guards.js";
 /** Every error the server can return, as string discriminants (never numeric bands). */
 export const API_ERROR_CODES = [
     'parse-error',
     'invalid-request',
     'unknown-method',
     'invalid-params',
-    /** A referenced id (scene, instance, model, asset, hotkey, shortcut, expression) resolves to nothing. */
+    /** A referenced id (scene, instance, model, asset, hotkey, automation, expression) resolves to nothing. */
     'not-found',
     /** The instance's model format cannot perform this method (e.g. MToon on Live2D). */
     'unsupported-for-format',
@@ -19,7 +20,7 @@ export const API_ERROR_CODES = [
     'internal',
 ];
 export function isApiErrorCode(v) {
-    return typeof v === 'string' && API_ERROR_CODES.includes(v);
+    return isOneOf(v, API_ERROR_CODES);
 }
 /** Thrown by {@link PersonaClient.call} when the server answers with an error envelope. */
 export class PersonaApiError extends Error {

package/dist/wire/events.d.ts

@@ -1,4 +1,4 @@
-import type { ExpressionPersistence, HotkeyState, ModelFormat, PoseStatus, SceneState, Settings, ShortcutInfo, TrackingStatus } from './types.ts';
+import type { AutomationInfo, ExpressionPersistence, HotkeyState, ModelFormat, PoseStatus, SceneState, Settings, TrackingStatus } from './types.ts';
 /** Every push event a session can subscribe to, with its payload. */
 export interface EventMap {
     /** Any scene mutation: create/delete/rename/activate/shortcut and persisted scene edits. */
@@ -10,9 +10,9 @@ export interface EventMap {
         modelId: string | null;
         config: HotkeyState;
     };
-    /** The app-shortcut list, its names, or its OS registrations changed. */
-    'shortcut.state': {
-        shortcuts: ShortcutInfo[];
+    /** The automation list, its names, or its OS registrations changed. */
+    'automation.state': {
+        automations: AutomationInfo[];
     };
     /** Network channel aggregates; `sources` includes webcam status and is optional for older servers. */
     'tracking.status': {

package/dist/wire/events.js

@@ -1,10 +1,11 @@
+import { isOneOf } from "../values/guards.js";
 // Built from a `Record<EventName, …>` so a new EventMap key that is missing
 // here fails the build instead of silently failing `isEventName`.
 export const EVENT_NAMES = Object.keys({
     'scene.changed': true,
     'settings.changed': true,
     'hotkey.state': true,
-    'shortcut.state': true,
+    'automation.state': true,
     'tracking.status': true,
     'instance.loaded': true,
     'expression.changed': true,
@@ -18,5 +19,5 @@ export const EVENT_NAMES = Object.keys({
     'expression.persistence': true,
 });
 export function isEventName(v) {
-    return typeof v === 'string' && EVENT_NAMES.includes(v);
+    return isOneOf(v, EVENT_NAMES);
 }

package/dist/wire/methods.d.ts

@@ -3,7 +3,7 @@ import type { ControllerMovementConfig, ControllerState } from '../values/contro
 import type { LipSyncCalibrationCommand, LipSyncConfig, LipSyncMode, LipSyncState } from '../values/lipsync.ts';
 import type { SceneInspection } from '../values/stage-info.ts';
 import type { EventName } from './events.ts';
-import type { AnchorOption, AppCapability, AssetKind, AssetRef, Attach, AttachHeadAngle, 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, ScenePatch, SceneState, ScreenPlacement, Settings, SettingsPatch, ShortcutInfo, TrackingSourceConfig, TrackingSourceId, TrackingSourceKind, TrackingStatus, VrmPlacement } from './types.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, ScenePatch, SceneState, ScreenPlacement, Settings, SettingsPatch, 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. */
@@ -295,14 +295,14 @@ export interface HotkeyTriggerRequest {
     hotkeyId: string;
 }
 export type HotkeyTriggerResponse = EmptyResponse;
-export type ShortcutListRequest = EmptyRequest;
-export interface ShortcutListResponse {
-    shortcuts: ShortcutInfo[];
+export type AutomationListRequest = EmptyRequest;
+export interface AutomationListResponse {
+    automations: AutomationInfo[];
 }
-export interface ShortcutTriggerRequest {
-    shortcutId: string;
+export interface AutomationRunRequest {
+    automationId: string;
 }
-export type ShortcutTriggerResponse = EmptyResponse;
+export type AutomationRunResponse = EmptyResponse;
 export type ModelListRequest = EmptyRequest;
 export interface ModelListResponse {
     models: ModelRef[];
@@ -842,13 +842,13 @@ export interface MethodMap {
         request: HotkeyTriggerRequest;
         response: HotkeyTriggerResponse;
     };
-    'shortcut.list': {
-        request: ShortcutListRequest;
-        response: ShortcutListResponse;
+    'automation.list': {
+        request: AutomationListRequest;
+        response: AutomationListResponse;
     };
-    'shortcut.trigger': {
-        request: ShortcutTriggerRequest;
-        response: ShortcutTriggerResponse;
+    'automation.run': {
+        request: AutomationRunRequest;
+        response: AutomationRunResponse;
     };
     'model.list': {
         request: ModelListRequest;

package/dist/wire/protocol.d.ts

@@ -1,10 +1,12 @@
 import type { InjectTarget } from './types.ts';
 /** Bumped on breaking wire changes; the server reports it in `hello` and clients warn on mismatch. */
-export declare const PROTOCOL_VERSION = 3;
+export declare const PROTOCOL_VERSION = 4;
 /** Default port the Persona API server listens on (user-configurable in the app). */
 export declare const DEFAULT_API_PORT = 25034;
 /** Default host clients dial: the server binds loopback unless LAN is opted in. */
 export declare const DEFAULT_API_HOST = "127.0.0.1";
+/** Scene activation waits for asset preparation before committing the new scene. */
+export declare const SCENE_ACTIVATION_TIMEOUT_MS = 120000;
 /** Server close code: the session's API key was revoked. Terminal — the client must not redial. */
 export declare const CLOSE_KEY_REVOKED = 4001;
 /** Server close code: the user disconnected this session from Persona's settings. Terminal — the client must not redial. */

package/dist/wire/protocol.js

@@ -1,9 +1,11 @@
 /** Bumped on breaking wire changes; the server reports it in `hello` and clients warn on mismatch. */
-export const PROTOCOL_VERSION = 3;
+export const PROTOCOL_VERSION = 4;
 /** Default port the Persona API server listens on (user-configurable in the app). */
 export const DEFAULT_API_PORT = 25034;
 /** Default host clients dial: the server binds loopback unless LAN is opted in. */
 export const DEFAULT_API_HOST = '127.0.0.1';
+/** Scene activation waits for asset preparation before committing the new scene. */
+export const SCENE_ACTIVATION_TIMEOUT_MS = 120_000;
 /** Server close code: the session's API key was revoked. Terminal — the client must not redial. */
 export const CLOSE_KEY_REVOKED = 4001;
 /** Server close code: the user disconnected this session from Persona's settings. Terminal — the client must not redial. */

package/dist/wire/schemas.d.ts

@@ -1,6 +1,22 @@
 import * as z from 'zod';
 import type { MethodName } from './methods.ts';
 import type { HotkeyConfig, ObjectContent } from './types.ts';
+/** A complete transition replacement; scene.patch remains stage-owned for its other slices. */
+export declare const SceneTransitionSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        circle: "circle";
+        image: "image";
+        video: "video";
+        cut: "cut";
+        fade: "fade";
+        wipe: "wipe";
+    }>;
+    durationMs: z.ZodNumber;
+    color: z.ZodString;
+    assetId: z.ZodNullable<z.ZodString>;
+    switchPoint: z.ZodNumber;
+    autoFade: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
 export declare const InjectTargetSchema: z.ZodObject<{
     type: z.ZodEnum<{
         input: "input";
@@ -164,8 +180,8 @@ export declare const requestSchemas: {
     'hotkey.trigger': z.ZodObject<{
         hotkeyId: z.ZodString;
     }, z.core.$strip>;
-    'shortcut.trigger': z.ZodObject<{
-        shortcutId: z.ZodString;
+    'automation.run': z.ZodObject<{
+        automationId: z.ZodString;
     }, z.core.$strip>;
     'tracking.addSource': z.ZodObject<{
         kind: z.ZodEnum<{

package/dist/wire/schemas.js

@@ -1,15 +1,25 @@
 import * as z from 'zod';
 import { CONTROLLER_DEAD_ZONE_MAX } from "../values/controller.js";
 import { isRecord } from "../values/guards.js";
-import { SPEECH_URL_MAX_LENGTH, STORAGE_KEY_MAX_LENGTH, STORAGE_VALUE_MAX_LENGTH } from "../values/limits.js";
+import { SCENE_COLOR_RE, SPEECH_URL_MAX_LENGTH, STORAGE_KEY_MAX_LENGTH, STORAGE_VALUE_MAX_LENGTH, } from "../values/limits.js";
 import { LIP_SYNC_CALIBRATION_ACTIONS, LIP_SYNC_GAIN_MAX, LIP_SYNC_MODES, LIP_SYNC_NOISE_GATE_MIN, LIP_SYNC_PHONEMES, LIP_SYNC_SMOOTHING_MAX, } from "../values/lipsync.js";
-import { ASSET_KINDS, POSE_SOURCE_IDS, TRACKING_SOURCE_IDS, TRACKING_SOURCE_KINDS } from "./types.js";
+import { SCENE_TRANSITION_DURATION_MAX_MS, SCENE_TRANSITION_DURATION_MIN_MS, SCENE_TRANSITION_SWITCH_POINT_MAX, SCENE_TRANSITION_SWITCH_POINT_MIN, SCENE_TRANSITION_TYPES, } from "../values/scene-transition.js";
+import { ASSET_KINDS, EFFECTS_QUALITY_LEVELS, INJECT_TARGET_TYPES, LIVE2D_ENGINES, MEDIAPIPE_DELEGATES, POSE_SOURCE_IDS, TRACKING_SOURCE_IDS, TRACKING_SOURCE_KINDS, } from "./types.js";
 // Runtime validation for the request side of the wire. Schemas exist for the
 // methods whose params the app's main process consumes directly; methods without
 // one are stage-owned — the renderer validates and heals them (same rules as the
 // panel). Fields marked z.custom are deliberately gated shallowly here because
 // the app heals them into shape server-side.
 const nonEmpty = z.string().min(1);
+/** A complete transition replacement; scene.patch remains stage-owned for its other slices. */
+export const SceneTransitionSchema = z.object({
+    type: z.enum(SCENE_TRANSITION_TYPES),
+    durationMs: z.number().min(SCENE_TRANSITION_DURATION_MIN_MS).max(SCENE_TRANSITION_DURATION_MAX_MS),
+    color: z.string().regex(SCENE_COLOR_RE),
+    assetId: nonEmpty.refine(v => v.trim() !== '', 'assetId must not be blank').nullable(),
+    switchPoint: z.number().min(SCENE_TRANSITION_SWITCH_POINT_MIN).max(SCENE_TRANSITION_SWITCH_POINT_MAX),
+    autoFade: z.boolean().default(false),
+});
 const port = z.number().int().min(1).max(65535);
 const lipSyncCalibration = z.discriminatedUnion('action', [
     z.object({ action: z.enum(LIP_SYNC_CALIBRATION_ACTIONS) }),
@@ -28,10 +38,10 @@ const mediapipePatch = z.object({
     face: z.boolean().optional(),
     hands: z.boolean().optional(),
     body: z.boolean().optional(),
-    delegate: z.enum(['CPU', 'GPU']).optional(),
+    delegate: z.enum(MEDIAPIPE_DELEGATES).optional(),
 });
 export const InjectTargetSchema = z.object({
-    type: z.enum(['input', 'live2d-param', 'vrm-expression']),
+    type: z.enum(INJECT_TARGET_TYPES),
     id: nonEmpty,
     instanceId: nonEmpty.optional(),
 });
@@ -49,9 +59,9 @@ export const SettingsPatchSchema = z.object({
         showFps: z.boolean().optional(),
         fpsLimit: z.number().optional(),
         selectionOutline: z.boolean().optional(),
-        effectsQuality: z.enum(['high', 'medium', 'low']).optional(),
+        effectsQuality: z.enum(EFFECTS_QUALITY_LEVELS).optional(),
         renderScale: z.number().optional(),
-        live2dEngine: z.enum(['pixi', 'three']).optional(),
+        live2dEngine: z.enum(LIVE2D_ENGINES).optional(),
     })
         .optional(),
 });
@@ -114,7 +124,7 @@ export const requestSchemas = {
         config: z.custom(isRecord, 'config must be a hotkey config'),
     }),
     'hotkey.trigger': z.object({ hotkeyId: nonEmpty }),
-    'shortcut.trigger': z.object({ shortcutId: nonEmpty }),
+    'automation.run': z.object({ automationId: nonEmpty }),
     'tracking.addSource': z.object({
         // Straight off the kind registry, for the same reason as ASSET_KINDS below: a schema
         // narrower than the constant answers invalid-params for a kind the app itself accepts.