@laplace.live/persona-sdk 1.9.0 → 1.10.0

package/dist/values/limits.d.ts

@@ -1,4 +1,4 @@
-import type { AssetRef, Attach, EnvironmentLook, ModelFormat, MToonTuning, ObjectContent, ObjectSpace, SceneEnvironment, SceneLight, SceneLightType, ScreenPlacement, VrmPlacement } from '../wire/types.ts';
+import type { AssetRef, Attach, EnvironmentLook, ModelFormat, MToonTuning, ObjectContent, ObjectSpace, 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;
@@ -13,6 +13,7 @@ export declare function hexColorOr(v: unknown, fallback: string): string;
 /** Drop the alpha byte a picker's hex input can produce (`#rrggbbaa` → `#rrggbb`). */
 export declare function opaqueHex(hex: string): string;
 export declare const SCENE_LIGHT_INTENSITY_MAX = 2;
+export declare const SCENE_SKYBOX_INTENSITY_MAX = 2;
 /**
  * Point lights need headroom against inverse-square decay; directional and ambient
  * lights have no falloff and would wash out the stage at the same intensity.
@@ -63,6 +64,17 @@ export declare const ELEVATION_LIMIT: number;
 /** Manual navigation distance bounds; authored cameras retain signed, unrestricted distances. */
 export declare const DISTANCE_MIN = 0.35;
 export declare const DISTANCE_MAX = 20;
+/** A scene's manual navigation distance bounds, in world units. */
+export interface CameraDistanceLimits {
+    min: number;
+    max: number;
+}
+/**
+ * {@link DISTANCE_MIN} and {@link DISTANCE_MAX}, widened in proportion for an Environment Model placed larger
+ * or smaller than a ~10 m room. Neither bound ever narrows.
+ * @param setRadius The loaded set's own bounding radius, before its placement scale; null until one has loaded.
+ */
+export declare function cameraDistanceLimits(env: Pick<SceneEnvironment, 'modelAssetId' | 'modelPlace'>, setRadius: number | null): CameraDistanceLimits;
 /** ×2 doubles Cubism's own breath amplitude — past that the head sway reads as a nod, not a breath. */
 export declare const BREATH_DEPTH_MAX = 2;
 export declare const MTOON_NORMAL_SCALE_MAX = 2;
@@ -78,6 +90,8 @@ export declare const MTOON_UV_ANIMATION_MAX = 4;
 export declare function defaultMToonTuning(): MToonTuning;
 export declare const DEFAULT_LIGHT_AZIMUTH_DEG = 45;
 export declare const DEFAULT_LIGHT_ELEVATION_DEG: number;
+/** What a following light tracks when `followCameraOptions` is omitted. */
+export declare const DEFAULT_LIGHT_FOLLOW_CAMERA_OPTIONS: SceneLightCameraFollowOptions;
 /** A fresh light of `type`, at the defaults that read sensibly for that type. */
 export declare function defaultSceneLightOf(type: SceneLightType): SceneLight;
 /**
@@ -115,17 +129,18 @@ export declare function applyEnvironmentLook(env: SceneEnvironment, look: Enviro
  * simply arrive wearing it.
  */
 export declare function environmentLookIsUntouched(env: SceneEnvironment, reference: SceneEnvironment): boolean;
+/** An environment asset: the 3D set (`modelAssetId`) or the equirect map (`iblAssetId`). */
+export type EnvironmentSlot = 'model' | 'map';
 /**
- * Point an environment at one asset, or at none.
- *
- * {@link SceneEnvironment.iblAssetId} and {@link SceneEnvironment.modelAssetId} are a
- * single slot — a scene wears an equirect map or a 3D set — so this clears whichever
- * the pick is not. `bakeFromModel` goes with the set: on for a set arriving where none was,
- * kept across a swap, dropped otherwise — it wins over a picked map, so a stale one would
- * leave a fresh map lighting nothing.
- * Light overrides index the set's own lamps, so a different set — or none — drops them.
- * `modelLook` stays put: the stage replaces it as the next set parses, and the desktop
- * reads the outgoing one as what the scene wears now when deciding to adopt the next.
+ * The edit that removes one environment asset, or both for null. The model takes its baking and
+ * light overrides along; removing only the map hands lighting to a remaining model. `modelLook`
+ * stays, as in {@link environmentWithAsset}.
+ */
+export declare function environmentClearPatch(env: SceneEnvironment, slot: EnvironmentSlot | null): Partial<Pick<SceneEnvironment, 'iblAssetId' | 'modelAssetId' | 'bakeFromModel' | 'modelLightOverrides'>>;
+/**
+ * Pick a model or map without removing the other; null clears both for legacy callers.
+ * A picked map becomes the lighting source. A first model generates lighting only without a map.
+ * `modelLook` stays put so the desktop can compare the outgoing look before adopting the next.
  * @returns A new environment; the input is untouched.
  */
 export declare function environmentWithAsset(env: SceneEnvironment, asset: Pick<AssetRef, 'id' | 'kind'> | null): SceneEnvironment;

package/dist/values/limits.js

@@ -29,6 +29,7 @@ export function opaqueHex(hex) {
     return /^#[0-9a-f]{8}$/i.test(hex) ? hex.slice(0, 7) : hex;
 }
 export const SCENE_LIGHT_INTENSITY_MAX = 2;
+export const SCENE_SKYBOX_INTENSITY_MAX = 2;
 /**
  * Point lights need headroom against inverse-square decay; directional and ambient
  * lights have no falloff and would wash out the stage at the same intensity.
@@ -90,6 +91,17 @@ export const ELEVATION_LIMIT = (80 * Math.PI) / 180;
 /** Manual navigation distance bounds; authored cameras retain signed, unrestricted distances. */
 export const DISTANCE_MIN = 0.35;
 export const DISTANCE_MAX = 20;
+/** Bounding radius of the set the distance bounds are sized for: a ~10 m room {@link DISTANCE_MAX} frames whole. */
+const DISTANCE_SET_RADIUS = 5;
+/**
+ * {@link DISTANCE_MIN} and {@link DISTANCE_MAX}, widened in proportion for an Environment Model placed larger
+ * or smaller than a ~10 m room. Neither bound ever narrows.
+ * @param setRadius The loaded set's own bounding radius, before its placement scale; null until one has loaded.
+ */
+export function cameraDistanceLimits(env, setRadius) {
+    const size = env.modelAssetId === null || setRadius === null ? 1 : (setRadius * env.modelPlace.scale) / DISTANCE_SET_RADIUS;
+    return { min: DISTANCE_MIN * Math.min(1, size), max: DISTANCE_MAX * Math.max(1, size) };
+}
 /** ×2 doubles Cubism's own breath amplitude — past that the head sway reads as a nod, not a breath. */
 export const BREATH_DEPTH_MAX = 2;
 export const MTOON_NORMAL_SCALE_MAX = 2;
@@ -124,12 +136,20 @@ export function defaultMToonTuning() {
 // Angles at which lightDirection reproduces (1,1,1).normalize() — the app's original hardcoded light.
 export const DEFAULT_LIGHT_AZIMUTH_DEG = 45;
 export const DEFAULT_LIGHT_ELEVATION_DEG = (Math.asin(1 / Math.sqrt(3)) * 180) / Math.PI;
+/** What a following light tracks when `followCameraOptions` is omitted. */
+export const DEFAULT_LIGHT_FOLLOW_CAMERA_OPTIONS = {
+    position: true,
+    rotation: true,
+    distance: true,
+};
 /** A fresh light of `type`, at the defaults that read sensibly for that type. */
 export function defaultSceneLightOf(type) {
     return {
         id: crypto.randomUUID(),
         type,
         enabled: true,
+        followCamera: false,
+        followCameraOptions: { ...DEFAULT_LIGHT_FOLLOW_CAMERA_OPTIONS },
         color: '#ffffff',
         // Ambient is a flat albedo floor with no shading — 1.0 alone washes the model out.
         intensity: type === 'ambient' ? 0.4 : 1,
@@ -210,27 +230,32 @@ export function environmentLookIsUntouched(env, reference) {
     return looked(env) === looked(reference);
 }
 /**
- * Point an environment at one asset, or at none.
- *
- * {@link SceneEnvironment.iblAssetId} and {@link SceneEnvironment.modelAssetId} are a
- * single slot — a scene wears an equirect map or a 3D set — so this clears whichever
- * the pick is not. `bakeFromModel` goes with the set: on for a set arriving where none was,
- * kept across a swap, dropped otherwise — it wins over a picked map, so a stale one would
- * leave a fresh map lighting nothing.
- * Light overrides index the set's own lamps, so a different set — or none — drops them.
- * `modelLook` stays put: the stage replaces it as the next set parses, and the desktop
- * reads the outgoing one as what the scene wears now when deciding to adopt the next.
+ * The edit that removes one environment asset, or both for null. The model takes its baking and
+ * light overrides along; removing only the map hands lighting to a remaining model. `modelLook`
+ * stays, as in {@link environmentWithAsset}.
+ */
+export function environmentClearPatch(env, slot) {
+    if (slot === 'map')
+        return { iblAssetId: null, bakeFromModel: env.modelAssetId !== null };
+    const model = { modelAssetId: null, bakeFromModel: false, modelLightOverrides: {} };
+    return slot === 'model' ? model : { ...model, iblAssetId: null };
+}
+/**
+ * Pick a model or map without removing the other; null clears both for legacy callers.
+ * A picked map becomes the lighting source. A first model generates lighting only without a map.
+ * `modelLook` stays put so the desktop can compare the outgoing look before adopting the next.
  * @returns A new environment; the input is untouched.
  */
 export function environmentWithAsset(env, asset) {
-    const isSet = asset?.kind === 'prop';
-    const modelAssetId = isSet ? asset.id : null;
+    if (asset === null)
+        return { ...env, ...environmentClearPatch(env, null) };
+    if (asset.kind !== 'prop')
+        return { ...env, iblAssetId: asset.id, bakeFromModel: false };
     return {
         ...env,
-        iblAssetId: asset !== null && !isSet ? asset.id : null,
-        modelAssetId,
-        bakeFromModel: isSet && (env.modelAssetId === null || env.bakeFromModel),
-        modelLightOverrides: modelAssetId === env.modelAssetId ? env.modelLightOverrides : {},
+        modelAssetId: asset.id,
+        bakeFromModel: env.modelAssetId === null ? env.iblAssetId === null : env.bakeFromModel,
+        modelLightOverrides: asset.id === env.modelAssetId ? env.modelLightOverrides : {},
     };
 }
 export const PLACE_2D_SCALE_MIN = 0.01;

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

@@ -22,6 +22,9 @@ export interface SceneAssetInfo {
 /** Metadata for the active scene, tagged so a response from a previous scene can be discarded. */
 export interface SceneInspection {
     sceneId: string;
-    environment: Omit<SceneAssetInfo, 'mediaSize'>;
+    environment: Omit<SceneAssetInfo, 'mediaSize'> & {
+        /** The set's own bounding radius before placement scale, for `cameraDistanceLimits`; omitted by older hosts. */
+        radius?: number | null;
+    };
     objects: Record<string, SceneAssetInfo>;
 }

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, 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';
+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, 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. */
@@ -40,6 +40,17 @@ export type ScenePatchRequest = ScenePatch;
 export interface ScenePatchResponse {
     scene: Scene;
 }
+/** Rebase one active-scene light against the displayed camera without moving or re-aiming it. */
+export interface SceneSetLightFollowCameraRequest {
+    lightId: string;
+    followCamera: boolean;
+    /** Merges independent follow choices while preserving the light's displayed pose. */
+    options?: Partial<SceneLightCameraFollowOptions>;
+}
+export interface SceneSetLightFollowCameraResponse {
+    /** The rebased light, or null if it no longer exists in the active scene. */
+    light: SceneLight | null;
+}
 export type InstanceListRequest = EmptyRequest;
 export interface InstanceListResponse {
     instances: InstanceRuntime[];
@@ -667,6 +678,10 @@ export interface MethodMap {
         request: ScenePatchRequest;
         response: ScenePatchResponse;
     };
+    'scene.setLightFollowCamera': {
+        request: SceneSetLightFollowCameraRequest;
+        response: SceneSetLightFollowCameraResponse;
+    };
     'instance.list': {
         request: InstanceListRequest;
         response: InstanceListResponse;

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

@@ -113,6 +113,15 @@ export declare const requestSchemas: {
     'scene.delete': z.ZodObject<{
         sceneId: z.ZodString;
     }, z.core.$strip>;
+    'scene.setLightFollowCamera': z.ZodObject<{
+        lightId: z.ZodString;
+        followCamera: z.ZodBoolean;
+        options: z.ZodOptional<z.ZodObject<{
+            position: z.ZodOptional<z.ZodBoolean>;
+            rotation: z.ZodOptional<z.ZodBoolean>;
+            distance: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
     'instance.add': z.ZodObject<{
         modelId: z.ZodString;
     }, z.core.$strip>;

package/dist/wire/schemas/requests.js

@@ -78,6 +78,11 @@ export const requestSchemas = {
     'scene.duplicate': z.object({ sceneId: nonEmpty }),
     'scene.rename': z.object({ sceneId: nonEmpty, name: nonEmpty }),
     'scene.delete': z.object({ sceneId: nonEmpty }),
+    'scene.setLightFollowCamera': z.object({
+        lightId: nonEmpty,
+        followCamera: z.boolean(),
+        options: z.object({ position: z.boolean(), rotation: z.boolean(), distance: z.boolean() }).partial().optional(),
+    }),
     'instance.add': z.object({ modelId: nonEmpty }),
     'instance.setModel': z.object({ instanceId: nonEmpty, modelId: nonEmpty }),
     'object.add': z.object({

package/dist/wire/types.d.ts

@@ -341,6 +341,25 @@ export declare const SHADOW_QUALITY_LEVELS: readonly ["off", "low", "medium", "h
 export type ShadowQuality = (typeof SHADOW_QUALITY_LEVELS)[number];
 export declare const SHADOW_FILTERS: readonly ["pcf", "pcss"];
 export type ShadowFilter = (typeof SHADOW_FILTERS)[number];
+/** Camera components followed by a light; omitted options default to all true. */
+export interface SceneLightCameraFollowOptions {
+    /** Follow the camera's target/pan translation. */
+    position: boolean;
+    /** Follow the camera's world rotation, including roll. */
+    rotation: boolean;
+    /** Follow the signed orbit distance from target to camera. */
+    distance: boolean;
+}
+/** Frozen camera components used when the matching follow option is disabled. */
+export interface SceneLightCameraFollowReference extends Pick<OrbitTransform, 'targetX' | 'targetY' | 'targetZ' | 'distance'> {
+    /** Unit quaternion in world space. */
+    rotation: {
+        x: number;
+        y: number;
+        z: number;
+        w: number;
+    };
+}
 /**
  * One scene light. Angles are degrees. Directional lights aim with
  * azimuth/elevation and sit at x/y/z (which moves their handle and shadow
@@ -354,6 +373,12 @@ export interface SceneLight {
     type: SceneLightType;
     /** Mutes illumination and shadows. Defaults to true; omitted by hosts without light toggles. */
     enabled?: boolean;
+    /** Camera-relative placement and angles; defaults to false. Gate editing on `camera-follow-lights`; ambient ignores it. */
+    followCamera?: boolean;
+    /** Independent camera components; omitted means all true. */
+    followCameraOptions?: SceneLightCameraFollowOptions;
+    /** Missing references use target zero, identity rotation, and distance zero for disabled components. */
+    followCameraReference?: SceneLightCameraFollowReference;
     color: string;
     intensity: number;
     azimuth: number;
@@ -840,11 +865,8 @@ export interface EnvironmentLook {
     color: SceneColorGrade;
 }
 /**
- * The world the 3D stage sits in: one environment — a map, or a 3D set the avatar
- * stands inside — the scene-global fog, and post-processing.
- *
- * The two asset ids are a single slot the editors write through
- * {@link environmentWithAsset}: at most one is ever set.
+ * The world the 3D stage sits in: independent environment map and 3D set,
+ * scene-global fog, and post-processing.
  */
 export interface SceneEnvironment {
     /** Equirectangular `.hdr` or image driving the environment lighting, or null. */
@@ -856,14 +878,21 @@ export interface SceneEnvironment {
      * has no IBL term of its own and the app adds one.
      */
     iblAvatarAmount: number;
+    /** Show the selected map, falling back to the model's sky, independently of the lighting source. */
     showSkybox: boolean;
+    /** Visible skybox blur, 0..1; defaults to 0. Omitted by older hosts. */
+    skyboxBlur?: number;
+    /** Visible skybox brightness, 0..2; defaults to 1. Omitted by older hosts. */
+    skyboxIntensity?: number;
+    /** Panorama and lighting yaw in radians; defaults to 0 and may wrap beyond one turn. Omitted by older hosts. */
+    iblRotation?: number;
     /** A `prop` asset (glb/gltf) rendered as the set the scene sits in, or null. */
     modelAssetId: string | null;
     /** Where that set sits, in the same units as an object's `place3d`. */
     modelPlace: Place3D;
     /**
-     * Bake the set's geometry into the environment lighting. It wins over
-     * {@link SceneEnvironment.iblAssetId}, so it only means anything with a set.
+     * Generate lighting from the set, using the selected map or the set's sky as input.
+     * False uses the map directly; the skybox remains independent of this choice.
      */
     bakeFromModel: boolean;
     /** Whether lights baked into the set render at all. */
@@ -940,7 +969,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", "shadow-filters"];
+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"];
 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`. */

package/dist/wire/types.js

@@ -42,7 +42,9 @@ export const APP_CAPABILITIES = [
     'scene-transitions',
     'area-lights',
     'spot-lights',
+    'camera-follow-lights',
     'shadow-filters',
+    'environment-map-model',
 ];
 export function isAppCapability(v) {
     return isOneOf(v, APP_CAPABILITIES);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@laplace.live/persona-sdk",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "description": "TypeScript SDK and wire schema for the LAPLACE Persona plugin API",
   "license": "MIT",
   "type": "module",
@@ -34,7 +34,7 @@
     "node": ">=24"
   },
   "dependencies": {
-    "zod": "^4.6.2"
+    "zod": "^4.6.4"
   },
   "scripts": {
     "build": "rimraf dist && tsc -p tsconfig.build.json",