@laplace.live/persona-sdk 1.8.1 → 1.10.0

package/dist/index.d.ts

@@ -19,6 +19,7 @@ export * from './values/model-info.ts';
 export * from './values/scene-transition.ts';
 export * from './values/stage-info.ts';
 export * from './values/terms.ts';
+export * from './values/volumetric-lighting.ts';
 export * from './values/vrm-bindings.ts';
 export * from './wire/envelope.ts';
 export * from './wire/errors.ts';

package/dist/index.js

@@ -21,6 +21,7 @@ export * from "./values/model-info.js";
 export * from "./values/scene-transition.js";
 export * from "./values/stage-info.js";
 export * from "./values/terms.js";
+export * from "./values/volumetric-lighting.js";
 export * from "./values/vrm-bindings.js";
 export * from "./wire/envelope.js";
 export * from "./wire/errors.js";

package/dist/values/controller.d.ts

@@ -75,6 +75,11 @@ export interface ControllerMovementConfig {
     /** Turn a VRM avatar toward its movement direction. */
     faceMovement: boolean;
 }
+export declare const CONTROLLER_MOVE_SPEED_MAX = 10;
+export declare const CONTROLLER_TURN_SPEED_MAX = 720;
+export declare const CONTROLLER_MOVEMENT_SMOOTHING_MAX = 0.5;
+export declare const CONTROLLER_WALK_SPEED_MIN = 0.1;
+export declare const CONTROLLER_WALK_SPEED_MAX = 10;
 export declare const DEFAULT_CONTROLLER_MOVEMENT: Readonly<ControllerMovementConfig>;
 /** Heal saved movement or a merged API patch using the same limits as the controls. */
 export declare function healControllerMovement(raw: unknown): ControllerMovementConfig;

package/dist/values/controller.js

@@ -114,9 +114,11 @@ export function controllerSlot(full) {
         ? parts.slot
         : null;
 }
-const CONTROLLER_MOVE_SPEED_MAX = 10;
-const CONTROLLER_TURN_SPEED_MAX = 720;
-const CONTROLLER_MOVEMENT_SMOOTHING_MAX = 0.5;
+export const CONTROLLER_MOVE_SPEED_MAX = 10;
+export const CONTROLLER_TURN_SPEED_MAX = 720;
+export const CONTROLLER_MOVEMENT_SMOOTHING_MAX = 0.5;
+export const CONTROLLER_WALK_SPEED_MIN = 0.1;
+export const CONTROLLER_WALK_SPEED_MAX = 10;
 export const DEFAULT_CONTROLLER_MOVEMENT = {
     enabled: false,
     slot: 1,
@@ -140,7 +142,7 @@ export function healControllerMovement(raw) {
         smoothing: clamp(finiteOr(r.smoothing, d.smoothing), 0, CONTROLLER_MOVEMENT_SMOOTHING_MAX),
         walkEnabled: typeof r.walkEnabled === 'boolean' ? r.walkEnabled : d.walkEnabled,
         walkClip: nonEmptyString(r.walkClip),
-        walkSpeed: clamp(finiteOr(r.walkSpeed, d.walkSpeed), 0.1, 10),
+        walkSpeed: clamp(finiteOr(r.walkSpeed, d.walkSpeed), CONTROLLER_WALK_SPEED_MIN, CONTROLLER_WALK_SPEED_MAX),
         faceMovement: typeof r.faceMovement === 'boolean' ? r.faceMovement : d.faceMovement,
     };
 }

package/dist/values/gltf-extensions.d.ts

@@ -4,7 +4,7 @@ export type GltfLoadPath = 'vrm' | 'gltf';
 export declare const LAPLACE_OUTFIT = "LAPLACE_outfit";
 /** The app's room extension, read on props and sets — `renderer/vrm/gltf-extension.ts`. */
 export declare const LAPLACE_ENVIRONMENT = "LAPLACE_environment";
-/** `GLTFLoader` extensions that throw at parse without a decoder — and the app sets none. */
+/** `GLTFLoader` extensions needing a decoder the app doesn't set. */
 export declare const DECODER_EXTENSIONS: string[];
 /** Per loader; the app's own extensions ride with the loader that reads them. */
 export declare const SUPPORTED_EXTENSIONS: Record<GltfLoadPath, ReadonlySet<string>>;

package/dist/values/gltf-extensions.js

@@ -15,16 +15,12 @@ const VRM_EXTENSIONS = [
     'VRMC_materials_mtoon',
     'VRMC_materials_hdr_emissiveMultiplier',
 ];
-/** `GLTFLoader` extensions that throw at parse without a decoder — and the app sets none. */
-export const DECODER_EXTENSIONS = [
-    'KHR_draco_mesh_compression',
-    'KHR_texture_basisu',
-    'EXT_meshopt_compression',
-    'KHR_meshopt_compression',
-];
+/** `GLTFLoader` extensions needing a decoder the app doesn't set. */
+export const DECODER_EXTENSIONS = ['KHR_texture_basisu'];
 /** The rest of `GLTFLoader`'s own `EXTENSIONS` table, which either loader renders as authored. */
 const RENDERABLE = [
     'KHR_binary_glTF',
+    'KHR_draco_mesh_compression',
     'KHR_lights_punctual',
     'KHR_materials_clearcoat',
     'KHR_materials_dispersion',
@@ -42,6 +38,8 @@ const RENDERABLE = [
     'EXT_materials_bump',
     'EXT_texture_webp',
     'EXT_texture_avif',
+    'EXT_meshopt_compression',
+    'KHR_meshopt_compression',
     'EXT_mesh_gpu_instancing',
 ];
 /** Per loader; the app's own extensions ride with the loader that reads them. */

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;
@@ -6,21 +6,33 @@ export declare function clamp01(v: number): number;
 export declare function wrapAngle(a: number): number;
 export declare const DEFAULT_LIVE2D_PLACEMENT: ScreenPlacement;
 export declare const DEFAULT_VRM_PLACEMENT: VrmPlacement;
-/** Scene colors heal to 6-digit hex. */
+/** Scene colors heal to 6-digit hex; both cases are spelled out because JSON Schema patterns carry no flags. */
 export declare const SCENE_COLOR_RE: RegExp;
 /** The value when it is a 6-digit hex color, else `fallback` — validated, never clamped. */
 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 decay physically (1/d²), so reach rides on power the way Blender's
- * does: 20 stays visible to ~10 m where 2 self-extinguishes by ~5. The other
- * types have no falloff to overcome — 20 would just blow the stage out.
+ * 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.
  */
 export declare const SCENE_LIGHT_POINT_INTENSITY_MAX = 20;
-/** Intensity ceiling for a light of `type` — one source for the slider and scene healing. */
+export declare const SCENE_LIGHT_AREA_SIZE_MIN = 0.01;
+export declare const SCENE_LIGHT_AREA_SIZE_MAX = 20;
+export declare const DEFAULT_AREA_LIGHT_SIZE = 1;
+export declare const SCENE_LIGHT_SPOT_ANGLE_MIN = 1;
+/** A 90° half-angle would make the spot shadow camera's 180° projection singular. */
+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;
+/** 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. */
+export declare function sceneLightIsAimed(type: SceneLightType): boolean;
+/** Whether a light of `type` can cast shadows; ambient and area lights never do. */
+export declare function sceneLightCastsShadows(type: SceneLightType): boolean;
 export declare const LIVE2D_SCALE_MIN = 0.1;
 export declare const LIVE2D_SCALE_MAX = 24;
 export declare const VRM_SCALE_MIN = 0.05;
@@ -30,6 +42,8 @@ export declare const SCENE_LIGHT_RANGE_MAX = 20;
 export declare const SCENE_LIGHT_SHADOW_RADIUS_MAX = 16;
 /** The point disk's 32 fixed taps stay dense across a far wider penumbra than 5 dithered ones. */
 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;
 /** Shadow softness (PCF disk radius, in shadow-map texels) ceiling for a light of `type`. */
 export declare function sceneLightShadowRadiusMax(type: SceneLightType): number;
 /**
@@ -50,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;
@@ -65,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;
 /**
@@ -102,16 +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: it outlives the id it names, and
- * 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

@@ -18,8 +18,8 @@ export function wrapAngle(a) {
 }
 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. */
-export const SCENE_COLOR_RE = /^#[0-9a-f]{6}$/i;
+/** Scene colors heal to 6-digit hex; both cases are spelled out because JSON Schema patterns carry no flags. */
+export const SCENE_COLOR_RE = /^#[0-9a-fA-F]{6}$/;
 /** The value when it is a 6-digit hex color, else `fallback` — validated, never clamped. */
 export function hexColorOr(v, fallback) {
     return typeof v === 'string' && SCENE_COLOR_RE.test(v) ? v : fallback;
@@ -29,15 +29,31 @@ 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 decay physically (1/d²), so reach rides on power the way Blender's
- * does: 20 stays visible to ~10 m where 2 self-extinguishes by ~5. The other
- * types have no falloff to overcome — 20 would just blow the stage out.
+ * 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.
  */
 export const SCENE_LIGHT_POINT_INTENSITY_MAX = 20;
-/** Intensity ceiling for a light of `type` — one source for the slider and scene healing. */
+export const SCENE_LIGHT_AREA_SIZE_MIN = 0.01;
+export const SCENE_LIGHT_AREA_SIZE_MAX = 20;
+export const DEFAULT_AREA_LIGHT_SIZE = 1;
+export const SCENE_LIGHT_SPOT_ANGLE_MIN = 1;
+/** A 90° half-angle would make the spot shadow camera's 180° projection singular. */
+export const SCENE_LIGHT_SPOT_ANGLE_MAX = 89;
+export const DEFAULT_SPOT_ANGLE_DEG = 30;
+export const DEFAULT_SPOT_PENUMBRA = 0.3;
+/** Positional lights need falloff headroom; the slider and scene healing share this ceiling. */
 export function sceneLightIntensityMax(type) {
-    return type === 'point' ? SCENE_LIGHT_POINT_INTENSITY_MAX : SCENE_LIGHT_INTENSITY_MAX;
+    return type === 'directional' || type === 'ambient' ? SCENE_LIGHT_INTENSITY_MAX : SCENE_LIGHT_POINT_INTENSITY_MAX;
+}
+/** Whether a light of `type` aims with azimuth/elevation. */
+export function sceneLightIsAimed(type) {
+    return type === 'directional' || type === 'spot' || type === 'area';
+}
+/** Whether a light of `type` can cast shadows; ambient and area lights never do. */
+export function sceneLightCastsShadows(type) {
+    return type !== 'ambient' && type !== 'area';
 }
 // Live2D bounds are the zoom clamp (zoom.ts re-exports these); VRM scales a world-space root.
 export const LIVE2D_SCALE_MIN = 0.1;
@@ -51,6 +67,8 @@ export const SCENE_LIGHT_RANGE_MAX = 20;
 export const SCENE_LIGHT_SHADOW_RADIUS_MAX = 16;
 /** The point disk's 32 fixed taps stay dense across a far wider penumbra than 5 dithered ones. */
 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;
 /** 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;
@@ -73,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;
@@ -107,25 +136,40 @@ 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,
-        azimuth: DEFAULT_LIGHT_AZIMUTH_DEG,
-        elevation: DEFAULT_LIGHT_ELEVATION_DEG,
+        azimuth: type === 'area' || type === 'spot' ? 0 : DEFAULT_LIGHT_AZIMUTH_DEG,
+        elevation: type === 'area' || type === 'spot' ? 0 : DEFAULT_LIGHT_ELEVATION_DEG,
         x: 0,
         y: 1.4,
         z: 1,
         range: 10,
+        angle: DEFAULT_SPOT_ANGLE_DEG,
+        penumbra: DEFAULT_SPOT_PENUMBRA,
+        width: DEFAULT_AREA_LIGHT_SIZE,
+        height: DEFAULT_AREA_LIGHT_SIZE,
+        roll: 0,
         // A point light shadow is six cube faces, so it stays opt-in where a
         // directional light's single depth pass can be on by default.
         shadowQuality: type === 'directional' ? 'high' : 'off',
         shadowRadius: 6,
+        shadowFilter: 'pcf',
+        shadowSourceSize: DEFAULT_LIGHT_SHADOW_SOURCE_SIZE,
     };
 }
 /**
@@ -186,26 +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: it outlives the id it names, and
- * 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.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/values/volumetric-lighting.d.ts

@@ -0,0 +1,42 @@
+import { type SceneEnvironment, type SceneVolumetricLighting } from '../wire/types.ts';
+/** Slider and healing metadata for the haze's numeric settings. */
+export declare const SCENE_VOLUMETRIC_LIGHTING_SPECS: {
+    readonly density: {
+        readonly default: 1;
+        readonly min: 0;
+        readonly max: 10;
+        readonly step: 0.05;
+        readonly digits: 2;
+    };
+    readonly intensity: {
+        readonly default: 1;
+        readonly min: 0;
+        readonly max: 10;
+        readonly step: 0.05;
+        readonly digits: 2;
+    };
+    readonly range: {
+        readonly default: 20;
+        readonly min: 1;
+        readonly max: 100;
+        readonly step: 1;
+        readonly digits: 0;
+    };
+    readonly speed: {
+        readonly default: 0.2;
+        readonly min: 0;
+        readonly max: 5;
+        readonly step: 0.05;
+        readonly digits: 2;
+    };
+};
+/** Existing scenes retain clear air until volumetric lighting is enabled. */
+export declare function defaultSceneVolumetricLighting(): SceneVolumetricLighting;
+/** Restore saved haze settings and clamp them to the shared editor bounds. */
+export declare function healSceneVolumetricLighting(raw: unknown): SceneVolumetricLighting;
+/** An environment edit whose haze settings arrive as leaves, so queued edits never replace one another. */
+export type EnvironmentPatch = Omit<Partial<SceneEnvironment>, 'volumetricLighting'> & {
+    volumetricLighting?: Partial<SceneVolumetricLighting>;
+};
+/** Merge `patch` into `target` in place; haze leaves land in the settings object `target` already holds. */
+export declare function mergeEnvironmentPatch(target: EnvironmentPatch, { volumetricLighting, ...fields }: EnvironmentPatch): void;

package/dist/values/volumetric-lighting.js

@@ -0,0 +1,43 @@
+import { EFFECTS_QUALITY_LEVELS } from "../wire/types.js";
+import { finiteOr, isOneOf, isRecord } from "./guards.js";
+import { clamp } from "./limits.js";
+/** Slider and healing metadata for the haze's numeric settings. */
+export const SCENE_VOLUMETRIC_LIGHTING_SPECS = {
+    density: { default: 1, min: 0, max: 10, step: 0.05, digits: 2 },
+    intensity: { default: 1, min: 0, max: 10, step: 0.05, digits: 2 },
+    range: { default: 20, min: 1, max: 100, step: 1, digits: 0 },
+    speed: { default: 0.2, min: 0, max: 5, step: 0.05, digits: 2 },
+};
+/** Existing scenes retain clear air until volumetric lighting is enabled. */
+export function defaultSceneVolumetricLighting() {
+    const specs = SCENE_VOLUMETRIC_LIGHTING_SPECS;
+    return {
+        enabled: false,
+        density: specs.density.default,
+        intensity: specs.intensity.default,
+        range: specs.range.default,
+        quality: 'medium',
+        speed: specs.speed.default,
+    };
+}
+/** Restore saved haze settings and clamp them to the shared editor bounds. */
+export function healSceneVolumetricLighting(raw) {
+    const d = defaultSceneVolumetricLighting();
+    if (!isRecord(raw))
+        return d;
+    const specs = SCENE_VOLUMETRIC_LIGHTING_SPECS;
+    return {
+        enabled: typeof raw.enabled === 'boolean' ? raw.enabled : d.enabled,
+        density: clamp(finiteOr(raw.density, d.density), specs.density.min, specs.density.max),
+        intensity: clamp(finiteOr(raw.intensity, d.intensity), specs.intensity.min, specs.intensity.max),
+        range: clamp(finiteOr(raw.range, d.range), specs.range.min, specs.range.max),
+        quality: isOneOf(raw.quality, EFFECTS_QUALITY_LEVELS) ? raw.quality : d.quality,
+        speed: clamp(finiteOr(raw.speed, d.speed), specs.speed.min, specs.speed.max),
+    };
+}
+/** Merge `patch` into `target` in place; haze leaves land in the settings object `target` already holds. */
+export function mergeEnvironmentPatch(target, { volumetricLighting, ...fields }) {
+    Object.assign(target, fields);
+    if (volumetricLighting)
+        target.volumetricLighting = Object.assign(target.volumetricLighting ?? {}, volumetricLighting);
+}

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

@@ -330,7 +330,8 @@ export interface SceneCamera {
  * the clip: applying a pose leaves whatever camera motion the scene has running.
  */
 export type CameraPose = Pick<SceneCamera, 'orbit' | 'fov' | 'roll' | 'projection'>;
-export type SceneLightType = 'directional' | 'point' | 'ambient';
+export declare const SCENE_LIGHT_TYPES: readonly ["directional", "point", "ambient", "area", "spot"];
+export type SceneLightType = (typeof SCENE_LIGHT_TYPES)[number];
 /**
  * Per-light shadow tier. `off` is the old `castShadow: false`; the rest raise
  * shadow-map resolution. A point light pays 6 cube faces for the same tier a
@@ -338,17 +339,46 @@ export type SceneLightType = 'directional' | 'point' | 'ambient';
  */
 export declare const SHADOW_QUALITY_LEVELS: readonly ["off", "low", "medium", "high", "ultra"];
 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
  * coverage, not their parallel shading), point lights use x/y/z + range,
- * ambient uses none — all fields stay so a type switch keeps them.
+ * spot adds azimuth/elevation, angle and penumbra to point's fields;
+ * area uses x/y/z, azimuth/elevation/roll and width/height; ambient uses none.
+ * All fields stay so a type switch keeps them. Area lights affect PBR and MToon materials.
  */
 export interface SceneLight {
     id: string;
     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;
@@ -357,10 +387,23 @@ export interface SceneLight {
     y: number;
     z: number;
     range: number;
-    /** Ambient light is directionless, so it never casts whatever this says. */
+    /** Spot cone half-angle in degrees, 1–89; omitted values default to 30. */
+    angle?: number;
+    /** Spot cone edge softness, 0–1; omitted values default to 0.3. */
+    penumbra?: number;
+    /** Rectangular area light dimensions in metres; omitted values default to 1. */
+    width?: number;
+    height?: number;
+    /** Area light rotation in its rectangle's plane, in degrees; defaults to 0. */
+    roll?: number;
+    /** Ambient and area lights never cast shadows. */
     shadowQuality: ShadowQuality;
-    /** Penumbra width in shadow-map texels — a stylistic dial; the filter widens the edge uniformly. */
+    /** PCF disk radius in shadow-map texels; retained while PCSS is selected. */
     shadowRadius: number;
+    /** Per-light filter; defaults to PCF. Gate editing on the `shadow-filters` app capability. */
+    shadowFilter?: ShadowFilter;
+    /** PCSS source diameter: degrees for directional lights, metres for point/spot; 0–10, default 0.1. */
+    shadowSourceSize?: number;
 }
 /** Distance haze. Only geometry fogs — empty space keeps the window's transparency. */
 export interface SceneFog {
@@ -369,6 +412,16 @@ export interface SceneFog {
     /** Exponential-squared falloff; the useful band is well under 1 at avatar scale. */
     density: number;
 }
+/** Illuminated haze in the 3D stage; rendered only by perspective cameras. */
+export interface SceneVolumetricLighting {
+    enabled: boolean;
+    density: number;
+    intensity: number;
+    /** Distance from the camera in scene units. */
+    range: number;
+    quality: EffectsQuality;
+    speed: number;
+}
 /** Display transform applied after the scene renders. `none` keeps colors exactly as authored. */
 export type SceneToneMapping = 'none' | 'neutral' | 'aces' | 'agx';
 /** Highlight glow in normal, streak, or star mode; color selection applies only to layer effects. */
@@ -812,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. */
@@ -828,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. */
@@ -849,6 +906,10 @@ export interface SceneEnvironment {
     /** The set's suggested look, captured when the model was picked; null when it carries none. */
     modelLook: EnvironmentLook | null;
     fog: SceneFog;
+    /** Omitted by hosts without volumetric lighting support. */
+    volumetricLighting?: SceneVolumetricLighting;
+    /** Optimize unshadowed point lights on supported renderers; omitted by older hosts. */
+    clusteredLighting?: boolean;
     effects: SceneEffects;
     /**
      * Built-in effects added as layers, in registry order — one keeps its row and tuning while
@@ -908,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"];
+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

@@ -18,12 +18,14 @@ export function isAssetKind(v) {
 }
 // ---- Objects -------------------------------------------------------------------
 export const OBJECT_SPACES = ['2d', '3d'];
+export const SCENE_LIGHT_TYPES = ['directional', 'point', 'ambient', 'area', 'spot'];
 /**
  * Per-light shadow tier. `off` is the old `castShadow: false`; the rest raise
  * shadow-map resolution. A point light pays 6 cube faces for the same tier a
  * directional light covers with one map, so it gets the smaller of the pair.
  */
 export const SHADOW_QUALITY_LEVELS = ['off', 'low', 'medium', 'high', 'ultra'];
+export const SHADOW_FILTERS = ['pcf', 'pcss'];
 // ---- Runtime state -------------------------------------------------------------
 /**
  * App-level features a client gates on (never version-sniff): `hello` and
@@ -38,6 +40,11 @@ export const APP_CAPABILITIES = [
     'asset-inspection',
     'layer-effects',
     '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.8.1",
+  "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",