@laplace.live/persona-sdk 0.17.0 → 0.18.0

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export * from './client/address.ts';
 export * from './client/client.ts';
+export * from './values/arkit.ts';
+export * from './values/curve.ts';
 export * from './values/custom-effect.ts';
 export * from './values/effect-schema.ts';
 export * from './values/guards.ts';
@@ -7,6 +9,7 @@ export * from './values/hotkeys.ts';
 export * from './values/labels.ts';
 export * from './values/limits.ts';
 export * from './values/locale.ts';
+export * from './values/terms.ts';
 export * from './wire/envelope.ts';
 export * from './wire/errors.ts';
 export * from './wire/events.ts';

package/dist/index.js

@@ -2,6 +2,8 @@
 // and the values/registries every Persona app must agree on.
 export * from "./client/address.js";
 export * from "./client/client.js";
+export * from "./values/arkit.js";
+export * from "./values/curve.js";
 export * from "./values/custom-effect.js";
 export * from "./values/effect-schema.js";
 export * from "./values/guards.js";
@@ -9,6 +11,7 @@ export * from "./values/hotkeys.js";
 export * from "./values/labels.js";
 export * from "./values/limits.js";
 export * from "./values/locale.js";
+export * from "./values/terms.js";
 export * from "./wire/envelope.js";
 export * from "./wire/errors.js";
 export * from "./wire/events.js";

package/dist/values/arkit.d.ts

@@ -0,0 +1,16 @@
+/** Canonical ARKit blendshape names, as `ARFaceAnchor` spells them. */
+export declare const ARKIT_SHAPES: readonly ["browDownLeft", "browDownRight", "browInnerUp", "browOuterUpLeft", "browOuterUpRight", "cheekPuff", "cheekSquintLeft", "cheekSquintRight", "eyeBlinkLeft", "eyeBlinkRight", "eyeLookDownLeft", "eyeLookDownRight", "eyeLookInLeft", "eyeLookInRight", "eyeLookOutLeft", "eyeLookOutRight", "eyeLookUpLeft", "eyeLookUpRight", "eyeSquintLeft", "eyeSquintRight", "eyeWideLeft", "eyeWideRight", "jawForward", "jawLeft", "jawOpen", "jawRight", "mouthClose", "mouthDimpleLeft", "mouthDimpleRight", "mouthFrownLeft", "mouthFrownRight", "mouthFunnel", "mouthLeft", "mouthLowerDownLeft", "mouthLowerDownRight", "mouthPressLeft", "mouthPressRight", "mouthPucker", "mouthRight", "mouthRollLower", "mouthRollUpper", "mouthShrugLower", "mouthShrugUpper", "mouthSmileLeft", "mouthSmileRight", "mouthStretchLeft", "mouthStretchRight", "mouthUpperUpLeft", "mouthUpperUpRight", "noseSneerLeft", "noseSneerRight", "tongueOut"];
+export type ArkitShape = (typeof ARKIT_SHAPES)[number];
+/** Full perfect-sync coverage: all {@link ARKIT_SHAPES}. */
+export declare const ARKIT_TOTAL: 52;
+/**
+ * An ARKit channel's id as a tracking input. Namespaced because VTS already has `JawOpen`,
+ * `CheekPuff` and `TongueOut`, and `.vtube.json` import case-folds.
+ */
+export type ArkitInputName = `ARKit${Capitalize<ArkitShape>}`;
+/** The input id for one ARKit channel. */
+export declare function arkitInputName(shape: ArkitShape): ArkitInputName;
+/** Every ARKit channel as a tracking input, in {@link ARKIT_SHAPES} order. */
+export declare const ARKIT_INPUT_NAMES: readonly ArkitInputName[];
+/** Whether an input id names a raw ARKit channel rather than one of VTS's derived inputs. */
+export declare function isArkitInputName(v: string): v is ArkitInputName;

package/dist/values/arkit.js

@@ -0,0 +1,71 @@
+// The 52 ARKit blendshapes and their spelling as `ARKit*` tracking inputs: binding one reads the
+// shape the phone measured instead of the lossy VTS-vocabulary derivation ("perfect sync").
+/** Canonical ARKit blendshape names, as `ARFaceAnchor` spells them. */
+export const ARKIT_SHAPES = [
+    'browDownLeft',
+    'browDownRight',
+    'browInnerUp',
+    'browOuterUpLeft',
+    'browOuterUpRight',
+    'cheekPuff',
+    'cheekSquintLeft',
+    'cheekSquintRight',
+    'eyeBlinkLeft',
+    'eyeBlinkRight',
+    'eyeLookDownLeft',
+    'eyeLookDownRight',
+    'eyeLookInLeft',
+    'eyeLookInRight',
+    'eyeLookOutLeft',
+    'eyeLookOutRight',
+    'eyeLookUpLeft',
+    'eyeLookUpRight',
+    'eyeSquintLeft',
+    'eyeSquintRight',
+    'eyeWideLeft',
+    'eyeWideRight',
+    'jawForward',
+    'jawLeft',
+    'jawOpen',
+    'jawRight',
+    'mouthClose',
+    'mouthDimpleLeft',
+    'mouthDimpleRight',
+    'mouthFrownLeft',
+    'mouthFrownRight',
+    'mouthFunnel',
+    'mouthLeft',
+    'mouthLowerDownLeft',
+    'mouthLowerDownRight',
+    'mouthPressLeft',
+    'mouthPressRight',
+    'mouthPucker',
+    'mouthRight',
+    'mouthRollLower',
+    'mouthRollUpper',
+    'mouthShrugLower',
+    'mouthShrugUpper',
+    'mouthSmileLeft',
+    'mouthSmileRight',
+    'mouthStretchLeft',
+    'mouthStretchRight',
+    'mouthUpperUpLeft',
+    'mouthUpperUpRight',
+    'noseSneerLeft',
+    'noseSneerRight',
+    'tongueOut',
+];
+/** Full perfect-sync coverage: all {@link ARKIT_SHAPES}. */
+export const ARKIT_TOTAL = ARKIT_SHAPES.length;
+/** The input id for one ARKit channel. */
+export function arkitInputName(shape) {
+    // TS cannot type a runtime capitalization as the template literal it computes.
+    return `ARKit${shape.charAt(0).toUpperCase()}${shape.slice(1)}`;
+}
+/** Every ARKit channel as a tracking input, in {@link ARKIT_SHAPES} order. */
+export const ARKIT_INPUT_NAMES = ARKIT_SHAPES.map(s => arkitInputName(s));
+const ARKIT_INPUT_SET = new Set(ARKIT_INPUT_NAMES);
+/** Whether an input id names a raw ARKit channel rather than one of VTS's derived inputs. */
+export function isArkitInputName(v) {
+    return ARKIT_INPUT_SET.has(v);
+}

package/dist/values/curve.d.ts

@@ -0,0 +1,174 @@
+/**
+ * Response curves for tracking bindings — the shape a straight `inRange`→`outRange` cannot say:
+ * a dead zone before a blink starts, a plateau where an eye rests, a held maximum.
+ *
+ * Modelled on nizima LIVE's `.live.json` curve, whose semantics were recovered from
+ * `Framework::Curve::interpolate` (see `references/nizima-desktop/disasm/curve-evaluator.txt`).
+ * Both axes are normalized 0..1, so a curve is portable between parameters — the binding's
+ * `outRange` is what puts it in Cubism units.
+ */
+/** Governs the segment *leaving* a keyframe; the last keyframe's is never read. */
+export type Interpolation = 'linear' | 'step' | 'invertStep' | 'bezier';
+export interface Point {
+    x: number;
+    y: number;
+}
+export interface Keyframe {
+    /** Both axes normalized 0..1. Keyframes are sorted by `anchor.x`. */
+    anchor: Point;
+    /**
+     * Bezier handles. `x` is a **fraction of the segment's x-span** (0 = this segment's left
+     * anchor, 1 = its right), `y` is absolute — nizima's asymmetry, and worth keeping: an
+     * anchor dragged sideways carries its handles, while the shape stays pinned to real output.
+     */
+    next?: Point;
+    previous?: Point;
+    interpolation: Interpolation;
+}
+export interface Curve {
+    keyframes: Keyframe[];
+}
+/** Smallest gap kept between an interior anchor and its neighbours, so no segment is zero-span. */
+export declare const EDGE_EPSILON = 0.001;
+/**
+ * A handle's absolute x, from its segment-relative fraction.
+ *
+ * Exported so an editor draws a handle where the evaluator reads it — the clamp is the whole
+ * reason `tAtX`'s bisection has one root, and a second copy of it would drift.
+ */
+export declare function handleX(from: number, to: number, fraction: number): number;
+/**
+ * The inverse of `handleX`: a handle's stored fraction, from its absolute x.
+ *
+ * Clamped for the same reason `handleX` is — a fraction outside 0..1 is re-clamped on read, so
+ * storing one would hand back a shape nobody drew.
+ */
+export declare function handleFraction(from: number, to: number, x: number): number;
+/**
+ * The curve's output for a normalized input, both in 0..1.
+ *
+ * Outside the keyframes' span the end values are held. nizima instead returns the raw input
+ * below the first anchor and 0 above the last; both are unreachable for a curve spanning 0..1,
+ * and holding is what a caller clamping its input actually wants.
+ */
+export declare function evaluateCurve(curve: Curve, x: number): number;
+/** A handle is stored on a keyframe; `next` shapes the segment leaving it, `previous` the one arriving. */
+export type HandleSide = 'next' | 'previous';
+export interface CurveHandle extends Point {
+    /** Which of the keyframe's two handles this is; also the property it is written back to. */
+    side: HandleSide;
+    /** The x-span of the segment it shapes — where `handleX` can put it, and so where it may move. */
+    span: readonly [number, number];
+}
+/**
+ * The keyframe's draggable handles, in curve coordinates — its outgoing one when it governs a
+ * Bezier segment, its incoming one when the keyframe before it does.
+ *
+ * `handleX` rather than a second clamp-and-lerp: a handle has to read back where the evaluator
+ * looks for it. `y` is absolute and deliberately unclamped — `sanitizeCurve` keeps a control point
+ * outside 0..1 and only the cubic's *result* is clamped, so clamping here would report a
+ * legitimate overshoot at the wrong height.
+ */
+export declare function handlesFor(keyframes: Keyframe[], index: number): CurveHandle[];
+/**
+ * How far an anchor may travel in x, as `[lo, hi]`.
+ *
+ * The ends are pinned to where they are: a curve that no longer spans 0..1 leaves the evaluator
+ * holding an end value over the gap, which reads as the binding going dead. An interior anchor
+ * stops at its neighbours rather than swapping past them — a swap renames every index mid-drag,
+ * and re-pairs Bezier handles with endpoints they were not cut for.
+ *
+ * One statement of the rule, so an editor's drag and its typed field cannot drift apart.
+ */
+export declare function anchorBounds(keyframes: Keyframe[], index: number): [number, number];
+/**
+ * Every Bezier segment carries both handles, seeded collinear unless it already has both.
+ *
+ * `segmentAt` degrades a half-handled segment to the straight line, so a Bezier keyframe without
+ * its handles names a shape nothing can reach and an editor has nothing to draw or drag — which
+ * is what a hand-written config, a plugin, or an anchor added into a Bezier segment produces.
+ * Seeding at the thirds reproduces that straight line exactly, so this never changes what a curve
+ * does; dragging a handle is what shapes it. Assumes keyframes sorted by `anchor.x`.
+ *
+ * A half-handled segment is seeded on **both** ends rather than only the empty one. Handles belong
+ * to a segment, not a keyframe: a lone survivor was calibrated against endpoints that no longer
+ * pair with it — an anchor was added, removed, or dragged past its neighbour — so pairing it with
+ * a fresh seed would bend a curve nobody shaped. It was already evaluating as the straight line,
+ * and after seeding it still does.
+ *
+ * This is the *repair*, which is why it stays inert: it runs on ingestion, where a curve arriving
+ * from disk must come back doing exactly what it did. `easeBezierSegment` is the authoring seed.
+ */
+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.
+ */
+export declare function easeBezierSegment(keyframes: Keyframe[], index: number): Keyframe[];
+/**
+ * Split the Bezier segment leaving `index` at normalized `x`, inserting an anchor on the curve.
+ *
+ * de Casteljau, so the two halves together reproduce the original cubic exactly: adding a point to
+ * a curved stretch does not move it. Without this the halves are re-cut collinear and the shape is
+ * gone — an S-curve becomes a straight line the moment you click on it.
+ *
+ * The anchor lands *on* the curve rather than under the pointer, which is what preserving the shape
+ * means; a caller who wants it elsewhere drags it afterwards. When the segment is not a
+ * fully-handled Bezier this returns **the input array itself**, which is how `insertAnchor` tells
+ * that it declined — keep that identity if you touch the guards.
+ */
+export declare function splitBezierSegment(keyframes: Keyframe[], index: number, x: number): Keyframe[];
+/**
+ * A new anchor at `at`, and the index it landed on.
+ *
+ * A fully-handled Bezier segment is subdivided, which puts the anchor *on* the curve — preserving
+ * the shape is what a click into a curved stretch has to mean. Any other segment takes the point as
+ * given, and the new keyframe inherits that segment's mode either way, so a point dropped into a
+ * Bezier stretch carries the two handles that implies rather than straightening what follows.
+ *
+ * `at` is kept strictly inside the two ends: an anchor sharing an end's x is a zero-span segment,
+ * which silently changes the value the evaluator holds past that end.
+ */
+export declare function insertAnchor(keyframes: Keyframe[], at: Point): {
+    keyframes: Keyframe[];
+    index: number;
+};
+/**
+ * A curve from an untrusted document — a config file or an IPC caller — or null when it
+ * cannot be made into one. Anchors are clamped into the unit square and sorted by x, which is
+ * what `evaluateCurve`'s scan assumes; handle y is left alone, since a control point outside
+ * 0..1 is legitimate and the evaluator clamps its result anyway.
+ */
+export declare function sanitizeCurve(v: unknown): Curve | null;
+/**
+ * The straight 0..1 line — what a binding without a curve already does, as an editable start.
+ *
+ * No handles: a `linear` keyframe's are never read, and one that outlives the segment it was cut
+ * for is what bends a curve on a mode switch. `withBezierHandles` cuts fresh ones against whatever
+ * the anchors are by then, so Bezier leaves the line where it is and only a drag shapes it.
+ */
+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 declare const CURVE_PRESET_IDS: readonly CurvePresetId[];
+/**
+ * The shapes VBridger's shipped presets reach for, transcribed from their 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:
+ *
+ * - `easeOut` is its mouth curve (`MouthOpen`, `JawOpen`: out-tangent 2, in-tangent 0) — opens
+ *   twice as fast as linear and saturates; `easeIn` is the mirror.
+ * - `sCurve` is its head-angle curve (`FaceAngle`, `MouthPressLipOpen`: flat ends, slope 2 through
+ *   rest) — twice as sensitive around rest, compressed at the extremes.
+ * - `threshold` and `steps` are what its step lists do, minus the hysteresis and hold: `steps`
+ *   carries the `_Stepped` preset's `MouthOpen` levels (0 / .25 / .5 / 1 at .1 / .5 / .75).
+ */
+export declare function curvePreset(id: CurvePresetId): Curve;

package/dist/values/curve.js

@@ -0,0 +1,399 @@
+import { isFiniteNumber, isRecord } from "./guards.js";
+import { clamp } from "./limits.js";
+/** Smallest gap kept between an interior anchor and its neighbours, so no segment is zero-span. */
+export const EDGE_EPSILON = 0.001;
+const lerp = (a, b, t) => a + (b - a) * t;
+/** Cubic Bezier at `t`, one axis. */
+function cubic(p0, p1, p2, p3, t) {
+    const u = 1 - t;
+    return u * u * u * p0 + 3 * u * u * t * p1 + 3 * u * t * t * p2 + t * t * t * p3;
+}
+/**
+ * `t` where the segment's x reaches `x`.
+ *
+ * Handle x-fractions are clamped to 0..1 by `handleX`, which makes x(t) monotonic and leaves
+ * exactly one root — so plain bisection finds it. nizima instead solves the cubic and picks the
+ * root nearest 0.5, which only differs for handles that overshoot their own segment; none of the
+ * curves it ships has one.
+ */
+function tAtX(p0, p1, p2, p3, x) {
+    let lo = 0;
+    let hi = 1;
+    // 20 halvings ≈ 1e-6 on a unit domain; a fixed count keeps the cost flat and the result stable.
+    for (let i = 0; i < 20; i++) {
+        const mid = (lo + hi) / 2;
+        if (cubic(p0, p1, p2, p3, mid) < x)
+            lo = mid;
+        else
+            hi = mid;
+    }
+    return (lo + hi) / 2;
+}
+/**
+ * A handle's absolute x, from its segment-relative fraction.
+ *
+ * Exported so an editor draws a handle where the evaluator reads it — the clamp is the whole
+ * reason `tAtX`'s bisection has one root, and a second copy of it would drift.
+ */
+export function handleX(from, to, fraction) {
+    return lerp(from, to, clamp(fraction, 0, 1));
+}
+/**
+ * The inverse of `handleX`: a handle's stored fraction, from its absolute x.
+ *
+ * Clamped for the same reason `handleX` is — a fraction outside 0..1 is re-clamped on read, so
+ * storing one would hand back a shape nobody drew.
+ */
+export function handleFraction(from, to, x) {
+    return to === from ? 0 : clamp((x - from) / (to - from), 0, 1);
+}
+function segmentAt(left, right, x) {
+    switch (left.interpolation) {
+        case 'step':
+            return left.anchor.y;
+        case 'invertStep':
+            return right.anchor.y;
+        case 'bezier': {
+            // A bezier keyframe missing either handle has no curve to describe, so it degrades to the
+            // straight line rather than to nizima's (0,0) fallback, which would jump to the floor.
+            if (!left.next || !right.previous)
+                break;
+            const x0 = left.anchor.x;
+            const x3 = right.anchor.x;
+            const t = tAtX(x0, handleX(x0, x3, left.next.x), handleX(x0, x3, right.previous.x), x3, x);
+            return clamp(cubic(left.anchor.y, left.next.y, right.previous.y, right.anchor.y, t), 0, 1);
+        }
+    }
+    const span = right.anchor.x - left.anchor.x;
+    return span === 0 ? right.anchor.y : lerp(left.anchor.y, right.anchor.y, (x - left.anchor.x) / span);
+}
+/**
+ * The curve's output for a normalized input, both in 0..1.
+ *
+ * Outside the keyframes' span the end values are held. nizima instead returns the raw input
+ * below the first anchor and 0 above the last; both are unreachable for a curve spanning 0..1,
+ * and holding is what a caller clamping its input actually wants.
+ */
+export function evaluateCurve(curve, x) {
+    const kf = curve.keyframes;
+    const first = kf[0];
+    const last = kf[kf.length - 1];
+    if (first === undefined || last === undefined)
+        return x;
+    if (x <= first.anchor.x)
+        return first.anchor.y;
+    if (x >= last.anchor.x)
+        return last.anchor.y;
+    let i = 0;
+    while (i < kf.length - 2 && x > (kf[i + 1]?.anchor.x ?? 1))
+        i++;
+    const left = kf[i];
+    const right = kf[i + 1];
+    return left === undefined || right === undefined ? first.anchor.y : segmentAt(left, right, x);
+}
+/**
+ * The keyframe's draggable handles, in curve coordinates — its outgoing one when it governs a
+ * Bezier segment, its incoming one when the keyframe before it does.
+ *
+ * `handleX` rather than a second clamp-and-lerp: a handle has to read back where the evaluator
+ * looks for it. `y` is absolute and deliberately unclamped — `sanitizeCurve` keeps a control point
+ * outside 0..1 and only the cubic's *result* is clamped, so clamping here would report a
+ * legitimate overshoot at the wrong height.
+ */
+export function handlesFor(keyframes, index) {
+    const out = [];
+    const kf = keyframes[index];
+    if (kf === undefined)
+        return out;
+    const after = keyframes[index + 1];
+    if (kf.interpolation === 'bezier' && after !== undefined && kf.next !== undefined) {
+        const span = [kf.anchor.x, after.anchor.x];
+        out.push({ side: 'next', x: handleX(span[0], span[1], kf.next.x), y: kf.next.y, span });
+    }
+    const before = keyframes[index - 1];
+    if (before?.interpolation === 'bezier' && kf.previous !== undefined) {
+        const span = [before.anchor.x, kf.anchor.x];
+        out.push({ side: 'previous', x: handleX(span[0], span[1], kf.previous.x), y: kf.previous.y, span });
+    }
+    return out;
+}
+/**
+ * How far an anchor may travel in x, as `[lo, hi]`.
+ *
+ * The ends are pinned to where they are: a curve that no longer spans 0..1 leaves the evaluator
+ * holding an end value over the gap, which reads as the binding going dead. An interior anchor
+ * stops at its neighbours rather than swapping past them — a swap renames every index mid-drag,
+ * and re-pairs Bezier handles with endpoints they were not cut for.
+ *
+ * One statement of the rule, so an editor's drag and its typed field cannot drift apart.
+ */
+export function anchorBounds(keyframes, index) {
+    const held = keyframes[index];
+    if (held === undefined)
+        return [0, 1];
+    if (index === 0 || index === keyframes.length - 1)
+        return [held.anchor.x, held.anchor.x];
+    return [(keyframes[index - 1]?.anchor.x ?? 0) + EDGE_EPSILON, (keyframes[index + 1]?.anchor.x ?? 1) - EDGE_EPSILON];
+}
+/**
+ * Every Bezier segment carries both handles, seeded collinear unless it already has both.
+ *
+ * `segmentAt` degrades a half-handled segment to the straight line, so a Bezier keyframe without
+ * its handles names a shape nothing can reach and an editor has nothing to draw or drag — which
+ * is what a hand-written config, a plugin, or an anchor added into a Bezier segment produces.
+ * Seeding at the thirds reproduces that straight line exactly, so this never changes what a curve
+ * does; dragging a handle is what shapes it. Assumes keyframes sorted by `anchor.x`.
+ *
+ * A half-handled segment is seeded on **both** ends rather than only the empty one. Handles belong
+ * to a segment, not a keyframe: a lone survivor was calibrated against endpoints that no longer
+ * pair with it — an anchor was added, removed, or dragged past its neighbour — so pairing it with
+ * a fresh seed would bend a curve nobody shaped. It was already evaluating as the straight line,
+ * and after seeding it still does.
+ *
+ * This is the *repair*, which is why it stays inert: it runs on ingestion, where a curve arriving
+ * from disk must come back doing exactly what it did. `easeBezierSegment` is the authoring seed.
+ */
+export function withBezierHandles(keyframes) {
+    const out = [...keyframes];
+    for (let i = 0; i < out.length - 1; i++) {
+        const left = out[i];
+        const right = out[i + 1];
+        if (left === undefined || right === undefined || left.interpolation !== 'bezier')
+            continue;
+        if (left.next !== undefined && right.previous !== undefined)
+            continue;
+        out[i] = { ...left, next: { x: 1 / 3, y: lerp(left.anchor.y, right.anchor.y, 1 / 3) } };
+        out[i + 1] = { ...right, previous: { x: 2 / 3, y: lerp(left.anchor.y, right.anchor.y, 2 / 3) } };
+    }
+    return out;
+}
+/**
+ * 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.
+ */
+export function easeBezierSegment(keyframes, index) {
+    const left = keyframes[index];
+    const right = keyframes[index + 1];
+    if (left === undefined || right === undefined || left.interpolation !== 'bezier')
+        return keyframes;
+    if (left.next !== undefined && right.previous !== undefined)
+        return keyframes;
+    const out = [...keyframes];
+    out[index] = { ...left, next: { x: 1 / 3, y: left.anchor.y } };
+    out[index + 1] = { ...right, previous: { x: 2 / 3, y: right.anchor.y } };
+    return out;
+}
+/** Both axes of `lerp`, for the de Casteljau construction. */
+function lerpPoint(a, b, t) {
+    return { x: lerp(a.x, b.x, t), y: lerp(a.y, b.y, t) };
+}
+/**
+ * Split the Bezier segment leaving `index` at normalized `x`, inserting an anchor on the curve.
+ *
+ * de Casteljau, so the two halves together reproduce the original cubic exactly: adding a point to
+ * a curved stretch does not move it. Without this the halves are re-cut collinear and the shape is
+ * gone — an S-curve becomes a straight line the moment you click on it.
+ *
+ * The anchor lands *on* the curve rather than under the pointer, which is what preserving the shape
+ * means; a caller who wants it elsewhere drags it afterwards. When the segment is not a
+ * fully-handled Bezier this returns **the input array itself**, which is how `insertAnchor` tells
+ * that it declined — keep that identity if you touch the guards.
+ */
+export function splitBezierSegment(keyframes, index, x) {
+    const left = keyframes[index];
+    const right = keyframes[index + 1];
+    if (left === undefined || right === undefined || left.interpolation !== 'bezier')
+        return keyframes;
+    if (left.next === undefined || right.previous === undefined)
+        return keyframes;
+    const p0 = left.anchor;
+    const p3 = right.anchor;
+    const p1 = { x: handleX(p0.x, p3.x, left.next.x), y: left.next.y };
+    const p2 = { x: handleX(p0.x, p3.x, right.previous.x), y: right.previous.y };
+    const t = tAtX(p0.x, p1.x, p2.x, p3.x, x);
+    const a = lerpPoint(p0, p1, t);
+    const b = lerpPoint(p1, p2, t);
+    const c = lerpPoint(p2, p3, t);
+    const d = lerpPoint(a, b, t);
+    const e = lerpPoint(b, c, t);
+    const anchor = lerpPoint(d, e, t);
+    const out = [...keyframes];
+    // The right keyframe is rewritten before the splice, while it is still at `index + 1`.
+    out[index] = { ...left, next: { x: handleFraction(p0.x, anchor.x, a.x), y: a.y } };
+    out[index + 1] = { ...right, previous: { x: handleFraction(anchor.x, p3.x, c.x), y: c.y } };
+    out.splice(index + 1, 0, {
+        anchor,
+        interpolation: 'bezier',
+        previous: { x: handleFraction(p0.x, anchor.x, d.x), y: d.y },
+        next: { x: handleFraction(anchor.x, p3.x, e.x), y: e.y },
+    });
+    return out;
+}
+/**
+ * A new anchor at `at`, and the index it landed on.
+ *
+ * A fully-handled Bezier segment is subdivided, which puts the anchor *on* the curve — preserving
+ * the shape is what a click into a curved stretch has to mean. Any other segment takes the point as
+ * given, and the new keyframe inherits that segment's mode either way, so a point dropped into a
+ * Bezier stretch carries the two handles that implies rather than straightening what follows.
+ *
+ * `at` is kept strictly inside the two ends: an anchor sharing an end's x is a zero-span segment,
+ * which silently changes the value the evaluator holds past that end.
+ */
+export function insertAnchor(keyframes, at) {
+    const first = keyframes[0];
+    const last = keyframes[keyframes.length - 1];
+    if (first === undefined || last === undefined)
+        return { keyframes, index: 0 };
+    const x = clamp(at.x, first.anchor.x + EDGE_EPSILON, last.anchor.x - EDGE_EPSILON);
+    let index = 0;
+    for (let i = 0; i < keyframes.length - 1; i++)
+        if ((keyframes[i]?.anchor.x ?? 0) <= x)
+            index = i;
+    const subdivided = splitBezierSegment(keyframes, index, x);
+    if (subdivided !== keyframes)
+        return { keyframes: subdivided, index: index + 1 };
+    const held = {
+        anchor: { x, y: clamp(at.y, 0, 1) },
+        interpolation: keyframes[index]?.interpolation ?? 'linear',
+    };
+    // Seeded here as well as at ingestion: this is the other way a Bezier keyframe is born without
+    // its handles, and `x` sits strictly inside the segment, so the insert cannot reorder.
+    const next = withBezierHandles([...keyframes.slice(0, index + 1), held, ...keyframes.slice(index + 1)]);
+    return { keyframes: next, index: index + 1 };
+}
+function point(v, clampToUnit) {
+    if (!isRecord(v) || !isFiniteNumber(v.x) || !isFiniteNumber(v.y))
+        return null;
+    return clampToUnit ? { x: clamp(v.x, 0, 1), y: clamp(v.y, 0, 1) } : { x: v.x, y: v.y };
+}
+const INTERPOLATIONS = ['linear', 'step', 'invertStep', 'bezier'];
+/**
+ * A curve from an untrusted document — a config file or an IPC caller — or null when it
+ * cannot be made into one. Anchors are clamped into the unit square and sorted by x, which is
+ * what `evaluateCurve`'s scan assumes; handle y is left alone, since a control point outside
+ * 0..1 is legitimate and the evaluator clamps its result anyway.
+ */
+export function sanitizeCurve(v) {
+    if (!isRecord(v) || !Array.isArray(v.keyframes))
+        return null;
+    const keyframes = [];
+    for (const raw of v.keyframes) {
+        if (!isRecord(raw))
+            continue;
+        const anchor = point(raw.anchor, true);
+        if (anchor === null)
+            continue;
+        const interpolation = INTERPOLATIONS.find(i => i === raw.interpolation) ?? 'linear';
+        const next = point(raw.next, false);
+        const previous = point(raw.previous, false);
+        keyframes.push({
+            anchor,
+            interpolation,
+            ...(next === null ? {} : { next }),
+            ...(previous === null ? {} : { previous }),
+        });
+    }
+    // One anchor describes no segment, so there is nothing a curve would say that the
+    // binding's own ranges do not.
+    if (keyframes.length < 2)
+        return null;
+    keyframes.sort((a, b) => a.anchor.x - b.anchor.x);
+    // Seeded here rather than only in the editor: this is where curves arrive from disk and from
+    // the plugin API, and a Bezier keyframe that lost its handles there is invisible in both.
+    return { keyframes: withBezierHandles(keyframes) };
+}
+/**
+ * The straight 0..1 line — what a binding without a curve already does, as an editable start.
+ *
+ * No handles: a `linear` keyframe's are never read, and one that outlives the segment it was cut
+ * for is what bends a curve on a mode switch. `withBezierHandles` cuts fresh ones against whatever
+ * the anchors are by then, so Bezier leaves the line where it is and only a drag shapes it.
+ */
+export function identityCurve() {
+    return {
+        keyframes: [
+            { anchor: { x: 0, y: 0 }, interpolation: 'linear' },
+            { anchor: { x: 1, y: 1 }, interpolation: 'linear' },
+        ],
+    };
+}
+export const CURVE_PRESET_IDS = [
+    'linear',
+    'easeIn',
+    'easeOut',
+    'sCurve',
+    'threshold',
+    'steps',
+];
+/**
+ * The shapes VBridger's shipped presets reach for, transcribed from their 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:
+ *
+ * - `easeOut` is its mouth curve (`MouthOpen`, `JawOpen`: out-tangent 2, in-tangent 0) — opens
+ *   twice as fast as linear and saturates; `easeIn` is the mirror.
+ * - `sCurve` is its head-angle curve (`FaceAngle`, `MouthPressLipOpen`: flat ends, slope 2 through
+ *   rest) — twice as sensitive around rest, compressed at the extremes.
+ * - `threshold` and `steps` are what its step lists do, minus the hysteresis and hold: `steps`
+ *   carries the `_Stepped` preset's `MouthOpen` levels (0 / .25 / .5 / 1 at .1 / .5 / .75).
+ */
+export function curvePreset(id) {
+    switch (id) {
+        case 'linear':
+            return identityCurve();
+        case 'easeIn':
+            return {
+                keyframes: [
+                    { anchor: { x: 0, y: 0 }, next: { x: 1 / 3, y: 0 }, interpolation: 'bezier' },
+                    { anchor: { x: 1, y: 1 }, previous: { x: 2 / 3, y: 1 / 3 }, interpolation: 'linear' },
+                ],
+            };
+        case 'easeOut':
+            return {
+                keyframes: [
+                    { anchor: { x: 0, y: 0 }, next: { x: 1 / 3, y: 2 / 3 }, interpolation: 'bezier' },
+                    { anchor: { x: 1, y: 1 }, previous: { x: 2 / 3, y: 1 }, interpolation: 'linear' },
+                ],
+            };
+        case 'sCurve':
+            return {
+                keyframes: [
+                    { anchor: { x: 0, y: 0 }, next: { x: 1 / 3, y: 0 }, interpolation: 'bezier' },
+                    {
+                        anchor: { x: 0.5, y: 0.5 },
+                        previous: { x: 2 / 3, y: 1 / 6 },
+                        next: { x: 1 / 3, y: 5 / 6 },
+                        interpolation: 'bezier',
+                    },
+                    { anchor: { x: 1, y: 1 }, previous: { x: 2 / 3, y: 1 }, interpolation: 'linear' },
+                ],
+            };
+        case 'threshold':
+            return {
+                keyframes: [
+                    { anchor: { x: 0, y: 0 }, interpolation: 'step' },
+                    { anchor: { x: 0.5, y: 1 }, interpolation: 'linear' },
+                    { anchor: { x: 1, y: 1 }, interpolation: 'linear' },
+                ],
+            };
+        case 'steps':
+            return {
+                keyframes: [
+                    { anchor: { x: 0, y: 0 }, interpolation: 'step' },
+                    { anchor: { x: 0.1, y: 0.25 }, interpolation: 'step' },
+                    { anchor: { x: 0.5, y: 0.5 }, interpolation: 'step' },
+                    { anchor: { x: 0.75, y: 1 }, interpolation: 'linear' },
+                    { anchor: { x: 1, y: 1 }, interpolation: 'linear' },
+                ],
+            };
+    }
+}

package/dist/values/labels.js

@@ -12,7 +12,9 @@ const SHORTCUT_ACTION_KIND_LABELS = {
     'effect-toggle': 'Toggle Effect',
     'effect-params': 'Effect Settings',
     'camera-pose': 'Camera Position',
+    'reset-camera': 'Reset Camera',
     'layer-visibility': 'Layer Visibility',
+    'stream-mode': 'Stream Mode',
 };
 /** English label for one shortcut action kind; kinds newer than this SDK read `Action`. */
 export function shortcutActionLabel(kind) {

package/dist/values/limits.d.ts

@@ -40,6 +40,8 @@ export declare const SCENE_EXPOSURE_MAX = 4;
 /** Vertical field of view in degrees; the band either side of a portrait lens, before the framing distorts. */
 export declare const SCENE_FOV_MIN = 10;
 export declare const SCENE_FOV_MAX = 90;
+/** ×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;
 export declare const MTOON_RIM_MAX = 2;
 /** ×0 flattens the Fresnel to a flood fill, ×4 tightens a default power-5 rim to a hairline. */

package/dist/values/limits.js

@@ -55,6 +55,8 @@ export const SCENE_EXPOSURE_MAX = 4;
 /** Vertical field of view in degrees; the band either side of a portrait lens, before the framing distorts. */
 export const SCENE_FOV_MIN = 10;
 export const SCENE_FOV_MAX = 90;
+/** ×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;
 export const MTOON_RIM_MAX = 2;
 /** ×0 flattens the Fresnel to a flood fill, ×4 tightens a default power-5 rim to a hairline. */

package/dist/values/terms.d.ts

@@ -0,0 +1,13 @@
+import type { BindingInput } from '../wire/types.ts';
+/** One weighted input of a binding's sum. `input` is canonical: a twin alias (`JawOpen`) is read as its ARKit id. */
+export interface BindingTerm {
+    input: BindingInput;
+    weight: number;
+}
+/**
+ * The weighted sum of the terms `inputs` carries, or null when it carries none. An absent term
+ * reads as 0 — VBridger's convention for an unset variable — so injecting or scrubbing one input
+ * of a composite binding still drives it. Shared by the stage's rule evaluation and the editor's
+ * curve marker, so both feed the curve the same number.
+ */
+export declare function sumTerms(terms: readonly BindingTerm[], inputs: Partial<Record<string, number>>): number | null;

package/dist/values/terms.js

@@ -0,0 +1,18 @@
+/**
+ * The weighted sum of the terms `inputs` carries, or null when it carries none. An absent term
+ * reads as 0 — VBridger's convention for an unset variable — so injecting or scrubbing one input
+ * of a composite binding still drives it. Shared by the stage's rule evaluation and the editor's
+ * curve marker, so both feed the curve the same number.
+ */
+export function sumTerms(terms, inputs) {
+    let sum = 0;
+    let any = false;
+    for (const t of terms) {
+        const v = inputs[t.input];
+        if (v === undefined)
+            continue;
+        any = true;
+        sum += t.weight * v;
+    }
+    return any ? sum : null;
+}

package/dist/wire/protocol.d.ts

@@ -15,5 +15,17 @@ export declare const CLOSE_SERVER_STOPPING = 1001;
 export declare const INJECT_LEASE_TTL_MS = 1000;
 /** How often {@link PersonaClient.driveParameter} re-sends held leases to keep them alive. */
 export declare const INJECT_HEARTBEAT_MS = 100;
+/**
+ * How often the binding editor's live indicators sample the tracking inputs (~20/s) — both the
+ * stage's push and the editor's poll of it, which must agree. Fast enough to read as live on a
+ * level bar, slow enough that neither the worker port nor the panel relay carries per-frame traffic.
+ */
+export declare const TRACKING_INPUTS_MS = 50;
+/**
+ * How long a scrubbed tracking input holds without being re-sent. The editor re-asserts on its
+ * own timer, so this is pure dead-man's handle: a closed control window, a reload, or a drag
+ * that never gets its pointerup releases the model instead of stranding it.
+ */
+export declare const INPUT_OVERRIDE_TTL_MS = 1000;
 /** Canonical map key for an injection target — JSON framing so ids containing spaces cannot collide. */
 export declare function injectTargetKey(t: InjectTarget): string;

package/dist/wire/protocol.js

@@ -14,6 +14,18 @@ export const CLOSE_SERVER_STOPPING = 1001;
 export const INJECT_LEASE_TTL_MS = 1000;
 /** How often {@link PersonaClient.driveParameter} re-sends held leases to keep them alive. */
 export const INJECT_HEARTBEAT_MS = 100;
+/**
+ * How often the binding editor's live indicators sample the tracking inputs (~20/s) — both the
+ * stage's push and the editor's poll of it, which must agree. Fast enough to read as live on a
+ * level bar, slow enough that neither the worker port nor the panel relay carries per-frame traffic.
+ */
+export const TRACKING_INPUTS_MS = 50;
+/**
+ * How long a scrubbed tracking input holds without being re-sent. The editor re-asserts on its
+ * own timer, so this is pure dead-man's handle: a closed control window, a reload, or a drag
+ * that never gets its pointerup releases the model instead of stranding it.
+ */
+export const INPUT_OVERRIDE_TTL_MS = 1000;
 /** Canonical map key for an injection target — JSON framing so ids containing spaces cannot collide. */
 export function injectTargetKey(t) {
     return JSON.stringify([t.type, t.id, t.instanceId ?? '']);

package/dist/wire/schemas.d.ts

@@ -98,7 +98,6 @@ export declare const requestSchemas: {
     'tracking.addSource': z.ZodObject<{
         kind: z.ZodEnum<{
             "vts-ios": "vts-ios";
-            "vts-ios-native": "vts-ios-native";
             ifacialmocap: "ifacialmocap";
             vmc: "vmc";
         }>;
@@ -157,7 +156,6 @@ export declare const requestSchemas: {
     'tracking.setSource': z.ZodObject<{
         source: z.ZodEnum<{
             "vts-ios": "vts-ios";
-            "vts-ios-native": "vts-ios-native";
             ifacialmocap: "ifacialmocap";
         }>;
     }, z.core.$strip>;

package/dist/wire/schemas.js

@@ -1,7 +1,7 @@
 import * as z from 'zod';
 import { isRecord } from "../values/guards.js";
 import { SPEECH_URL_MAX_LENGTH, STORAGE_KEY_MAX_LENGTH, STORAGE_VALUE_MAX_LENGTH } from "../values/limits.js";
-import { ASSET_KINDS } from "./types.js";
+import { ASSET_KINDS, POSE_SOURCE_IDS, TRACKING_SOURCE_IDS, TRACKING_SOURCE_KINDS } from "./types.js";
 // Runtime validation for the request side of the wire. Schemas exist for the
 // methods whose params the app's main process consumes directly; methods without
 // one are stage-owned — the renderer validates and heals them (same rules as the
@@ -78,7 +78,9 @@ export const requestSchemas = {
     'hotkey.trigger': z.object({ hotkeyId: nonEmpty }),
     'shortcut.trigger': z.object({ shortcutId: nonEmpty }),
     'tracking.addSource': z.object({
-        kind: z.enum(['vts-ios', 'vts-ios-native', 'ifacialmocap', 'vmc']),
+        // Straight off the kind registry, for the same reason as ASSET_KINDS below: a schema
+        // narrower than the constant answers invalid-params for a kind the app itself accepts.
+        kind: z.enum(TRACKING_SOURCE_KINDS),
         name: z.string().optional(),
         phoneIp: nonEmpty.nullable().optional(),
         port: port.optional(),
@@ -97,9 +99,9 @@ export const requestSchemas = {
     'asset.register': z.object({ path: nonEmpty, want: z.enum(ASSET_KINDS).optional() }),
     'settings.patch': z.object({ settings: SettingsPatchSchema }),
     'tracking.setEnabled': z.object({ enabled: z.boolean() }),
-    'tracking.setSource': z.object({ source: z.enum(['vts-ios', 'vts-ios-native', 'ifacialmocap']) }),
+    'tracking.setSource': z.object({ source: z.enum(TRACKING_SOURCE_IDS) }),
     'pose.setEnabled': z.object({ enabled: z.boolean() }),
-    'pose.setSource': z.object({ source: z.enum(['vmc']) }),
+    'pose.setSource': z.object({ source: z.enum(POSE_SOURCE_IDS) }),
     'pose.setPort': z.object({ port }),
     'session.identify': z.object({
         name: z.string().trim().min(1).max(64),

package/dist/wire/types.d.ts

@@ -1,3 +1,4 @@
+import { type ArkitInputName } from '../values/arkit.ts';
 export type ModelFormat = 'live2d' | 'vrm';
 /** Where an item came from: shipped with the app, or added by the user. */
 export type ContentOrigin = 'bundled' | 'user';
@@ -145,6 +146,13 @@ export interface SceneModelItem {
     vrm: VrmPlacement;
     idleAnimation: boolean;
     idleClip: string;
+    /**
+     * Live2D only: the engine's built-in idle breath. Beyond `ParamBreath` it also sways
+     * `ParamAngle*`/`ParamBodyAngleX`, so a rig whose head ranges are tuned tightly may want it off.
+     */
+    breath: boolean;
+    /** Multiplier on the breath's amplitude; 1 is the Cubism sample's own depth. */
+    breathDepth: number;
     /** MToon material fine-tuning, VRM only. */
     mtoon: MToonTuning;
 }
@@ -792,7 +800,7 @@ export interface HotkeyState extends HotkeyConfig {
     registered: string[];
 }
 /** Action kinds an app shortcut can carry today; servers may send kinds newer than this list. */
-export declare const SHORTCUT_ACTION_KINDS: readonly ["effect-toggle", "effect-params", "camera-pose", "layer-visibility"];
+export declare const SHORTCUT_ACTION_KINDS: readonly ["effect-toggle", "effect-params", "camera-pose", "reset-camera", "layer-visibility", "stream-mode"];
 export type ShortcutActionKind = (typeof SHORTCUT_ACTION_KINDS)[number];
 /**
  * One app-level global shortcut (a multi-action macro) as clients see it. Action
@@ -818,7 +826,7 @@ export interface ExpressionPersistence {
 export type JsonValue = string | number | boolean | null | JsonValue[] | {
     [key: string]: JsonValue;
 };
-export declare const TRACKING_SOURCE_IDS: readonly ["vts-ios", "vts-ios-native", "ifacialmocap"];
+export declare const TRACKING_SOURCE_IDS: readonly ["vts-ios", "ifacialmocap"];
 export type TrackingSourceId = (typeof TRACKING_SOURCE_IDS)[number];
 /** Body-pose protocols. Every one so far is UDP with a configurable port. */
 export declare const POSE_SOURCE_IDS: readonly ["vmc"];
@@ -826,7 +834,7 @@ export type PoseSourceId = (typeof POSE_SOURCE_IDS)[number];
 export type TrackingStatus = 'off' | 'waiting' | 'tracking' | 'no-face';
 export type PoseStatus = 'off' | 'waiting' | 'tracking';
 /** Every protocol a tracking source instance can speak; face kinds plus the body (vmc) kind. */
-export declare const TRACKING_SOURCE_KINDS: readonly ["vts-ios", "vts-ios-native", "ifacialmocap", "vmc"];
+export declare const TRACKING_SOURCE_KINDS: readonly ["vts-ios", "ifacialmocap", "vmc"];
 export type TrackingSourceKind = (typeof TRACKING_SOURCE_KINDS)[number];
 /** Whether a source kind feeds the face channel (vmc is the body channel). */
 export declare function isFaceSourceKind(kind: TrackingSourceKind): kind is TrackingSourceId;
@@ -897,9 +905,43 @@ export interface SettingsPatch {
         effectsQuality?: EffectsQuality;
     };
 }
-/** VTS's input vocabulary plus the VBridger-standard extras — the valid `id`s for `input` inject targets (and the names a model's `.vtube.json` references). */
-export declare const INPUT_NAMES: readonly ["FaceAngleX", "FaceAngleY", "FaceAngleZ", "FacePositionX", "FacePositionY", "FacePositionZ", "EyeOpenLeft", "EyeOpenRight", "EyeLeftX", "EyeLeftY", "EyeRightX", "EyeRightY", "Brows", "BrowLeftY", "BrowRightY", "MouthSmile", "MouthOpen", "MouthX", "CheekPuff", "JawOpen", "JawX", "TongueOut", "MouthPucker", "MouthFunnel", "MouthShrug", "MouthPress", "MouthPressLipOpen"];
-export type InputName = (typeof INPUT_NAMES)[number];
+/** VTS's input vocabulary, plus `JawOpen` — the derived half of {@link INPUT_NAMES}. */
+declare const VTS_INPUT_NAMES: readonly ["FaceAngleX", "FaceAngleY", "FaceAngleZ", "FacePositionX", "FacePositionY", "FacePositionZ", "EyeOpenLeft", "EyeOpenRight", "EyeLeftX", "EyeLeftY", "EyeRightX", "EyeRightY", "Brows", "BrowLeftY", "BrowRightY", "MouthSmile", "MouthOpen", "MouthX", "CheekPuff", "JawOpen", "TongueOut"];
+type VtsInputName = (typeof VTS_INPUT_NAMES)[number];
+/**
+ * The valid `id`s for `input` inject targets, and the names a model's `.vtube.json`
+ * references: VTS's derived vocabulary plus every raw ARKit channel.
+ */
+export declare const INPUT_NAMES: readonly InputName[];
+export type InputName = VtsInputName | ArkitInputName;
+/** Whether an untrusted string names a tracking input — the guard every wire boundary needs. */
+export declare function isInputName(v: string): v is InputName;
+/**
+ * VTS-vocabulary inputs that are the same float as one raw ARKit channel (the desktop derives
+ * exactly these three verbatim; everything else it averages, floors or gains). Either id is
+ * accepted on the wire and in files, and both are read as the ARKit one.
+ */
+export declare const ARKIT_TWINS: {
+    readonly JawOpen: "ARKitJawOpen";
+    readonly TongueOut: "ARKitTongueOut";
+    readonly CheekPuff: "ARKitCheekPuff";
+};
+/** A wire alias in {@link ARKIT_TWINS}. */
+type ArkitTwinAlias = keyof typeof ARKIT_TWINS;
+/**
+ * What a binding may read: every input but the three wire aliases in `ARKIT_TWINS`, which are
+ * read as their ARKit twin. Rules, and the editor's rows, are typed over this.
+ */
+export type BindingInput = Exclude<InputName, ArkitTwinAlias>;
+/** {@link INPUT_NAMES} minus the aliases, in the same order. */
+export declare const BINDING_INPUT_NAMES: readonly BindingInput[];
+/** The id an input is read as: its ARKit twin when it has one, else itself. */
+export declare function arkitTwinOf(input: InputName): BindingInput;
+/**
+ * Each input's natural span — the units a sender should write, and the input range a new
+ * binding starts from. Head angles are **degrees**; the rest are unitless.
+ */
+export declare const INPUT_RANGES: Record<InputName, readonly [number, number]>;
 /**
  * What an injected value drives:
  * - `input` — a VTS-vocabulary tracking input (`MouthOpen`, `FaceAngleX`, …), mapped
@@ -920,3 +962,4 @@ export interface InjectEntry extends InjectTarget {
     /** 0..1 blend over whatever else drives the parameter; default 1. */
     weight?: number;
 }
+export {};

package/dist/wire/types.js

@@ -1,6 +1,7 @@
 // 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.
+import { ARKIT_INPUT_NAMES } from "../values/arkit.js";
 /**
  * How a registered file is labelled. Wider than an object's content kinds: `.hdr` is only
  * ever an environment map, and a `.vmd` splits by content — `cameraMotion` for one that
@@ -28,9 +29,16 @@ export function isAppCapability(v) {
 }
 // ---- App shortcuts --------------------------------------------------------------
 /** Action kinds an app shortcut can carry today; servers may send kinds newer than this list. */
-export const SHORTCUT_ACTION_KINDS = ['effect-toggle', 'effect-params', 'camera-pose', 'layer-visibility'];
+export const SHORTCUT_ACTION_KINDS = [
+    'effect-toggle',
+    'effect-params',
+    'camera-pose',
+    'reset-camera',
+    'layer-visibility',
+    'stream-mode',
+];
 // ---- Settings ------------------------------------------------------------------
-export const TRACKING_SOURCE_IDS = ['vts-ios', 'vts-ios-native', 'ifacialmocap'];
+export const TRACKING_SOURCE_IDS = ['vts-ios', 'ifacialmocap'];
 /** Body-pose protocols. Every one so far is UDP with a configurable port. */
 export const POSE_SOURCE_IDS = ['vmc'];
 /** Every protocol a tracking source instance can speak; face kinds plus the body (vmc) kind. */
@@ -46,8 +54,8 @@ export const EFFECTS_QUALITY_LEVELS = ['low', 'medium', 'high'];
  */
 export const FPS_LIMIT_PRESETS = [0, 15, 30, 60, 90];
 // ---- Injection -----------------------------------------------------------------
-/** VTS's input vocabulary plus the VBridger-standard extras — the valid `id`s for `input` inject targets (and the names a model's `.vtube.json` references). */
-export const INPUT_NAMES = [
+/** VTS's input vocabulary, plus `JawOpen` — the derived half of {@link INPUT_NAMES}. */
+const VTS_INPUT_NAMES = [
     'FaceAngleX',
     'FaceAngleY',
     'FaceAngleZ',
@@ -68,11 +76,81 @@ export const INPUT_NAMES = [
     'MouthX',
     'CheekPuff',
     'JawOpen',
-    'JawX',
     'TongueOut',
-    'MouthPucker',
-    'MouthFunnel',
-    'MouthShrug',
-    'MouthPress',
-    'MouthPressLipOpen',
 ];
+/**
+ * The valid `id`s for `input` inject targets, and the names a model's `.vtube.json`
+ * references: VTS's derived vocabulary plus every raw ARKit channel.
+ */
+export const INPUT_NAMES = [...VTS_INPUT_NAMES, ...ARKIT_INPUT_NAMES];
+const INPUT_NAME_SET = new Set(INPUT_NAMES);
+/** Whether an untrusted string names a tracking input — the guard every wire boundary needs. */
+export function isInputName(v) {
+    return INPUT_NAME_SET.has(v);
+}
+/**
+ * VTS-vocabulary inputs that are the same float as one raw ARKit channel (the desktop derives
+ * exactly these three verbatim; everything else it averages, floors or gains). Either id is
+ * accepted on the wire and in files, and both are read as the ARKit one.
+ */
+export const ARKIT_TWINS = {
+    JawOpen: 'ARKitJawOpen',
+    TongueOut: 'ARKitTongueOut',
+    CheekPuff: 'ARKitCheekPuff',
+};
+const TWIN_ALIASES = new Set(Object.keys(ARKIT_TWINS));
+/** Whether an input id is one of the {@link ARKIT_TWINS} aliases. */
+function isArkitTwinAlias(v) {
+    return TWIN_ALIASES.has(v);
+}
+/** {@link INPUT_NAMES} minus the aliases, in the same order. */
+export const BINDING_INPUT_NAMES = INPUT_NAMES.filter(n => !isArkitTwinAlias(n));
+/** The id an input is read as: its ARKit twin when it has one, else itself. */
+export function arkitTwinOf(input) {
+    return isArkitTwinAlias(input) ? ARKIT_TWINS[input] : input;
+}
+/**
+ * From VTS's own registry (`FaceTrackingParamInfo.paramNameDictionary`), which is both the
+ * range its editor seeds a new parameter with and what every `.vtube.json` was authored
+ * against. Two families differ deliberately:
+ *
+ * - **the brow inputs** are signed here. VTS lists them `0..1`; we derive them as
+ *   `brow-up − brow-down`, so a frown needs the lower half.
+ * - **`JawOpen`** is absent from VTS's registry — it exists there only as a plugin-created
+ *   parameter, which VTS then special-cases — so its span is the ARKit channel's.
+ */
+const VTS_INPUT_RANGES = {
+    FaceAngleX: [-30, 30],
+    FaceAngleY: [-30, 30],
+    FaceAngleZ: [-90, 90],
+    FacePositionX: [-15, 15],
+    FacePositionY: [-15, 15],
+    FacePositionZ: [-10, 10],
+    EyeOpenLeft: [0, 1],
+    EyeOpenRight: [0, 1],
+    EyeLeftX: [-1, 1],
+    EyeLeftY: [-1, 1],
+    EyeRightX: [-1, 1],
+    EyeRightY: [-1, 1],
+    Brows: [-1, 1],
+    BrowLeftY: [-1, 1],
+    BrowRightY: [-1, 1],
+    MouthSmile: [0, 1],
+    MouthOpen: [0, 1],
+    MouthX: [-1, 1],
+    CheekPuff: [0, 1],
+    JawOpen: [0, 1],
+    TongueOut: [0, 1],
+};
+/** ARKit blendshapes are unit-scale by definition, so every raw channel shares one span. */
+const ARKIT_RANGE = [0, 1];
+/**
+ * Each input's natural span — the units a sender should write, and the input range a new
+ * binding starts from. Head angles are **degrees**; the rest are unitless.
+ */
+export const INPUT_RANGES = {
+    ...VTS_INPUT_RANGES,
+    // `fromEntries` widens the key type back to `string`; the annotation above is what keeps
+    // this exhaustive, and it fails to typecheck if a name ever lacks a range.
+    ...Object.fromEntries(ARKIT_INPUT_NAMES.map(n => [n, ARKIT_RANGE])),
+};

package/package.json

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