@laplace.live/persona-sdk 0.10.0 → 0.12.0

package/dist/values/effect-schema.d.ts

@@ -1,4 +1,4 @@
-import type { SceneEffects } from '../wire/types.ts';
+import type { SceneEffects, ToggleEffectKey } from '../wire/types.ts';
 /** Slider + healing metadata for one numeric effect parameter. */
 export interface EffectParamSpec {
     default: number;
@@ -14,12 +14,6 @@ export interface EffectParamSpec {
 export interface EffectColorSpec {
     default: string;
 }
-/** Keys of {@link SceneEffects} that follow the `{ enabled } + params` pattern. */
-export type ToggleEffectKey = {
-    [K in keyof SceneEffects]: SceneEffects[K] extends {
-        enabled: boolean;
-    } ? K : never;
-}[keyof SceneEffects];
 export declare const EFFECT_SPECS: Record<ToggleEffectKey, Readonly<Record<string, EffectParamSpec>>>;
 /**
  * Hex-color params, keyed like {@link EFFECT_SPECS} — generic walkers (healing,
@@ -36,5 +30,12 @@ export declare const TOGGLE_EFFECT_KEYS: readonly ToggleEffectKey[];
 export declare const SCENE_SPACE_EFFECT_KEYS: readonly ToggleEffectKey[];
 /** Registry effects the post chain composes — {@link TOGGLE_EFFECT_KEYS} minus the scene-space ones. */
 export declare const POST_EFFECT_KEYS: readonly ToggleEffectKey[];
+/** The canonical `effectLayers`: registry order, junk dropped, every switched-on effect included. */
+export declare function effectLayerKeys(listed: readonly unknown[], effects: Pick<SceneEffects, ToggleEffectKey>): ToggleEffectKey[];
+/**
+ * Composition order, bottom to top, with user-authored effects as one `'custom'` group.
+ * Display-only: the desktop chain's `rebuild()` is the order that runs — a stage moved there moves here too.
+ */
+export declare const EFFECT_STACK_ORDER: readonly (ToggleEffectKey | 'custom')[];
 /** Every registry effect at its defaults — the derived half of a fresh {@link SceneEffects}. */
 export declare function defaultToggleEffects(): Pick<SceneEffects, ToggleEffectKey>;

package/dist/values/effect-schema.js

@@ -177,6 +177,32 @@ export const TOGGLE_EFFECT_KEYS = Object.keys(EFFECT_SPECS);
 export const SCENE_SPACE_EFFECT_KEYS = ['rain', 'snow'];
 /** Registry effects the post chain composes — {@link TOGGLE_EFFECT_KEYS} minus the scene-space ones. */
 export const POST_EFFECT_KEYS = TOGGLE_EFFECT_KEYS.filter(key => !SCENE_SPACE_EFFECT_KEYS.includes(key));
+/** The canonical `effectLayers`: registry order, junk dropped, every switched-on effect included. */
+export function effectLayerKeys(listed, effects) {
+    return TOGGLE_EFFECT_KEYS.filter(key => listed.includes(key) || effects[key].enabled);
+}
+/**
+ * Composition order, bottom to top, with user-authored effects as one `'custom'` group.
+ * Display-only: the desktop chain's `rebuild()` is the order that runs — a stage moved there moves here too.
+ */
+export const EFFECT_STACK_ORDER = [
+    'rain',
+    'snow',
+    'dof',
+    'rim',
+    'outline',
+    'dropShadow',
+    'chromaticAberration',
+    'bloom',
+    'diffusion',
+    'color',
+    'pixelate',
+    'glitch',
+    'droplets',
+    'custom',
+    'grain',
+    'vignette',
+];
 /** Every registry effect at its defaults — the derived half of a fresh {@link SceneEffects}. */
 export function defaultToggleEffects() {
     const out = {};

package/dist/values/limits.d.ts

@@ -52,6 +52,8 @@ export declare const PLACE_3D_SCALE_MIN = 0.01;
 export declare const PLACE_3D_SCALE_MAX = 100;
 /** 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). */
+export declare function contentAssetId(content: ObjectContent): string | null;
 /**
  * The one model format a space's objects can ride: the renderers never mix, and
  * the three canvas always composites over the Pixi one, so a cross-space pin
@@ -61,6 +63,8 @@ export declare function attachableParentFormat(space: ObjectSpace): ModelFormat;
 export declare const DEFAULT_HEAD_ANGLE: NonNullable<Attach['headAngle']>;
 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. */
+export declare const ATTACH_PARALLAX_MAX = 300;
 export declare const ATTACH_SMOOTHING_MAX = 50;
 export declare const DEFAULT_ELASTICITY: NonNullable<Attach['elasticity']>;
 export declare const ELASTICITY_STIFFNESS_MAX = 100;

package/dist/values/limits.js

@@ -90,6 +90,10 @@ export const PLACE_3D_SCALE_MAX = 100;
 export function objectSupportsSpace(kind, space) {
     return kind === 'prop' ? space === '3d' : true;
 }
+/** The asset an object streams from, or null for kinds that carry their source inline (web, capture). */
+export function contentAssetId(content) {
+    return content.kind === 'image' || content.kind === 'video' || content.kind === 'prop' ? content.assetId : null;
+}
 /**
  * The one model format a space's objects can ride: the renderers never mix, and
  * the three canvas always composites over the Pixi one, so a cross-space pin
@@ -98,9 +102,16 @@ export function objectSupportsSpace(kind, space) {
 export function attachableParentFormat(space) {
     return space === '2d' ? 'live2d' : 'vrm';
 }
-export const DEFAULT_HEAD_ANGLE = { multiplier: 1, smoothing: 15 };
+export const DEFAULT_HEAD_ANGLE = {
+    multiplier: 1,
+    parallaxX: 0,
+    parallaxY: 0,
+    smoothing: 15,
+};
 export const ATTACH_MULTIPLIER_MIN = -2;
 export const ATTACH_MULTIPLIER_MAX = 2;
+/** Parallax slider ceiling, symmetric: stage px at a full head turn. */
+export const ATTACH_PARALLAX_MAX = 300;
 export const ATTACH_SMOOTHING_MAX = 50;
 // Warudo Attachable defaults and slider ceilings, verbatim.
 export const DEFAULT_ELASTICITY = { stiffness: 2, damping: 3, maxSpeed: 2 };

package/dist/wire/methods.d.ts

@@ -1,5 +1,5 @@
 import type { EventName } from './events.ts';
-import type { AnchorOption, AppCapability, AssetKind, AssetRef, Attach, Expression, ExpressionPersistence, HotkeyConfig, HotkeyState, InjectEntry, InjectTarget, InstanceRuntime, JsonValue, 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, Expression, ExpressionPersistence, HotkeyConfig, HotkeyState, InjectEntry, InjectTarget, InstanceRuntime, JsonValue, 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';
 /** 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. */
@@ -149,10 +149,14 @@ export interface ObjectSetPlacementRequest {
     place3d?: Partial<Place3D>;
 }
 export type ObjectSetPlacementResponse = EmptyResponse;
+/** {@link Attach} as `object.attach` accepts it: head-angle fields may be omitted and heal to their defaults. */
+export type AttachInput = Omit<Attach, 'headAngle'> & {
+    headAngle: Partial<AttachHeadAngle> | null;
+};
 export interface ObjectAttachRequest {
     instanceId: string;
     /** Null detaches. */
-    attach: Attach | null;
+    attach: AttachInput | null;
 }
 export type ObjectAttachResponse = EmptyResponse;
 export interface ObjectSetLightOverridesRequest {

package/dist/wire/types.d.ts

@@ -2,9 +2,15 @@ export type ModelFormat = 'live2d' | 'vrm';
 /** Where an item came from: shipped with the app, or added by the user. */
 export type ContentOrigin = 'bundled' | 'user';
 /** How a registered file is labelled. Wider than an object's content kinds: `.hdr` is only ever an environment map. */
-export type AssetKind = 'image' | 'video' | 'prop' | 'ibl' | 'lut' | 'animation';
-/** Every content kind the Inventory can list. `pngtuber` is schema-ready before any producer exists. */
-export type InventoryKind = ModelFormat | 'pngtuber' | AssetKind;
+export declare const ASSET_KINDS: readonly ["image", "video", "prop", "ibl", "lut", "animation"];
+export type AssetKind = (typeof ASSET_KINDS)[number];
+/** Narrow a kind string to the set the asset registry owns — models and effects have their own. */
+export declare function isAssetKind(v: unknown): v is AssetKind;
+/**
+ * Every content kind the Inventory can list. `pngtuber` is schema-ready before any
+ * producer exists; `effect` rows are post-processing effects (built-in or installed), not files.
+ */
+export type InventoryKind = ModelFormat | 'pngtuber' | AssetKind | 'effect';
 /**
  * What every registry entry carries, model or asset alike. `kind` is always *what
  * the thing is* and `origin` always *where it came from* — the two were once
@@ -171,9 +177,12 @@ export type AttachAnchor = {
     verts: [number, number, number];
     weights: [number, number, number];
 };
-/** Live2D only: smoothed ParamAngleZ × multiplier turns the pinned item (X/Y ride the mesh). */
+/** Live2D only: ParamAngleZ × multiplier turns the pinned item; ParamAngleX/Y × parallax shift it (smoothed). */
 export interface AttachHeadAngle {
     multiplier: number;
+    /** Stage px at a full head turn (model at scale 1); positive = in front of the mesh, negative = behind. */
+    parallaxX: number;
+    parallaxY: number;
     /** VTS-style 0..50; ~frames of lag at 60 fps (0 = instant). */
     smoothing: number;
 }
@@ -247,7 +256,7 @@ export type SceneLightType = 'directional' | 'point' | 'ambient';
  * 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 declare const SHADOW_QUALITY_LEVELS: readonly ["off", "low", "medium", "high", "extra"];
+export declare const SHADOW_QUALITY_LEVELS: readonly ["off", "low", "medium", "high", "ultra"];
 export type ShadowQuality = (typeof SHADOW_QUALITY_LEVELS)[number];
 /**
  * One scene light. Angles are degrees. Directional lights aim with
@@ -539,6 +548,12 @@ export interface SceneEffects {
     rain: SceneRain;
     snow: SceneSnow;
 }
+/** Keys of {@link SceneEffects} that follow the `{ enabled } + params` pattern. */
+export type ToggleEffectKey = {
+    [K in keyof SceneEffects]: SceneEffects[K] extends {
+        enabled: boolean;
+    } ? K : never;
+}[keyof SceneEffects];
 /**
  * One user-authored effect's placement in a scene. Deliberately a sibling of
  * {@link SceneEffects} rather than a key inside it: `ToggleEffectKey` is derived
@@ -568,6 +583,11 @@ export interface SceneEnvironment {
     showSkybox: boolean;
     fog: SceneFog;
     effects: SceneEffects;
+    /**
+     * Built-in effects added as layers, in registry order — one keeps its row and tuning while
+     * switched off. Healing lists every switched-on effect, so a patch that switches one on adds its layer.
+     */
+    effectLayers: ToggleEffectKey[];
     /**
      * User-authored effects, in the order they compose. They run as a group at one
      * fixed point in the post chain — after grading and the screen-space warps,

package/dist/wire/types.js

@@ -1,12 +1,18 @@
 // The API's data model: the entity shapes that requests, responses, and events
 // carry. Structural mirrors of the app's scene/settings models, minus anything
 // filesystem-shaped — model refs are sanitized to ids, never directories.
+/** How a registered file is labelled. Wider than an object's content kinds: `.hdr` is only ever an environment map. */
+export const ASSET_KINDS = ['image', 'video', 'prop', 'ibl', 'lut', 'animation'];
+/** Narrow a kind string to the set the asset registry owns — models and effects have their own. */
+export function isAssetKind(v) {
+    return typeof v === 'string' && ASSET_KINDS.includes(v);
+}
 /**
  * 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', 'extra'];
+export const SHADOW_QUALITY_LEVELS = ['off', 'low', 'medium', 'high', 'ultra'];
 // ---- Runtime state -------------------------------------------------------------
 /**
  * App-level features a client gates on (never version-sniff): `hello` and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@laplace.live/persona-sdk",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "TypeScript SDK and wire schema for the LAPLACE Persona plugin API",
   "license": "MIT",
   "type": "module",