@laplace.live/persona-sdk 1.21.0 → 1.23.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/effect-schema.js

@@ -147,11 +147,12 @@ export const EFFECT_SPECS = {
     blur: {
         radius: { default: 8, min: 0, max: 64, step: 0.5, unit: 'px' },
     },
+    // Intensity and Threshold take Warudo's Camera Bloom units; with Radius, the defaults are its look at 1080p.
     bloom: {
-        intensity: { default: 0, min: 0, max: 10, step: 0.01 },
-        threshold: { default: 0.5, min: 0, max: 2, step: 0.01 },
+        intensity: { default: 0.1, min: 0, max: 10, step: 0.01 },
+        threshold: { default: 0.75, min: 0, max: 5, step: 0.01 },
         thresholdSmooth: { default: 0, min: 0, max: 1, step: 0.01 },
-        radius: { default: 1, min: 0, max: 6, step: 0.01 },
+        radius: { default: 3, min: 0, max: 6, step: 0.01 },
         saturation: { default: 0, min: -1, max: 1, step: 0.01 },
         opacity: { default: 1, min: 0, max: 1, step: 0.01 },
         starRays: { default: 3, min: 1, max: 6, step: 1 },
@@ -308,7 +309,7 @@ export const EFFECT_COLOR_SPECS = {
         color5: { default: '#ffffff' },
     },
     rim: {
-        color: { default: '#ffffff' },
+        color: { default: '#ffeb74' },
     },
     outline: {
         color: { default: '#000000' },
@@ -394,13 +395,7 @@ export const EFFECT_ENUM_SPECS = {
     },
     blur: { mode: { default: 'gaussian', values: ['gaussian', 'bokeh'] } },
     bloom: { mode: { default: 'normal', values: ['normal', 'streak', 'star'] } },
-    rim: {
-        mode: { default: 'single', values: ['single', 'double', 'sharpenSingle', 'sharpenDouble'] },
-        blendMode: {
-            default: 'overlay',
-            values: EFFECT_BLEND_MODES,
-        },
-    },
+    rim: { mode: { default: 'single', values: ['single', 'double', 'sharpenSingle', 'sharpenDouble'] } },
     outline: { quality: { default: 'medium', values: ['low', 'medium', 'high'] } },
     colorWheels: { mode: { default: 'liftGammaGain', values: ['liftGammaGain', 'shadowsMidtonesHighlights'] } },
 };

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/item-transition.d.ts

@@ -1,12 +1,14 @@
-export declare const ITEM_TRANSITION_STYLES: readonly ["glitch", "dither", "pop", "cut"];
+export declare const ITEM_TRANSITION_STYLES: readonly ["glitch", "fade", "pop", "cut"];
 export type ItemTransitionStyle = (typeof ITEM_TRANSITION_STYLES)[number];
+/** What `fade` was named while it was a dithered dissolve; hosts still accept it, as `fade`. */
+export declare const LEGACY_DITHER_STYLE = "dither";
 /** One ramp length for a model switch, an object fade, or a body's entrance and exit. */
 export declare const ITEM_TRANSITION_DEFAULT_MS = 300;
 export declare const ITEM_TRANSITION_MAX_MS = 5000;
 export interface ItemTransition {
     /**
-     * `glitch` tears and burns through a dithered dissolve, `dither` is the plain screen-door,
-     * `pop` scales in and out, `cut` switches.
+     * `glitch` tears and burns through a dithered dissolve, `fade` fades each item by alpha as one
+     * layer, `pop` scales in and out, `cut` switches.
      */
     style: ItemTransitionStyle;
     /** Length of the ramp either way, 0–`ITEM_TRANSITION_MAX_MS`; 0 behaves as `cut`. */
@@ -16,8 +18,8 @@ export declare function defaultItemTransition(): ItemTransition;
 /** A per-call departure from the scene's item transition, for `stage.spawn`. */
 export interface SpawnTransition {
     style?: ItemTransitionStyle;
-    /** Entrance ramp, 0–`ITEM_TRANSITION_MAX_MS`; defaults to the scene's duration. */
+    /** Entrance ramp, 0–`ITEM_TRANSITION_MAX_MS`; defaults to the scene's duration, and a `cut` ignores it. */
     inMs?: number;
-    /** Exit ramp — expiry, eviction and clears — 0–`ITEM_TRANSITION_MAX_MS`; defaults to the scene's duration. */
+    /** Exit ramp — expiry, eviction and clears — 0–`ITEM_TRANSITION_MAX_MS`; as `inMs`. */
     outMs?: number;
 }

package/dist/values/item-transition.js

@@ -1,6 +1,8 @@
 // How stage items appear and disappear — models, objects and spawned bodies alike. Per scene,
 // on `SceneEnvironment.itemTransition`; `stage.spawn` may override it per call.
-export const ITEM_TRANSITION_STYLES = ['glitch', 'dither', 'pop', 'cut'];
+export const ITEM_TRANSITION_STYLES = ['glitch', 'fade', 'pop', 'cut'];
+/** What `fade` was named while it was a dithered dissolve; hosts still accept it, as `fade`. */
+export const LEGACY_DITHER_STYLE = 'dither';
 /** One ramp length for a model switch, an object fade, or a body's entrance and exit. */
 export const ITEM_TRANSITION_DEFAULT_MS = 300;
 export const ITEM_TRANSITION_MAX_MS = 5000;

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, ChromaKey, EnvironmentLook, KeyableContent, 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,39 @@ 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;
+/** Chroma key tolerance bounds, OBS's 1–1000 ÷ 1000; the floor keeps the edge ramps from dividing by zero. */
+export declare const CHROMA_KEY_TOLERANCE_MIN = 0.001;
+export declare const CHROMA_KEY_TOLERANCE_MAX = 1;
+/** OBS's Chroma Key defaults: green, similarity 400, smoothness 80, spill reduction 100. */
+export declare const DEFAULT_CHROMA_KEY: ChromaKey;
+/** Whether a chroma key can reach the content's pixels: image, video and webpage quads. */
+export declare function isKeyableContent(content: ObjectContent): content is KeyableContent;
+/** 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 +323,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. */