@laplace.live/persona-sdk 0.9.0 → 0.11.0

package/dist/client/client.js

@@ -89,6 +89,9 @@ export class PersonaClient {
         this.settleConnect?.(new Error('client closed'));
         const ws = this.ws;
         this.ws = null;
+        // Synchronously, not in the attempt's `.finally` a microtask later: a connect()
+        // in this same tick must dial instead of joining the attempt just settled.
+        this.connectPromise = null;
         ws?.close();
         this.setState('closed');
     }

package/dist/effects.d.ts

@@ -0,0 +1,79 @@
+import type * as TSL from 'three/tsl';
+import type { Color, Node, Vector2, Vector3, Vector4 } from 'three/webgpu';
+export * from './values/custom-effect.ts';
+/** A vec4-typed TSL node with its swizzles — what `sample` returns and `build` composes over. */
+export type CustomEffectVec4 = ReturnType<typeof TSL.nodeObject<Node<'vec4'>>>;
+/** A float-typed TSL node with its operators — what `viewZ` returns. */
+export type CustomEffectFloat = ReturnType<typeof TSL.nodeObject<Node<'float'>>>;
+/** A vec3-typed TSL node with its swizzles — what the camera probes return. */
+export type CustomEffectVec3 = ReturnType<typeof TSL.nodeObject<Node<'vec3'>>>;
+/** What an author's module receives. Not a security boundary — just the useful surface. */
+export interface CustomEffectApi {
+    /** The whole `three/tsl` namespace: `vec4`, `uv`, `uniform`, `mix`, `Fn`, … */
+    tsl: typeof TSL;
+    three: {
+        Color: typeof Color;
+        Vector2: typeof Vector2;
+        Vector3: typeof Vector3;
+        Vector4: typeof Vector4;
+    };
+    /**
+     * Stock three display nodes an effect cannot build for itself. `afterImage`
+     * is the seam for anything temporal: correct frame feedback needs two render
+     * targets ping-ponged plus a renderer reference, and `build()` hands authors
+     * neither. Upstream types return the bare class, hiding the TSL swizzles the
+     * runtime proxy carries; this signature types the echo as what authors use it
+     * as — a sampleable vec4 image.
+     */
+    nodes: {
+        afterImage: (node: Node, damp?: Node | number) => CustomEffectVec4;
+    };
+}
+/** Build-time context for one custom effect. */
+export interface CustomEffectBuildContext {
+    /** Sample the incoming frame at any UV — the seam that makes warps and blurs possible. */
+    sample: (at: unknown) => CustomEffectVec4;
+    /** Screen UV of the pixel being shaded. */
+    uv: typeof TSL.uv;
+    /**
+     * View-space Z of the 3D scene at this pixel — three's convention: 0 at the
+     * camera, more negative with distance, the far plane where nothing was drawn.
+     * The Live2D layer and 2D objects contribute no depth. Costs one depth read,
+     * and only if called.
+     */
+    viewZ: () => CustomEffectFloat;
+    /**
+     * Normalized world-space direction of the scene camera's view ray through
+     * this pixel, fov and aspect folded in. Inside the post pass TSL's own
+     * `cameraPosition`/`cameraWorldMatrix` describe the fullscreen quad's
+     * camera — this is the real one. Anchor a field here instead of `uv()` and
+     * it holds still in the world while the camera orbits.
+     */
+    worldRay: () => CustomEffectVec3;
+    /** The scene camera's world position in metres, as a per-frame uniform. */
+    cameraPosition: () => CustomEffectVec3;
+    /** Hand a build-time disposable (a blur render target) to the chain's transient list. */
+    track: (t: {
+        dispose?: () => void;
+    }) => void;
+}
+/** What an author's module returns. Everything but `build` is optional. */
+export interface CustomEffectModule {
+    /** Uniform nodes keyed by manifest param name; param edits write straight into `.value`. */
+    uniforms?: Record<string, {
+        value: unknown;
+    }>;
+    /** Compose the effect over `input` — the frame so far, already sampleable — and return the result node. */
+    build: (input: Node, ctx: CustomEffectBuildContext) => Node;
+    /** Per-frame CPU state. `dt` and `elapsed` are seconds. */
+    update?: (dt: number, elapsed: number) => void;
+    dispose?: () => void;
+}
+/** The module's default export. Runs once per load — mint uniforms here so they survive rebuilds. */
+export type CustomEffectFactory = (api: CustomEffectApi) => CustomEffectModule;
+/** Why an effect is not rendering, for the panel's error row. */
+export interface CustomEffectFault {
+    slug: string;
+    phase: 'load' | 'build' | 'update';
+    message: string;
+}

package/dist/effects.js

@@ -0,0 +1,6 @@
+// The custom-effect authoring contract: what an effect module receives, what it
+// returns, and (re-exported) the manifest shape naming its params. Everything
+// touching three is type-only — the desktop hands the runtime to the module's
+// factory, because a module loaded from `persona://` can import nothing.
+// Typechecking against this entry needs `@types/three` (optional peer).
+export * from "./values/custom-effect.js";

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export * from './client/address.ts';
 export * from './client/client.ts';
+export * from './values/custom-effect.ts';
 export * from './values/effect-schema.ts';
 export * from './values/guards.ts';
 export * from './values/labels.ts';

package/dist/index.js

@@ -2,6 +2,7 @@
 // and the values/registries every Persona app must agree on.
 export * from "./client/address.js";
 export * from "./client/client.js";
+export * from "./values/custom-effect.js";
 export * from "./values/effect-schema.js";
 export * from "./values/guards.js";
 export * from "./values/labels.js";

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

@@ -0,0 +1,44 @@
+/** How wide a manifest may open a slider; keeps a typo'd range from making one unusable. */
+export declare const CUSTOM_EFFECT_PARAM_LIMIT = 1000000;
+/** Enabled custom effects one scene may compose — each costs a full-frame RTT. Disabled entries are uncapped. */
+export declare const CUSTOM_EFFECTS_MAX = 8;
+/** Params per effect. Past this the panel section stops being navigable. */
+export declare const CUSTOM_EFFECT_PARAM_MAX = 32;
+export type CustomEffectParamKind = 'number' | 'boolean' | 'color';
+/** One author-declared control. `kind` picks the panel widget and the healing rule. */
+export interface CustomEffectParam {
+    kind: CustomEffectParamKind;
+    /** Slider/field label. Author-supplied, so never translated. */
+    label: string;
+    /** Numbers: the clamp range and readout. Booleans and colors ignore these. */
+    default: number | boolean | string;
+    min?: number;
+    max?: number;
+    step?: number;
+    digits?: number;
+    unit?: string;
+}
+/** A validated `manifest.json`. */
+export interface CustomEffectManifest {
+    name: string;
+    /** Author-declared, shown in the panel's detail row. */
+    version?: string;
+    author?: string;
+    description?: string;
+    params: Record<string, CustomEffectParam>;
+}
+export declare function isCustomEffectSlug(v: unknown): v is string;
+/**
+ * Validate a parsed `manifest.json`. Null when it carries no usable name —
+ * everything else degrades (a bad param is dropped, not fatal), because a
+ * half-typed manifest should still show the author what already works.
+ */
+export declare function parseCustomEffectManifest(raw: unknown): CustomEffectManifest | null;
+/** Every declared param at its default — the params half of a fresh scene entry. */
+export declare function defaultCustomEffectParams(manifest: CustomEffectManifest): Record<string, number | boolean | string>;
+/**
+ * Clamp saved params to the manifest that is installed now. Unknown keys are
+ * kept: an author mid-edit who renames a param back should not find the value
+ * gone, and a param costs nothing until the module reads it.
+ */
+export declare function healCustomEffectParams(raw: unknown, manifest: CustomEffectManifest | null): Record<string, number | boolean | string>;

package/dist/values/custom-effect.js

@@ -0,0 +1,136 @@
+// User-authored effects: the manifest contract and its validator.
+//
+// An effect folder holds `manifest.json` (plain data — this file's shape) and
+// `effect.js` (a TSL builder the stage worker evaluates). The split is what lets
+// main heal a scene's saved params without ever running author code: only the
+// worker imports the module, and it is the sole place third-party JS runs.
+//
+// Params mirror EffectParamSpec so the panel renders both kinds of effect with
+// the same sliders — but these arrive at runtime from disk, so everything here
+// validates rather than trusting the type.
+import { finiteOr, isFiniteNumber, isRecord, nonEmptyString } from "./guards.js";
+import { hexColorOr } from "./limits.js";
+/** How wide a manifest may open a slider; keeps a typo'd range from making one unusable. */
+export const CUSTOM_EFFECT_PARAM_LIMIT = 1e6;
+/** Enabled custom effects one scene may compose — each costs a full-frame RTT. Disabled entries are uncapped. */
+export const CUSTOM_EFFECTS_MAX = 8;
+/** Params per effect. Past this the panel section stops being navigable. */
+export const CUSTOM_EFFECT_PARAM_MAX = 32;
+/** Folder-name rule: lowercase, dash-separated. Also the on-disk path segment, so no dots or slashes. */
+const SLUG_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
+export function isCustomEffectSlug(v) {
+    return typeof v === 'string' && SLUG_RE.test(v);
+}
+function bounded(v) {
+    return Math.min(CUSTOM_EFFECT_PARAM_LIMIT, Math.max(-CUSTOM_EFFECT_PARAM_LIMIT, v));
+}
+function parseParam(raw) {
+    if (!isRecord(raw))
+        return null;
+    const label = nonEmptyString(raw.label);
+    if (label === null)
+        return null;
+    if (raw.kind === 'boolean')
+        return { kind: 'boolean', label, default: raw.default === true };
+    if (raw.kind === 'color')
+        return { kind: 'color', label, default: hexColorOr(raw.default, '#ffffff') };
+    // Numbers are the default kind: an omitted or unknown `kind` is far more often
+    // a slider the author forgot to tag than a control they meant to drop.
+    // Both ends clamp into ±LIMIT before ordering, or a range wholly past the
+    // limit would keep one end beyond it.
+    const lo = bounded(finiteOr(raw.min, 0));
+    const hi = bounded(finiteOr(raw.max, 1));
+    // An inverted or empty range would leave a slider that cannot move; widen to the default's own value.
+    const min = Math.min(lo, hi);
+    const max = Math.max(lo, hi);
+    const def = Math.min(max, Math.max(min, finiteOr(raw.default, min)));
+    const step = Math.min(max - min || 1, Math.abs(finiteOr(raw.step, 0.01)) || 0.01);
+    return {
+        kind: 'number',
+        label,
+        default: def,
+        min,
+        max,
+        step,
+        ...(isFiniteNumber(raw.digits) && { digits: Math.min(6, Math.max(0, Math.trunc(raw.digits))) }),
+        ...(typeof raw.unit === 'string' && raw.unit !== '' && { unit: raw.unit.slice(0, 8) }),
+    };
+}
+/**
+ * Validate a parsed `manifest.json`. Null when it carries no usable name —
+ * everything else degrades (a bad param is dropped, not fatal), because a
+ * half-typed manifest should still show the author what already works.
+ */
+export function parseCustomEffectManifest(raw) {
+    if (!isRecord(raw))
+        return null;
+    const name = nonEmptyString(raw.name);
+    if (name === null)
+        return null;
+    const params = {};
+    if (isRecord(raw.params)) {
+        for (const [key, value] of Object.entries(raw.params)) {
+            if (Object.keys(params).length >= CUSTOM_EFFECT_PARAM_MAX)
+                break;
+            // The key is a JS identifier on the uniforms object the module builds; a
+            // key it cannot name would silently never receive its value.
+            if (!/^[A-Za-z_$][\w$]*$/.test(key))
+                continue;
+            const param = parseParam(value);
+            if (param)
+                params[key] = param;
+        }
+    }
+    return {
+        name: name.slice(0, 64),
+        params,
+        ...(typeof raw.version === 'string' && raw.version !== '' && { version: raw.version.slice(0, 32) }),
+        ...(typeof raw.author === 'string' && raw.author !== '' && { author: raw.author.slice(0, 64) }),
+        ...(typeof raw.description === 'string' &&
+            raw.description !== '' && { description: raw.description.slice(0, 280) }),
+    };
+}
+/** Every declared param at its default — the params half of a fresh scene entry. */
+export function defaultCustomEffectParams(manifest) {
+    const out = {};
+    for (const [key, param] of Object.entries(manifest.params))
+        out[key] = param.default;
+    return out;
+}
+/** A primitive a saved param may hold; non-finite numbers are junk, not tuning. */
+function isParamValue(v) {
+    return isFiniteNumber(v) || typeof v === 'boolean' || typeof v === 'string';
+}
+/**
+ * Clamp saved params to the manifest that is installed now. Unknown keys are
+ * kept: an author mid-edit who renames a param back should not find the value
+ * gone, and a param costs nothing until the module reads it.
+ */
+export function healCustomEffectParams(raw, manifest) {
+    const src = isRecord(raw) ? raw : {};
+    const out = {};
+    for (const [key, value] of Object.entries(src)) {
+        const spec = manifest?.params[key];
+        if (!spec) {
+            // No spec to clamp against — an unknown key, or no manifest at all (effect
+            // not installed on this machine); keeping primitives is what lets a
+            // reinstall restore the user's tuning.
+            if (isParamValue(value))
+                out[key] = value;
+            continue;
+        }
+        if (spec.kind === 'boolean')
+            out[key] = typeof value === 'boolean' ? value : spec.default === true;
+        else if (spec.kind === 'color')
+            out[key] = hexColorOr(value, String(spec.default));
+        else {
+            const lo = spec.min ?? 0;
+            const hi = spec.max ?? 1;
+            out[key] = Math.min(hi, Math.max(lo, finiteOr(value, Number(spec.default))));
+        }
+    }
+    if (manifest)
+        for (const [key, spec] of Object.entries(manifest.params))
+            out[key] ??= spec.default;
+    return out;
+}

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;
@@ -10,13 +10,17 @@ export interface EffectParamSpec {
     /** Appended to the readout (`s`, `px`, …). */
     unit?: string;
 }
-/** Keys of {@link SceneEffects} that follow the `{ enabled } + numeric params` pattern. */
-export type ToggleEffectKey = {
-    [K in keyof SceneEffects]: SceneEffects[K] extends {
-        enabled: boolean;
-    } ? K : never;
-}[keyof SceneEffects];
+/** Healing metadata for one hex-color effect parameter (validated, not clamped). */
+export interface EffectColorSpec {
+    default: string;
+}
 export declare const EFFECT_SPECS: Record<ToggleEffectKey, Readonly<Record<string, EffectParamSpec>>>;
+/**
+ * Hex-color params, keyed like {@link EFFECT_SPECS} — generic walkers (healing,
+ * defaults, hotkey snapshots, the panel) visit both tables. Only effects with a
+ * string param appear.
+ */
+export declare const EFFECT_COLOR_SPECS: Partial<Record<ToggleEffectKey, Readonly<Record<string, EffectColorSpec>>>>;
 export declare const TOGGLE_EFFECT_KEYS: readonly ToggleEffectKey[];
 /**
  * Registry effects that render as scene geometry inside the scene pass rather
@@ -26,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

@@ -2,7 +2,8 @@
 // Defaults, healing clamps, active checks, structural keys, and the panel's
 // sliders are all derived from this table, so adding an effect is:
 //   1. Type its values in `SceneEffects` (types.ts) + its interface.
-//   2. Spec it here; label it in the panel's effect-labels.ts (parity-checked).
+//   2. Spec it here (hex-color params go in EFFECT_COLOR_SPECS); label it in
+//      the panel's effect-labels.ts (parity-checked).
 //   3. Implement its stage under apps/desktop/src/renderer/vrm/webgpu/effects/.
 //      Scene-space effects (geometry, not a post stage — e.g. snow) also join
 //      SCENE_SPACE_EFFECT_KEYS below.
@@ -27,14 +28,31 @@ export const EFFECT_SPECS = {
         // Threshold 0.8 catches highlights without hazing the whole avatar; radius is the lib default.
         threshold: { default: 0.8, min: 0, max: 1, step: 0.01 },
         radius: { default: 0.85, min: 0, max: 1, step: 0.01 },
+        // VTS bloom's anamorphic-flare half. Streak 0 keeps the passes out of the
+        // graph; the angle is VTS's horizontal/vertical toggle made continuous.
+        streak: { default: 0, min: 0, max: 3, step: 0.01 },
+        streakThreshold: { default: 0.8, min: 0, max: 1, step: 0.01 },
+        streakAngle: { default: 0, min: -90, max: 90, step: 1, unit: '°' },
+        darken: { default: 0, min: 0, max: 1, step: 0.01 },
+    },
+    // Shoost's diffusion (its Kino bloom variant, sliders Radius/Intensity/
+    // Contrast→threshold): screen-composited, so its Opacity slider folds into
+    // intensity. Threshold 0.35 mists the midtones up — the stock Pro-Mist read.
+    diffusion: {
+        intensity: { default: 1, min: 0, max: 2, step: 0.01 },
+        radius: { default: 0.85, min: 0, max: 1, step: 0.01 },
+        threshold: { default: 0.35, min: 0, max: 1, step: 0.01 },
     },
     dof: {
         bokehScale: { default: 2, min: 0, max: 8, step: 0.01 },
         /** World metres of acceptably-sharp depth around the focus plane. */
         focusRange: { default: 2, min: 0.1, max: 10, step: 0.01 },
     },
+    // VTube Studio's chromatic_aberration surface: strength + blur edges, the
+    // latter continuous like rim.bothSides (VTS fades the same shader uniform).
     chromaticAberration: {
         strength: { default: 0.2, min: 0, max: 1, step: 0.01 },
+        blurEdges: { default: 1, min: 0, max: 1, step: 0.01 },
     },
     grain: {
         strength: { default: 0.3, min: 0, max: 1, step: 0.01 },
@@ -43,6 +61,36 @@ export const EFFECT_SPECS = {
         darkness: { default: 0.5, min: 0, max: 1, step: 0.01 },
         offset: { default: 0.5, min: 0, max: 1, step: 0.01 },
     },
+    // Shoost's rim-light ranges where the control carried over (size, angle,
+    // opacity→intensity); the rest follows VTube Studio's backlight. New params
+    // default neutral (omni 0, limit 1, darken 0) so healed scenes keep their look.
+    rim: {
+        intensity: { default: 1, min: 0, max: 2, step: 0.01 },
+        omni: { default: 0, min: 0, max: 1, step: 0.01 },
+        size: { default: 16, min: 1, max: 64, step: 1, unit: 'px' },
+        softness: { default: 0.6, min: 0, max: 1, step: 0.01 },
+        angle: { default: 45, min: 0, max: 360, step: 1, unit: '°' },
+        bothSides: { default: 0.5, min: 0, max: 1, step: 0.01 },
+        brightnessLimit: { default: 1, min: 0, max: 1, step: 0.01 },
+        darken: { default: 0, min: 0, max: 1, step: 0.01 },
+    },
+    // VTube Studio's backlight outline block: stripe count/speed/curve ranges are
+    // VTS's; size is ours (px, like rim) instead of VTS's normalized 0..1.
+    outline: {
+        size: { default: 8, min: 1, max: 64, step: 1, unit: 'px' },
+        opacity: { default: 1, min: 0, max: 1, step: 0.01 },
+        stripes: { default: 0.5, min: 0, max: 1, step: 0.01 },
+        stripeMix: { default: 1, min: 0, max: 1, step: 0.01 },
+        stripeSpeed: { default: 0.2, min: -1, max: 1, step: 0.01 },
+        stripeCurve: { default: 0, min: 0, max: 1, step: 0.01 },
+    },
+    // VTube Studio's backlight shadow: an offset silhouette copy. VTS hides it at
+    // zero offset; ours defaults to a visible down-right cast so enabling shows it.
+    dropShadow: {
+        opacity: { default: 0.6, min: 0, max: 1, step: 0.01 },
+        offsetX: { default: 3, min: -20, max: 20, step: 0.5, digits: 1, unit: '%' },
+        offsetY: { default: 3, min: -20, max: 20, step: 0.5, digits: 1, unit: '%' },
+    },
     pixelate: {
         // Pixels per block; past ~64 the frame is a handful of tiles.
         granularity: { default: 8, min: 2, max: 64, step: 1 },
@@ -74,6 +122,17 @@ export const EFFECT_SPECS = {
         staticDrops: { default: 0.2, min: 0, max: 3, step: 0.1, digits: 1 },
         glints: { default: 0.6, min: 0, max: 1, step: 0.05 },
     },
+    // VTS's weather rain rebuilt in world space: velocity-aligned streaks that
+    // slant with wind and splash where they land. `amount` is the live instance count.
+    rain: {
+        amount: { default: 4000, min: 100, max: 10000, step: 100 },
+        speed: { default: 1, min: 0.2, max: 3, step: 0.1, digits: 1, unit: '×' },
+        wind: { default: 0, min: -6, max: 6, step: 0.1, digits: 1, unit: 'm/s' },
+        length: { default: 1, min: 0.2, max: 3, step: 0.05 },
+        size: { default: 1, min: 0.4, max: 3, step: 0.05 },
+        splash: { default: 0.7, min: 0, max: 1, step: 0.05 },
+        opacity: { default: 0.4, min: 0.05, max: 1, step: 0.05 },
+    },
     // three's webgpu_compute_particles_snow, rescaled to the stage's metre-scale
     // world. `amount` is the live instance count; buffers allocate the max once.
     snow: {
@@ -86,6 +145,28 @@ export const EFFECT_SPECS = {
         opacity: { default: 1, min: 0.1, max: 1, step: 0.05 },
     },
 };
+/**
+ * Hex-color params, keyed like {@link EFFECT_SPECS} — generic walkers (healing,
+ * defaults, hotkey snapshots, the panel) visit both tables. Only effects with a
+ * string param appear.
+ */
+export const EFFECT_COLOR_SPECS = {
+    bloom: {
+        tint: { default: '#ffffff' },
+        // Beautify's anamorphic-flare tint default — the classic lens-streak blue.
+        streakTint: { default: '#8080ff' },
+    },
+    rim: {
+        color: { default: '#ffffff' },
+    },
+    outline: {
+        color: { default: '#ffffff' },
+        stripeColor: { default: '#000000' },
+    },
+    dropShadow: {
+        color: { default: '#000000' },
+    },
+};
 // Object.keys widens to string[]; the annotation above pins the keys to exactly ToggleEffectKey.
 export const TOGGLE_EFFECT_KEYS = Object.keys(EFFECT_SPECS);
 /**
@@ -93,9 +174,35 @@ export const TOGGLE_EFFECT_KEYS = Object.keys(EFFECT_SPECS);
  * than composing into the post chain. A new scene-space effect must join this
  * list, or its toggle needlessly forces the post path on and rebuilds the graph.
  */
-export const SCENE_SPACE_EFFECT_KEYS = ['snow'];
+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 = {};
@@ -103,6 +210,8 @@ export function defaultToggleEffects() {
         const fx = { enabled: false };
         for (const [param, spec] of Object.entries(EFFECT_SPECS[key]))
             fx[param] = spec.default;
+        for (const [param, spec] of Object.entries(EFFECT_COLOR_SPECS[key] ?? {}))
+            fx[param] = spec.default;
         out[key] = fx;
     }
     // Runtime-built, invisible to TS; EFFECT_SPECS's satisfies check is what pins

package/dist/values/limits.d.ts

@@ -6,6 +6,8 @@ export declare const DEFAULT_LIVE2D_PLACEMENT: ScreenPlacement;
 export declare const DEFAULT_VRM_PLACEMENT: VrmPlacement;
 /** Scene colors heal to 6-digit hex. */
 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;

package/dist/values/limits.js

@@ -9,6 +9,10 @@ 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;
+/** 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;
+}
 /** Drop the alpha byte a picker's hex input can produce (`#rrggbbaa` → `#rrggbb`). */
 export function opaqueHex(hex) {
     return /^#[0-9a-f]{8}$/i.test(hex) ? hex.slice(0, 7) : hex;
@@ -64,7 +68,8 @@ export function defaultSceneLightOf(type) {
         id: crypto.randomUUID(),
         type,
         color: '#ffffff',
-        intensity: 1,
+        // 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,
         x: 0,

package/dist/wire/schemas.d.ts

@@ -29,7 +29,6 @@ export declare const SettingsPatchSchema: z.ZodObject<{
         trayVisible: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>>;
     performance: z.ZodOptional<z.ZodObject<{
-        backgroundRendering: z.ZodOptional<z.ZodBoolean>;
         showFps: z.ZodOptional<z.ZodBoolean>;
         fpsLimit: z.ZodOptional<z.ZodNumber>;
         selectionOutline: z.ZodOptional<z.ZodBoolean>;
@@ -139,7 +138,6 @@ export declare const requestSchemas: {
                 trayVisible: z.ZodOptional<z.ZodBoolean>;
             }, z.core.$strip>>;
             performance: z.ZodOptional<z.ZodObject<{
-                backgroundRendering: z.ZodOptional<z.ZodBoolean>;
                 showFps: z.ZodOptional<z.ZodBoolean>;
                 fpsLimit: z.ZodOptional<z.ZodNumber>;
                 selectionOutline: z.ZodOptional<z.ZodBoolean>;

package/dist/wire/schemas.js

@@ -22,7 +22,6 @@ export const SettingsPatchSchema = z.object({
     ui: z.object({ trayVisible: z.boolean().optional() }).optional(),
     performance: z
         .object({
-        backgroundRendering: z.boolean().optional(),
         showFps: z.boolean().optional(),
         fpsLimit: z.number().optional(),
         selectionOutline: z.boolean().optional(),

package/dist/wire/types.d.ts

@@ -3,8 +3,11 @@ export type ModelFormat = 'live2d' | 'vrm';
 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;
+/**
+ * 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
@@ -280,12 +283,42 @@ export interface SceneFog {
 }
 /** Display transform applied after the scene renders. `none` keeps colors exactly as authored. */
 export type SceneToneMapping = 'none' | 'neutral' | 'aces' | 'agx';
-/** Glow around bright pixels. `threshold` is the luminance floor; `radius` widens the halo. */
+/**
+ * Glow around bright pixels, with anamorphic streak flares on the side
+ * (VTube Studio's Beautify-based bloom). `threshold` is the luminance floor;
+ * `radius` widens the halo.
+ */
 export interface SceneBloom {
     enabled: boolean;
     intensity: number;
     threshold: number;
     radius: number;
+    /** Halo tint (hex); white is untinted. */
+    tint: string;
+    /** Anamorphic streak strength; 0 keeps the streak passes out of the graph. */
+    streak: number;
+    /** Luminance floor for the streak's own bright pass. */
+    streakThreshold: number;
+    /** Streak axis in degrees: 0 horizontal, ±90 vertical (VTS's vertical toggle, continuous). */
+    streakAngle: number;
+    /** Streak tint (hex); classic anamorphic flares are light blue. */
+    streakTint: string;
+    /** Darkens the avatar under the glow so highlights pop (VTS's model darken), 0..1. */
+    darken: number;
+}
+/**
+ * Cinematic soft-focus veil (Shoost's diffusion, a Kino bloom variant): the
+ * frame's own light blurred wide and screened back over itself, so highlights
+ * halo and nearby shadows lift without bloom's additive blowout.
+ */
+export interface SceneDiffusion {
+    enabled: boolean;
+    /** Veil strength; screen-composited, so 1 stays short of clipping. */
+    intensity: number;
+    /** Veil spread: 0 tight halos, 1 the widest wash. */
+    radius: number;
+    /** Luminance floor that feeds the veil: 0 mists the whole frame, higher keeps it to highlights. */
+    threshold: number;
 }
 /** Darkened frame corners. `offset` pushes the falloff outward. */
 export interface SceneVignette {
@@ -301,10 +334,13 @@ export interface SceneColorGrade {
     brightness: number;
     contrast: number;
 }
-/** RGB fringing toward frame edges. `strength` 0..1. */
+/** Lens fringing that grows toward frame edges (Unity PPv2's curve, the one VTube Studio wraps). */
 export interface SceneChromaticAberration {
     enabled: boolean;
+    /** Fringe displacement 0..1; 1 smears ~10% of the frame at the corners. */
     strength: number;
+    /** 0 = three crisp RGB ghosts, 1 = fully integrated spectral smear (VTS's "blur edges"). */
+    blurEdges: number;
 }
 /** Animated film grain. `strength` is blend opacity 0..1. */
 export interface SceneFilmGrain {
@@ -378,6 +414,89 @@ export interface SceneDroplets {
     /** Specular glint on drops where the frame is transparent, so rain reads over the desktop (0 to 1). */
     glints: number;
 }
+/**
+ * Screen-space rim light along the avatar silhouette (Shoost's layer rim light,
+ * VTube Studio's backlight): coverage edges facing `angle` catch the glow.
+ * Silhouette-driven — an opaque skybox leaves no edges to light.
+ */
+export interface SceneRim {
+    enabled: boolean;
+    /** Rim tint (hex). */
+    color: string;
+    /** Glow strength; past 1 overdrives into bloom territory. */
+    intensity: number;
+    /** Rim width in output pixels. */
+    size: number;
+    /** Edge falloff: 0 a crisp line, 1 a wide soft fade. */
+    softness: number;
+    /** Light direction in degrees, compass-style: 0 lights from above, 90 from the right. */
+    angle: number;
+    /** How much the edge opposite the light glows too (0 to 1). */
+    bothSides: number;
+    /** Uniform glow on every edge regardless of `angle` (VTS's main backlight strength), 0..1. */
+    omni: number;
+    /** Ceiling the glow lightens pixels toward: 1 screens to white, lower protects highlights. */
+    brightnessLimit: number;
+    /** Darkens the avatar under the glow for contrast (VTS's model darken), 0..1. */
+    darken: number;
+}
+/**
+ * Contour band hugging the avatar silhouette, with an optional animated stripe
+ * pattern scrolling through it (VTube Studio's backlight outline). Silhouette-
+ * driven like the rim light — it needs coverage edges to trace.
+ */
+export interface SceneOutline {
+    enabled: boolean;
+    /** Outline color (hex). */
+    color: string;
+    /** Stripe color (hex), painted over `color` where the stripe pattern lands. */
+    stripeColor: string;
+    /** Band thickness in output pixels. */
+    size: number;
+    /** Outline opacity 0..1. */
+    opacity: number;
+    /** Stripe density: 0 broad bands, 1 fine candy stripes. */
+    stripes: number;
+    /** Stripe visibility: 0 a solid outline, 1 full-strength stripes. */
+    stripeMix: number;
+    /** Stripe scroll speed; negative reverses the direction. */
+    stripeSpeed: number;
+    /** Bends the stripes into waves: 0 straight, 1 strongly curled. */
+    stripeCurve: number;
+}
+/**
+ * Hard-edged copy of the avatar silhouette cast behind it (VTube Studio's
+ * backlight shadow). Offsets are percent of the frame height.
+ */
+export interface SceneDropShadow {
+    enabled: boolean;
+    /** Shadow color (hex). */
+    color: string;
+    /** Shadow opacity 0..1. */
+    opacity: number;
+    /** Horizontal offset, percent of frame height; positive casts right. */
+    offsetX: number;
+    /** Vertical offset, percent of frame height; positive casts down. */
+    offsetY: number;
+}
+/** Compute-driven 3D rainfall: motion-blur streaks fall through the scene and splash on models, props, and the floor. */
+export interface SceneRain {
+    enabled: boolean;
+    /** How many drops are alive at once. */
+    amount: number;
+    /** Fall clock multiplier. */
+    speed: number;
+    /** Sideways drift in metres per second; slants the streaks. */
+    wind: number;
+    /** Streak length multiplier over the motion-blur baseline. */
+    length: number;
+    /** Streak width multiplier. */
+    size: number;
+    /** Impact splash strength; 0 recycles drops with no splash. */
+    splash: number;
+    /** Streak opacity. */
+    opacity: number;
+}
 /** Compute-driven snowfall in the 3D scene: flakes drift down, settle on models and props, then melt. */
 export interface SceneSnow {
     enabled: boolean;
@@ -407,17 +526,46 @@ export interface SceneEffects {
     /** Scene brightness multiplied in before the tone curve; 1 is neutral. Works in every mode, including `none`. */
     exposure: number;
     bloom: SceneBloom;
+    diffusion: SceneDiffusion;
     vignette: SceneVignette;
     color: SceneColorGrade;
     chromaticAberration: SceneChromaticAberration;
     grain: SceneFilmGrain;
     lut: SceneLut;
     dof: SceneDepthOfField;
+    rim: SceneRim;
+    outline: SceneOutline;
+    dropShadow: SceneDropShadow;
     pixelate: ScenePixelate;
     glitch: SceneGlitch;
     droplets: SceneDroplets;
+    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
+ * from that interface, and healing, defaults, hotkey snapshots and the panel all
+ * iterate it as a closed compile-time union. Runtime keys in there would erase
+ * that guarantee for the built-in effects too.
+ */
+export interface SceneCustomEffect {
+    /** Folder name under the config home's `effects/` dir — stable id and module location. */
+    slug: string;
+    enabled: boolean;
+    /**
+     * Author-declared values, keyed by the manifest's param names. Untyped by
+     * construction: the specs arrive from disk at runtime, so these are validated
+     * against the installed manifest rather than checked at compile time.
+     */
+    params: Record<string, number | boolean | string>;
+}
 /**
  * Image-based lighting for the 3D stage: an environment map, whether to show it
  * behind the scene, the scene-global fog, and post-processing.
@@ -429,6 +577,19 @@ 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,
+     * before grain and vignette — so the built-in composition order stays fixed.
+     * An entry whose effect is not installed here is kept, not dropped: it would
+     * cost the user their tuning on a machine that simply lacks the folder.
+     */
+    customEffects: SceneCustomEffect[];
 }
 export interface Scene {
     id: string;
@@ -606,7 +767,6 @@ export interface Settings {
         trayVisible: boolean;
     };
     performance: {
-        backgroundRendering: boolean;
         showFps: boolean;
         fpsLimit: number;
         selectionOutline: boolean;
@@ -633,7 +793,6 @@ export interface SettingsPatch {
         trayVisible?: boolean;
     };
     performance?: {
-        backgroundRendering?: boolean;
         showFps?: boolean;
         fpsLimit?: number;
         selectionOutline?: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@laplace.live/persona-sdk",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "TypeScript SDK and wire schema for the LAPLACE Persona plugin API",
   "license": "MIT",
   "type": "module",
@@ -16,6 +16,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./effects": {
+      "types": "./dist/effects.d.ts",
+      "import": "./dist/effects.js"
     }
   },
   "files": [
@@ -26,10 +30,20 @@
     "provenance": true
   },
   "devDependencies": {
+    "@types/three": "^0.185.4",
     "rimraf": "^6.1.3",
+    "three": "0.185.1",
     "typescript": "~6.0.3",
     "vitest": "^4.1.11"
   },
+  "peerDependencies": {
+    "@types/three": "^0.185.0"
+  },
+  "peerDependenciesMeta": {
+    "@types/three": {
+      "optional": true
+    }
+  },
   "engines": {
     "node": ">=22"
   },