@laplace.live/persona-sdk 0.18.1 → 1.0.0

package/README.md

@@ -4,7 +4,7 @@ TypeScript SDK and wire schema for the [LAPLACE Persona](https://github.com/lapl
 plugin API — a token-authenticated WebSocket API for driving the avatar, scenes, expressions,
 motions, hotkeys, and tracking parameters from outside the app.
 
-Isomorphic: runs in Node ≥22, Bun, browsers, and OBS browser sources on the global `WebSocket`.
+Isomorphic: runs in Node ≥24, Bun, browsers, and OBS browser sources on the global `WebSocket`.
 One runtime dependency ([`zod`](https://zod.dev), backing the wire schemas).
 
 ## Setup

package/dist/client/client.d.ts

@@ -5,7 +5,7 @@ import type { InjectTarget } from '../wire/types.ts';
 export type PersonaClientState = 'closed' | 'connecting' | 'open' | 'reconnecting';
 /**
  * The subset of the WebSocket API the client uses. The global `WebSocket`
- * (browsers, Node ≥22, Bun) and the `ws` package's client both satisfy it
+ * (browsers, Node ≥24, Bun) and the `ws` package's client both satisfy it
  * structurally, so `createWebSocket` implementations need no casts.
  */
 export interface WebSocketLike {

package/dist/index.d.ts

@@ -1,15 +1,21 @@
 export * from './client/address.ts';
 export * from './client/client.ts';
 export * from './values/arkit.ts';
+export * from './values/bindings.ts';
+export * from './values/controller.ts';
 export * from './values/curve.ts';
-export * from './values/custom-effect.ts';
+export * from './values/edit-history.ts';
 export * from './values/effect-schema.ts';
+export * from './values/gltf-extensions.ts';
 export * from './values/guards.ts';
 export * from './values/hotkeys.ts';
 export * from './values/labels.ts';
 export * from './values/limits.ts';
 export * from './values/locale.ts';
+export * from './values/model-info.ts';
+export * from './values/stage-info.ts';
 export * from './values/terms.ts';
+export * from './values/vrm-bindings.ts';
 export * from './wire/envelope.ts';
 export * from './wire/errors.ts';
 export * from './wire/events.ts';

package/dist/index.js

@@ -3,15 +3,21 @@
 export * from "./client/address.js";
 export * from "./client/client.js";
 export * from "./values/arkit.js";
+export * from "./values/bindings.js";
+export * from "./values/controller.js";
 export * from "./values/curve.js";
-export * from "./values/custom-effect.js";
+export * from "./values/edit-history.js";
 export * from "./values/effect-schema.js";
+export * from "./values/gltf-extensions.js";
 export * from "./values/guards.js";
 export * from "./values/hotkeys.js";
 export * from "./values/labels.js";
 export * from "./values/limits.js";
 export * from "./values/locale.js";
+export * from "./values/model-info.js";
+export * from "./values/stage-info.js";
 export * from "./values/terms.js";
+export * from "./values/vrm-bindings.js";
 export * from "./wire/envelope.js";
 export * from "./wire/errors.js";
 export * from "./wire/events.js";

package/dist/values/bindings.d.ts

@@ -0,0 +1,43 @@
+import type { Curve } from './curve.ts';
+import type { BindingTerm } from './terms.ts';
+/** A saved input-to-parameter rule shared by the rig editor and plugin API. */
+export interface Binding {
+    /** Summed at their weights before the range map; never empty. The first is the input the list files it under. */
+    terms: BindingTerm[];
+    output: string;
+    /** The rig author's own name for this binding, when their `.vtube.json` carried one. */
+    name?: string;
+    inRange: [number, number];
+    outRange: [number, number];
+    clampOutput: boolean;
+    smoothing: number;
+    autoBlink: boolean;
+    curve?: Curve;
+}
+/** A parameter the rig declares, as the picker lists it. */
+export interface BindableParameter {
+    id: string;
+    min: number;
+    max: number;
+    default: number;
+}
+/** Metadata read from a rig's display and physics sidecars. */
+export interface BindingEditorData {
+    connections: Binding[];
+    parameters: BindableParameter[];
+    metadata: {
+        display: {
+            parameterNames: Record<string, string>;
+            parameterGroups: Record<string, string>;
+            groups: {
+                id: string;
+                name: string;
+            }[];
+        } | null;
+        physics: {
+            inputs: string[];
+            outputs: string[];
+        } | null;
+    };
+    edited: boolean;
+}

package/dist/values/bindings.js

@@ -0,0 +1 @@
+export {};

package/dist/values/controller.d.ts

@@ -0,0 +1,109 @@
+/** Positive safe-integer controller profile id, independent of the current browser index. */
+export type ControllerSlot = number;
+/** Whether a value can identify a persistent controller profile. */
+export declare function isControllerSlot(value: unknown): value is ControllerSlot;
+/** Standard gamepad controls, using VTS's parameter names for the first controller. */
+export declare const BASE_CONTROLLER_INPUT_NAMES: readonly ["ControllerStickLeftX", "ControllerStickLeftY", "ControllerStickRightX", "ControllerStickRightY", "ControllerStickPressLeft", "ControllerStickPressRight", "ControllerDPadX", "ControllerDPadY", "ControllerCross", "ControllerCircle", "ControllerSquare", "ControllerTriangle", "ControllerShoulderLeft", "ControllerShoulderRight", "ControllerTriggerLeft", "ControllerTriggerRight", "ControllerOptionLeft", "ControllerOptionRight", "ControllerHome"];
+export type BaseControllerInputName = (typeof BASE_CONTROLLER_INPUT_NAMES)[number];
+type NumberedControllerName<T extends string> = T extends `Controller${infer Control}` ? `Controller${number}${Control}` : never;
+export type ControllerInputName = BaseControllerInputName | NumberedControllerName<BaseControllerInputName>;
+/** Address a parameter on one controller; slot 1 retains its original VTS name. */
+export declare function controllerInputName(base: BaseControllerInputName, slot: ControllerSlot): ControllerInputName;
+/** Remove a controller parameter's slot prefix for shared labels and ranges. */
+export declare function baseControllerInputName(full: ControllerInputName): BaseControllerInputName;
+/** Whether an input names a supported controller parameter. */
+export declare function isControllerInputName(v: string): v is ControllerInputName;
+/** Stick and D-pad axes are signed, with positive Y pointing up; other controls are 0..1. */
+export declare const BASE_CONTROLLER_INPUT_RANGES: {
+    readonly ControllerStickLeftX: readonly [-1, 1];
+    readonly ControllerStickLeftY: readonly [-1, 1];
+    readonly ControllerStickRightX: readonly [-1, 1];
+    readonly ControllerStickRightY: readonly [-1, 1];
+    readonly ControllerStickPressLeft: readonly [0, 1];
+    readonly ControllerStickPressRight: readonly [0, 1];
+    readonly ControllerDPadX: readonly [-1, 1];
+    readonly ControllerDPadY: readonly [-1, 1];
+    readonly ControllerCross: readonly [0, 1];
+    readonly ControllerCircle: readonly [0, 1];
+    readonly ControllerSquare: readonly [0, 1];
+    readonly ControllerTriangle: readonly [0, 1];
+    readonly ControllerShoulderLeft: readonly [0, 1];
+    readonly ControllerShoulderRight: readonly [0, 1];
+    readonly ControllerTriggerLeft: readonly [0, 1];
+    readonly ControllerTriggerRight: readonly [0, 1];
+    readonly ControllerOptionLeft: readonly [0, 1];
+    readonly ControllerOptionRight: readonly [0, 1];
+    readonly ControllerHome: readonly [0, 1];
+};
+/** Natural parameter range, shared by every controller profile. */
+export declare function controllerInputRange(name: ControllerInputName): readonly [number, number];
+/** VTS shortcut names differ from parameter names, especially shoulders, clicks and D-pad. */
+export declare const BASE_CONTROLLER_TRIGGER_NAMES: readonly ["ControllerCross", "ControllerCircle", "ControllerSquare", "ControllerTriangle", "ControllerDpadUp", "ControllerDpadDown", "ControllerDpadLeft", "ControllerDpadRight", "ControllerLeftShoulder", "ControllerRightShoulder", "ControllerLeftTrigger", "ControllerRightTrigger", "ControllerLeftStickClick", "ControllerRightStickClick", "ControllerLeftStickUp", "ControllerLeftStickDown", "ControllerLeftStickLeft", "ControllerLeftStickRight", "ControllerRightStickUp", "ControllerRightStickDown", "ControllerRightStickLeft", "ControllerRightStickRight", "ControllerOptionLeft", "ControllerOptionRight", "ControllerHome"];
+export type BaseControllerTriggerName = (typeof BASE_CONTROLLER_TRIGGER_NAMES)[number];
+export type ControllerTriggerName = BaseControllerTriggerName | NumberedControllerName<BaseControllerTriggerName>;
+/** Address a shortcut trigger on one controller; slot 1 retains its original VTS name. */
+export declare function controllerTriggerName(base: BaseControllerTriggerName, slot: ControllerSlot): ControllerTriggerName;
+/** Remove a controller trigger's slot prefix for its shared control label. */
+export declare function baseControllerTriggerName(full: ControllerTriggerName): BaseControllerTriggerName;
+/** Whether a shortcut trigger names a supported controller control. */
+export declare function isControllerTriggerName(v: string): v is ControllerTriggerName;
+/**
+ * The slot addressed by a controller parameter or shortcut trigger; null for any other string.
+ * The typed overload trusts a name this module built or validated — the template types alone
+ * also admit `Controller0Cross`, which would answer null.
+ */
+export declare function controllerSlot(full: ControllerInputName | ControllerTriggerName): ControllerSlot;
+export declare function controllerSlot(full: string): ControllerSlot | null;
+/** Optional per-instance stage movement; posing remains in the model's input bindings. */
+export interface ControllerMovementConfig {
+    enabled: boolean;
+    slot: ControllerSlot;
+    /** Metres/second for VRM; stage heights/second for Live2D. */
+    moveSpeed: number;
+    /** Degrees/second. */
+    turnSpeed: number;
+    /** Velocity response time in seconds; zero responds immediately. */
+    smoothing: number;
+    /** Play a VRM walking cycle while moving across the stage. */
+    walkEnabled: boolean;
+    /** Registered animation clip reference, or null until one is selected. */
+    walkClip: string | null;
+    /** Nominal metres/second of the walking cycle at normal playback speed. */
+    walkSpeed: number;
+    /** Turn a VRM avatar toward its movement direction. */
+    faceMovement: boolean;
+}
+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;
+/** Analog buttons (triggers, pressure-sensitive faces) count as pressed from here. */
+export declare const BUTTON_PRESS_THRESHOLD = 0.5;
+/** Radial stick dead zone of a profile that has never been tuned. */
+export declare const DEFAULT_CONTROLLER_DEAD_ZONE = 0.15;
+export declare const CONTROLLER_DEAD_ZONE_MAX = 0.5;
+/** Saved controller profile names and per-device tuning, exposed to remote editors. */
+export interface ControllerProfileInfo {
+    slot: ControllerSlot;
+    deviceId: string;
+    name?: string;
+    /** Radial stick dead zone, 0..0.5; absent until tuned, meaning `DEFAULT_CONTROLLER_DEAD_ZONE`. */
+    deadZone?: number;
+}
+export interface ControllerConfig {
+    enabled: boolean;
+    profiles: ControllerProfileInfo[];
+}
+/** Stage-owned input sample; hardware is never polled by the remote console. */
+export interface ControllerState {
+    profiles: ControllerProfileInfo[];
+    devices: {
+        id: string;
+        index: number;
+        mapping: string;
+        slot: ControllerSlot | null;
+    }[];
+    inputs: Partial<Record<ControllerInputName, number>>;
+    pressed: ControllerTriggerName[];
+    assigningSlot: ControllerSlot | null;
+}
+export {};

package/dist/values/controller.js

@@ -0,0 +1,167 @@
+import { finiteOr, isRecord, nonEmptyString } from "./guards.js";
+import { clamp } from "./limits.js";
+/** Whether a value can identify a persistent controller profile. */
+export function isControllerSlot(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value > 0;
+}
+/** Standard gamepad controls, using VTS's parameter names for the first controller. */
+export const BASE_CONTROLLER_INPUT_NAMES = [
+    'ControllerStickLeftX',
+    'ControllerStickLeftY',
+    'ControllerStickRightX',
+    'ControllerStickRightY',
+    'ControllerStickPressLeft',
+    'ControllerStickPressRight',
+    'ControllerDPadX',
+    'ControllerDPadY',
+    'ControllerCross',
+    'ControllerCircle',
+    'ControllerSquare',
+    'ControllerTriangle',
+    'ControllerShoulderLeft',
+    'ControllerShoulderRight',
+    'ControllerTriggerLeft',
+    'ControllerTriggerRight',
+    'ControllerOptionLeft',
+    'ControllerOptionRight',
+    'ControllerHome',
+];
+/** Slot 1 keeps the bare VTS name; every other slot inserts its number after `Controller`. */
+function slotPrefixed(base, slot) {
+    if (!isControllerSlot(slot))
+        throw new RangeError('controller profile id must be a positive safe integer');
+    return slot === 1 ? base : `Controller${String(slot)}${base.slice('Controller'.length)}`;
+}
+const SLOT_PREFIX = /^Controller\d+/;
+/** Address a parameter on one controller; slot 1 retains its original VTS name. */
+export function controllerInputName(base, slot) {
+    return slotPrefixed(base, slot);
+}
+/** Remove a controller parameter's slot prefix for shared labels and ranges. */
+export function baseControllerInputName(full) {
+    return full.replace(SLOT_PREFIX, 'Controller');
+}
+const CONTROLLER_INPUT_SET = new Set(BASE_CONTROLLER_INPUT_NAMES);
+function controllerParts(full) {
+    const match = /^Controller([1-9]\d*)?([A-Za-z]+)$/.exec(full);
+    if (match === null)
+        return null;
+    const slot = match[1] === undefined ? 1 : Number(match[1]);
+    if (!isControllerSlot(slot) || (match[1] !== undefined && slot === 1))
+        return null;
+    return { slot, base: `Controller${match[2] ?? ''}` };
+}
+/** Whether an input names a supported controller parameter. */
+export function isControllerInputName(v) {
+    const parts = controllerParts(v);
+    return parts !== null && CONTROLLER_INPUT_SET.has(parts.base);
+}
+/** Stick and D-pad axes are signed, with positive Y pointing up; other controls are 0..1. */
+export const BASE_CONTROLLER_INPUT_RANGES = {
+    ControllerStickLeftX: [-1, 1],
+    ControllerStickLeftY: [-1, 1],
+    ControllerStickRightX: [-1, 1],
+    ControllerStickRightY: [-1, 1],
+    ControllerStickPressLeft: [0, 1],
+    ControllerStickPressRight: [0, 1],
+    ControllerDPadX: [-1, 1],
+    ControllerDPadY: [-1, 1],
+    ControllerCross: [0, 1],
+    ControllerCircle: [0, 1],
+    ControllerSquare: [0, 1],
+    ControllerTriangle: [0, 1],
+    ControllerShoulderLeft: [0, 1],
+    ControllerShoulderRight: [0, 1],
+    ControllerTriggerLeft: [0, 1],
+    ControllerTriggerRight: [0, 1],
+    ControllerOptionLeft: [0, 1],
+    ControllerOptionRight: [0, 1],
+    ControllerHome: [0, 1],
+};
+/** Natural parameter range, shared by every controller profile. */
+export function controllerInputRange(name) {
+    return BASE_CONTROLLER_INPUT_RANGES[baseControllerInputName(name)];
+}
+/** VTS shortcut names differ from parameter names, especially shoulders, clicks and D-pad. */
+export const BASE_CONTROLLER_TRIGGER_NAMES = [
+    'ControllerCross',
+    'ControllerCircle',
+    'ControllerSquare',
+    'ControllerTriangle',
+    'ControllerDpadUp',
+    'ControllerDpadDown',
+    'ControllerDpadLeft',
+    'ControllerDpadRight',
+    'ControllerLeftShoulder',
+    'ControllerRightShoulder',
+    'ControllerLeftTrigger',
+    'ControllerRightTrigger',
+    'ControllerLeftStickClick',
+    'ControllerRightStickClick',
+    'ControllerLeftStickUp',
+    'ControllerLeftStickDown',
+    'ControllerLeftStickLeft',
+    'ControllerLeftStickRight',
+    'ControllerRightStickUp',
+    'ControllerRightStickDown',
+    'ControllerRightStickLeft',
+    'ControllerRightStickRight',
+    'ControllerOptionLeft',
+    'ControllerOptionRight',
+    'ControllerHome',
+];
+/** Address a shortcut trigger on one controller; slot 1 retains its original VTS name. */
+export function controllerTriggerName(base, slot) {
+    return slotPrefixed(base, slot);
+}
+/** Remove a controller trigger's slot prefix for its shared control label. */
+export function baseControllerTriggerName(full) {
+    return full.replace(SLOT_PREFIX, 'Controller');
+}
+const CONTROLLER_TRIGGER_SET = new Set(BASE_CONTROLLER_TRIGGER_NAMES);
+/** Whether a shortcut trigger names a supported controller control. */
+export function isControllerTriggerName(v) {
+    const parts = controllerParts(v);
+    return parts !== null && CONTROLLER_TRIGGER_SET.has(parts.base);
+}
+export function controllerSlot(full) {
+    const parts = controllerParts(full);
+    return parts !== null && (CONTROLLER_INPUT_SET.has(parts.base) || CONTROLLER_TRIGGER_SET.has(parts.base))
+        ? parts.slot
+        : null;
+}
+const CONTROLLER_MOVE_SPEED_MAX = 10;
+const CONTROLLER_TURN_SPEED_MAX = 720;
+const CONTROLLER_MOVEMENT_SMOOTHING_MAX = 0.5;
+export const DEFAULT_CONTROLLER_MOVEMENT = {
+    enabled: false,
+    slot: 1,
+    moveSpeed: 0.5,
+    turnSpeed: 90,
+    smoothing: 0.12,
+    walkEnabled: false,
+    walkClip: null,
+    walkSpeed: 1,
+    faceMovement: false,
+};
+/** Heal saved movement or a merged API patch using the same limits as the controls. */
+export function healControllerMovement(raw) {
+    const r = isRecord(raw) ? raw : {};
+    const d = DEFAULT_CONTROLLER_MOVEMENT;
+    return {
+        enabled: typeof r.enabled === 'boolean' ? r.enabled : d.enabled,
+        slot: isControllerSlot(r.slot) ? r.slot : d.slot,
+        moveSpeed: clamp(finiteOr(r.moveSpeed, d.moveSpeed), 0, CONTROLLER_MOVE_SPEED_MAX),
+        turnSpeed: clamp(finiteOr(r.turnSpeed, d.turnSpeed), 0, CONTROLLER_TURN_SPEED_MAX),
+        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),
+        faceMovement: typeof r.faceMovement === 'boolean' ? r.faceMovement : d.faceMovement,
+    };
+}
+/** Analog buttons (triggers, pressure-sensitive faces) count as pressed from here. */
+export const BUTTON_PRESS_THRESHOLD = 0.5;
+/** Radial stick dead zone of a profile that has never been tuned. */
+export const DEFAULT_CONTROLLER_DEAD_ZONE = 0.15;
+export const CONTROLLER_DEAD_ZONE_MAX = 0.5;

package/dist/values/curve.d.ts

@@ -104,12 +104,8 @@ export declare function withBezierHandles(keyframes: Keyframe[]): Keyframe[];
  * The segment leaving `index` shaped as an ease-in-out: control points at the thirds, each held
  * at its own anchor's height, so the curve leaves flat and arrives flat.
  *
- * What an editor's Bezier button applies, and the one place seeding is *meant* to change the
- * curve — pressing the button is an authoring action, and a mode switch that visibly did nothing
- * reads as a broken button. `withBezierHandles` is the opposite: it repairs, so it stays inert.
- *
- * A segment already carrying both handles is returned untouched, so linear → bezier gives back
- * the shape that was there rather than flattening it into a fresh ease.
+ * An authoring seed; `withBezierHandles` repairs without changing the shape. A segment already
+ * carrying both handles is returned untouched.
  */
 export declare function easeBezierSegment(keyframes: Keyframe[], index: number): Keyframe[];
 /**
@@ -158,10 +154,11 @@ export declare function sanitizeCurve(v: unknown): Curve | null;
  */
 export declare function identityCurve(): Curve;
 /** A ready-made response shape that replaces the whole curve; `linear` is the identity. */
-export type CurvePresetId = 'linear' | 'easeIn' | 'easeOut' | 'sCurve' | 'threshold' | 'steps';
+export type CurvePresetId = 'linear' | 'step' | 'invertStep' | 'bezier' | 'easeIn' | 'easeOut' | 'sCurve' | 'threshold' | 'steps';
 export declare const CURVE_PRESET_IDS: readonly CurvePresetId[];
 /**
- * The shapes VBridger's shipped presets reach for, transcribed from their Unity curves
+ * Fresh whole-curve shapes: endpoint holds, a Bezier ease-in-out, and shapes from VBridger's presets.
+ * The remaining shapes are transcribed from its Unity curves
  * (references/vbridger-desktop/saves/, `store[].curve.keys`). A Hermite key pair converts to a
  * Bezier segment exactly — `P1 = A + Δx/3·(1, m₀)`, `P2 = B − Δx/3·(1, m₁)` — so these evaluate as
  * the originals do:

package/dist/values/curve.js

@@ -171,12 +171,8 @@ export function withBezierHandles(keyframes) {
  * The segment leaving `index` shaped as an ease-in-out: control points at the thirds, each held
  * at its own anchor's height, so the curve leaves flat and arrives flat.
  *
- * What an editor's Bezier button applies, and the one place seeding is *meant* to change the
- * curve — pressing the button is an authoring action, and a mode switch that visibly did nothing
- * reads as a broken button. `withBezierHandles` is the opposite: it repairs, so it stays inert.
- *
- * A segment already carrying both handles is returned untouched, so linear → bezier gives back
- * the shape that was there rather than flattening it into a fresh ease.
+ * An authoring seed; `withBezierHandles` repairs without changing the shape. A segment already
+ * carrying both handles is returned untouched.
  */
 export function easeBezierSegment(keyframes, index) {
     const left = keyframes[index];
@@ -328,6 +324,9 @@ export function identityCurve() {
 }
 export const CURVE_PRESET_IDS = [
     'linear',
+    'step',
+    'invertStep',
+    'bezier',
     'easeIn',
     'easeOut',
     'sCurve',
@@ -335,7 +334,8 @@ export const CURVE_PRESET_IDS = [
     'steps',
 ];
 /**
- * The shapes VBridger's shipped presets reach for, transcribed from their Unity curves
+ * Fresh whole-curve shapes: endpoint holds, a Bezier ease-in-out, and shapes from VBridger's presets.
+ * The remaining shapes are transcribed from its Unity curves
  * (references/vbridger-desktop/saves/, `store[].curve.keys`). A Hermite key pair converts to a
  * Bezier segment exactly — `P1 = A + Δx/3·(1, m₀)`, `P2 = B − Δx/3·(1, m₁)` — so these evaluate as
  * the originals do:
@@ -351,6 +351,15 @@ export function curvePreset(id) {
     switch (id) {
         case 'linear':
             return identityCurve();
+        case 'step':
+        case 'invertStep':
+        case 'bezier': {
+            const keyframes = [
+                { anchor: { x: 0, y: 0 }, interpolation: id },
+                { anchor: { x: 1, y: 1 }, interpolation: 'linear' },
+            ];
+            return { keyframes: id === 'bezier' ? easeBezierSegment(keyframes, 0) : keyframes };
+        }
         case 'easeIn':
             return {
                 keyframes: [

package/dist/values/edit-history.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Bounded undo/redo over whole-value snapshots, keyed by content: a push equal to the cursor
+ * entry is dropped, and a push after an undo truncates the redo tail. Entries are cloned on
+ * capture and on restore, so a caller mutating what it holds can never rewrite history.
+ */
+export interface EditHistory<T> {
+    /** Drop everything and seed a single baseline entry. */
+    reset(value: T): void;
+    /** Record `value` if its content differs from the cursor entry; truncates the redo tail. */
+    push(value: T): void;
+    /** Step back; a fresh clone, or null at the floor. */
+    undo(): T | null;
+    /** Step forward; mirror of {@link EditHistory.undo}. */
+    redo(): T | null;
+    /**
+     * Rewrite the run of entries around the cursor that share its `runKey`, outward until the key
+     * changes on either side — a fold, never a step, so undo and redo across the run all carry it.
+     */
+    amend(runKey: (value: T) => string, rewrite: (value: T) => void): void;
+}
+export declare function createEditHistory<T>(limit?: number): EditHistory<T>;

package/dist/values/edit-history.js

@@ -0,0 +1,62 @@
+const EDIT_HISTORY_LIMIT = 50;
+export function createEditHistory(limit = EDIT_HISTORY_LIMIT) {
+    let stack = [];
+    let cursor = -1;
+    const entryOf = (value, key = JSON.stringify(value)) => ({ value: structuredClone(value), key });
+    return {
+        reset(value) {
+            stack = [entryOf(value)];
+            cursor = 0;
+        },
+        push(value) {
+            // Keyed before it is cloned: a commit that changed nothing — a field blurred on the value it
+            // already held, or a restore committed back — is not a step, and the second is what keeps
+            // the redo tail alive.
+            const key = JSON.stringify(value);
+            const cur = stack[cursor];
+            if (cur && cur.key === key)
+                return;
+            stack.length = cursor + 1;
+            stack.push(entryOf(value, key));
+            cursor++;
+            if (stack.length > limit) {
+                stack.shift();
+                cursor--;
+            }
+        },
+        undo() {
+            if (cursor <= 0)
+                return null;
+            cursor--;
+            return structuredClone(stack[cursor].value);
+        },
+        redo() {
+            if (cursor >= stack.length - 1)
+                return null;
+            cursor++;
+            return structuredClone(stack[cursor].value);
+        },
+        amend(runKey, rewrite) {
+            const cur = stack[cursor];
+            if (!cur)
+                return;
+            const from = runKey(cur.value);
+            const apply = (e) => {
+                rewrite(e.value);
+                e.key = JSON.stringify(e.value);
+            };
+            for (let i = cursor; i >= 0; i--) {
+                const entry = stack[i];
+                if (runKey(entry.value) !== from)
+                    break;
+                apply(entry);
+            }
+            for (let i = cursor + 1; i < stack.length; i++) {
+                const entry = stack[i];
+                if (runKey(entry.value) !== from)
+                    break;
+                apply(entry);
+            }
+        },
+    };
+}

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

@@ -33,9 +33,9 @@ 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.
+ * Composition order, bottom to top.
  * 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')[];
+export declare const EFFECT_STACK_ORDER: readonly ToggleEffectKey[];
 /** 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

@@ -185,7 +185,7 @@ 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.
+ * Composition order, bottom to top.
  * Display-only: the desktop chain's `rebuild()` is the order that runs — a stage moved there moves here too.
  */
 export const EFFECT_STACK_ORDER = [
@@ -202,7 +202,6 @@ export const EFFECT_STACK_ORDER = [
     'pixelate',
     'glitch',
     'droplets',
-    'custom',
     'grain',
     'vignette',
 ];

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

@@ -0,0 +1,20 @@
+/** Which loader read the file: a VRM avatar, or a plain glb — a prop or an environment set. */
+export type GltfLoadPath = 'vrm' | 'gltf';
+/** The app's wardrobe extension, read on avatars — `renderer/vrm/gltf-outfit.ts`. */
+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. */
+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>>;
+/** The extensions a glTF root declares (`extensionsUsed`) or carries itself, deduped in file order. */
+export declare function declaredExtensions(json: {
+    extensionsUsed?: unknown;
+    extensions?: unknown;
+}): string[];
+/** A file's declared extensions split by what its loader honours, each side in file order. */
+export declare function partitionExtensions(declared: readonly string[], path: GltfLoadPath): {
+    supported: string[];
+    unsupported: string[];
+};