@laplace.live/persona-sdk 1.19.0 → 1.21.0

package/dist/index.d.ts

@@ -17,10 +17,12 @@ export * from './values/limits.ts';
 export * from './values/lipsync.ts';
 export * from './values/locale.ts';
 export * from './values/model-info.ts';
+export * from './values/model-movement.ts';
 export * from './values/mouse.ts';
 export * from './values/scene-transition.ts';
 export * from './values/stage-info.ts';
 export * from './values/terms.ts';
+export * from './values/time.ts';
 export * from './values/volumetric-lighting.ts';
 export * from './values/vrm-bindings.ts';
 export * from './wire/envelope.ts';

package/dist/index.js

@@ -19,10 +19,12 @@ export * from "./values/limits.js";
 export * from "./values/lipsync.js";
 export * from "./values/locale.js";
 export * from "./values/model-info.js";
+export * from "./values/model-movement.js";
 export * from "./values/mouse.js";
 export * from "./values/scene-transition.js";
 export * from "./values/stage-info.js";
 export * from "./values/terms.js";
+export * from "./values/time.js";
 export * from "./values/volumetric-lighting.js";
 export * from "./values/vrm-bindings.js";
 export * from "./wire/envelope.js";

package/dist/values/curve.d.ts

@@ -18,8 +18,8 @@ export interface Keyframe {
     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.
+     * anchor, 1 = its right), `y` is absolute — nizima's format. Because `y` stays put when its
+     * anchor moves, an editor drag has to carry the handles itself (`dragAnchor`), or the point kinks.
      */
     next?: Point;
     previous?: Point;
@@ -61,8 +61,9 @@ export interface CurveHandle extends Point {
     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.
+ * The keyframe's handles, in curve coordinates — its outgoing one when it governs a Bezier
+ * segment, its incoming one when the keyframe before it does. A sharp point's are retracted onto
+ * it and still reported; `extendedHandles` is what an editor draws.
  *
  * `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
@@ -70,6 +71,8 @@ export interface CurveHandle extends Point {
  * legitimate overshoot at the wrong height.
  */
 export declare function handlesFor(keyframes: Keyframe[], index: number): CurveHandle[];
+/** The keyframe's handles an editor draws and lets you grab: a retracted one has nothing to grab. */
+export declare function extendedHandles(keyframes: Keyframe[], index: number): CurveHandle[];
 /**
  * How far an anchor may travel in x, as `[lo, hi]`.
  *
@@ -81,6 +84,31 @@ export declare function handlesFor(keyframes: Keyframe[], index: number): CurveH
  * 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];
+/**
+ * The anchor at `index` moved to `to`, held within `anchorBounds` and the plot, carrying its own
+ * handles as a pen tool does, so the curve leaves and arrives at it in the same directions: a
+ * smooth point stays smooth, a corner keeps its angle. The neighbours' handles keep their
+ * fractions, so the segments either side stretch rather than re-aim.
+ */
+export declare function dragAnchor(keyframes: Keyframe[], index: number, to: Point): Keyframe[];
+/**
+ * The `side` handle of the anchor at `index` moved to `to`. On a smooth point the other handle
+ * turns to stay in line, keeping its length — a pen tool's default — unless `independent`, which
+ * moves this one alone and leaves a corner. `to` is held within the segment the handle shapes,
+ * where `handleX` reads it, and on the plot, where it can be found again; a stored overshoot still
+ * reads back. The turned handle is shortened to fit its own.
+ */
+export declare function dragHandle(keyframes: Keyframe[], index: number, side: HandleSide, to: Point, independent: boolean): Keyframe[];
+/**
+ * A pen tool's convert-point click on the interior anchor at `index`: a smooth point turns sharp,
+ * anything else turns smooth. Beside a step there is nothing to be in line with, so a point there is
+ * smooth while its one handle is out. Sharp retracts the handles onto the anchor, so no curve bends
+ * at it. Smooth aims them through the neighbours — flat at a peak or valley, so the curve cannot
+ * overshoot the neighbour it turns at — a third of the way along each segment, and a linear side
+ * becomes Bezier with its far handle on the old line, so the neighbour's end keeps its direction.
+ * Step sides are left as they are. Returns **the input array itself** when it declines.
+ */
+export declare function toggleSmooth(keyframes: Keyframe[], index: number): Keyframe[];
 /**
  * Every Bezier segment carries both handles, seeded collinear unless it already has both.
  *
@@ -146,13 +174,18 @@ export declare const INTERPOLATIONS: readonly ["linear", "step", "invertStep", "
  */
 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.
+ * The straight 0..1 line — what a binding without a curve already does — as the Linear preset.
  *
  * 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;
+/**
+ * The same straight line as one Bezier segment, handles on the line at the thirds — what a new
+ * curve starts as, so a point clicked into it splits smooth and a drag bends it rather than kinking.
+ */
+export declare function bezierIdentityCurve(): Curve;
 /** A ready-made response shape that replaces the whole curve; `linear` is the identity. */
 export type CurvePresetId = (typeof CURVE_PRESET_IDS)[number];
 export declare const CURVE_PRESET_IDS: readonly ["linear", "step", "invertStep", "bezier", "easeIn", "easeOut", "sCurve", "threshold", "steps"];

package/dist/values/curve.js

@@ -92,8 +92,9 @@ export function evaluateCurve(curve, x) {
     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.
+ * The keyframe's handles, in curve coordinates — its outgoing one when it governs a Bezier
+ * segment, its incoming one when the keyframe before it does. A sharp point's are retracted onto
+ * it and still reported; `extendedHandles` is what an editor draws.
  *
  * `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
@@ -117,6 +118,15 @@ export function handlesFor(keyframes, index) {
     }
     return out;
 }
+/** Below this length a handle is retracted onto its anchor, as a sharp point's are. */
+const RETRACTED = 1e-9;
+/** The keyframe's handles an editor draws and lets you grab: a retracted one has nothing to grab. */
+export function extendedHandles(keyframes, index) {
+    const anchor = keyframes[index]?.anchor;
+    if (anchor === undefined)
+        return [];
+    return handlesFor(keyframes, index).filter(h => Math.hypot(h.x - anchor.x, h.y - anchor.y) > RETRACTED);
+}
 /**
  * How far an anchor may travel in x, as `[lo, hi]`.
  *
@@ -133,7 +143,143 @@ export function anchorBounds(keyframes, index) {
         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];
+    const lo = keyframes[index - 1]?.anchor.x ?? 0;
+    const hi = keyframes[index + 1]?.anchor.x ?? 1;
+    // Clicks in one column stack anchors on the curve; neighbours too close for the margin meet halfway.
+    const edge = Math.min(EDGE_EPSILON, (hi - lo) / 2);
+    return [lo + edge, hi - edge];
+}
+/**
+ * The handle at `anchor + s·offset` for the largest `s` in 0..1 inside the box, stored against
+ * `xs`, its segment's span: a handle out of room is shortened along its own direction, so a
+ * smooth point stays smooth.
+ */
+function fitHandle(anchor, offset, xs, ys) {
+    let s = 1;
+    if (offset.x > 0)
+        s = Math.min(s, (xs[1] - anchor.x) / offset.x);
+    if (offset.x < 0)
+        s = Math.min(s, (xs[0] - anchor.x) / offset.x);
+    if (offset.y > 0)
+        s = Math.min(s, (ys[1] - anchor.y) / offset.y);
+    if (offset.y < 0)
+        s = Math.min(s, (ys[0] - anchor.y) / offset.y);
+    s = Math.max(0, s);
+    return { x: handleFraction(xs[0], xs[1], anchor.x + offset.x * s), y: anchor.y + offset.y * s };
+}
+/** Where an authored handle may sit in y: on the plot, or no further out than a stored overshoot. */
+function heightsFor(y) {
+    return [Math.min(0, y), Math.max(1, y)];
+}
+/** Two handles in line through their anchor, on opposite sides of it: a smooth point. */
+function inLine(anchor, a, b) {
+    const u = { x: a.x - anchor.x, y: a.y - anchor.y };
+    const v = { x: b.x - anchor.x, y: b.y - anchor.y };
+    const lu = Math.hypot(u.x, u.y);
+    const lv = Math.hypot(v.x, v.y);
+    if (lu <= RETRACTED || lv <= RETRACTED)
+        return false;
+    return u.x * v.x + u.y * v.y < 0 && Math.abs(u.x * v.y - u.y * v.x) <= 1e-3 * lu * lv;
+}
+/**
+ * The anchor at `index` moved to `to`, held within `anchorBounds` and the plot, carrying its own
+ * handles as a pen tool does, so the curve leaves and arrives at it in the same directions: a
+ * smooth point stays smooth, a corner keeps its angle. The neighbours' handles keep their
+ * fractions, so the segments either side stretch rather than re-aim.
+ */
+export function dragAnchor(keyframes, index, to) {
+    const held = keyframes[index];
+    if (held === undefined)
+        return keyframes;
+    const [lo, hi] = anchorBounds(keyframes, index);
+    const at = { x: clamp(to.x, lo, hi), y: clamp(to.y, 0, 1) };
+    const moved = { ...held, anchor: at };
+    for (const h of handlesFor(keyframes, index)) {
+        const span = h.side === 'next' ? [at.x, h.span[1]] : [h.span[0], at.x];
+        moved[h.side] = fitHandle(at, { x: h.x - held.anchor.x, y: h.y - held.anchor.y }, span, heightsFor(h.y));
+    }
+    return keyframes.map((k, i) => (i === index ? moved : k));
+}
+/**
+ * The `side` handle of the anchor at `index` moved to `to`. On a smooth point the other handle
+ * turns to stay in line, keeping its length — a pen tool's default — unless `independent`, which
+ * moves this one alone and leaves a corner. `to` is held within the segment the handle shapes,
+ * where `handleX` reads it, and on the plot, where it can be found again; a stored overshoot still
+ * reads back. The turned handle is shortened to fit its own.
+ */
+export function dragHandle(keyframes, index, side, to, independent) {
+    const held = keyframes[index];
+    const handles = handlesFor(keyframes, index);
+    const dragged = handles.find(h => h.side === side);
+    if (held === undefined || dragged === undefined)
+        return keyframes;
+    const at = { x: clamp(to.x, dragged.span[0], dragged.span[1]), y: clamp(to.y, 0, 1) };
+    const moved = { ...held };
+    moved[side] = { x: handleFraction(dragged.span[0], dragged.span[1], at.x), y: at.y };
+    const other = handles.find(h => h.side !== side);
+    const a = held.anchor;
+    const reach = Math.hypot(at.x - a.x, at.y - a.y);
+    if (!independent && other !== undefined && reach > 0 && inLine(a, dragged, other)) {
+        const keep = Math.hypot(other.x - a.x, other.y - a.y) / reach;
+        const away = { x: (a.x - at.x) * keep, y: (a.y - at.y) * keep };
+        moved[other.side] = fitHandle(a, away, other.span, heightsFor(other.y));
+    }
+    return keyframes.map((k, i) => (i === index ? moved : k));
+}
+/**
+ * A pen tool's convert-point click on the interior anchor at `index`: a smooth point turns sharp,
+ * anything else turns smooth. Beside a step there is nothing to be in line with, so a point there is
+ * smooth while its one handle is out. Sharp retracts the handles onto the anchor, so no curve bends
+ * at it. Smooth aims them through the neighbours — flat at a peak or valley, so the curve cannot
+ * overshoot the neighbour it turns at — a third of the way along each segment, and a linear side
+ * becomes Bezier with its far handle on the old line, so the neighbour's end keeps its direction.
+ * Step sides are left as they are. Returns **the input array itself** when it declines.
+ */
+export function toggleSmooth(keyframes, index) {
+    const before = keyframes[index - 1];
+    const held = keyframes[index];
+    const after = keyframes[index + 1];
+    if (before === undefined || held === undefined || after === undefined)
+        return keyframes;
+    // A step side has no curve to aim; a linear one turns Bezier below.
+    const smoothIn = before.interpolation === 'linear' || before.interpolation === 'bezier';
+    const smoothOut = held.interpolation === 'linear' || held.interpolation === 'bezier';
+    if (!smoothIn && !smoothOut)
+        return keyframes;
+    const a = held.anchor;
+    const handles = handlesFor(keyframes, index);
+    const incoming = handles.find(h => h.side === 'previous');
+    const outgoing = handles.find(h => h.side === 'next');
+    const out = [...keyframes];
+    const isSmooth = smoothIn && smoothOut
+        ? incoming !== undefined && outgoing !== undefined && inLine(a, incoming, outgoing)
+        : extendedHandles(keyframes, index).length > 0;
+    if (isSmooth) {
+        const sharp = { ...held };
+        if (incoming !== undefined)
+            sharp.previous = { x: 1, y: a.y };
+        if (outgoing !== undefined)
+            sharp.next = { x: 0, y: a.y };
+        out[index] = sharp;
+        return out;
+    }
+    const l = before.anchor;
+    const r = after.anchor;
+    const slope = (a.y - l.y) * (r.y - a.y) > 0 ? (r.y - l.y) / (r.x - l.x) : 0;
+    const smooth = { ...held };
+    if (before.interpolation === 'linear') {
+        out[index - 1] = { ...before, interpolation: 'bezier', next: { x: 1 / 3, y: lerp(l.y, a.y, 1 / 3) } };
+    }
+    if (smoothIn)
+        smooth.previous = fitHandle(a, { x: (l.x - a.x) / 3, y: (slope * (l.x - a.x)) / 3 }, [l.x, a.x], [0, 1]);
+    if (held.interpolation === 'linear') {
+        smooth.interpolation = 'bezier';
+        out[index + 1] = { ...after, previous: { x: 2 / 3, y: lerp(a.y, r.y, 2 / 3) } };
+    }
+    if (smoothOut)
+        smooth.next = fitHandle(a, { x: (r.x - a.x) / 3, y: (slope * (r.x - a.x)) / 3 }, [a.x, r.x], [0, 1]);
+    out[index] = smooth;
+    return out;
 }
 /**
  * Every Bezier segment carries both handles, seeded collinear unless it already has both.
@@ -308,7 +454,7 @@ export function sanitizeCurve(v) {
     return { keyframes: withBezierHandles(keyframes) };
 }
 /**
- * The straight 0..1 line — what a binding without a curve already does, as an editable start.
+ * The straight 0..1 line — what a binding without a curve already does — as the Linear preset.
  *
  * 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
@@ -322,6 +468,18 @@ export function identityCurve() {
         ],
     };
 }
+/**
+ * The same straight line as one Bezier segment, handles on the line at the thirds — what a new
+ * curve starts as, so a point clicked into it splits smooth and a drag bends it rather than kinking.
+ */
+export function bezierIdentityCurve() {
+    return {
+        keyframes: withBezierHandles([
+            { anchor: { x: 0, y: 0 }, interpolation: 'bezier' },
+            { anchor: { x: 1, y: 1 }, interpolation: 'linear' },
+        ]),
+    };
+}
 export const CURVE_PRESET_IDS = [
     'linear',
     'step',

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

@@ -11,6 +11,7 @@ export declare const EFFECT_SCOPES: {
     readonly blur: readonly ["scene", "layer"];
     readonly bloom: readonly ["scene", "layer"];
     readonly diffusion: readonly ["scene", "layer"];
+    readonly sketch: readonly ["scene", "layer"];
     readonly dof: readonly ["scene"];
     readonly chromaticAberration: readonly ["scene"];
     readonly grain: readonly ["scene"];

package/dist/values/effect-schema.js

@@ -13,6 +13,7 @@ export const EFFECT_SCOPES = {
     blur: ['scene', 'layer'],
     bloom: ['scene', 'layer'],
     diffusion: ['scene', 'layer'],
+    sketch: ['scene', 'layer'],
     dof: ['scene'],
     chromaticAberration: ['scene'],
     grain: ['scene'],
@@ -165,6 +166,15 @@ export const EFFECT_SPECS = {
         radius: { default: 0.85, min: 0, max: 1, step: 0.01 },
         threshold: { default: 0.35, min: 0, max: 1, step: 0.01 },
     },
+    sketch: {
+        lines: { default: 1, min: 0, max: 2, step: 0.01 },
+        lineWidth: { default: 1, min: 0.5, max: 4, step: 0.1, digits: 1, unit: 'px' },
+        // 1 is the source's density; above it the grain packs toward solid graphite.
+        shading: { default: 1, min: 0, max: 2, step: 0.01 },
+        softness: { default: 1, min: 0, max: 1, step: 0.01 },
+        saturation: { default: 0, min: 0, max: 1, step: 0.01 },
+        opacity: { default: 1, 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. */
@@ -303,6 +313,10 @@ export const EFFECT_COLOR_SPECS = {
     outline: {
         color: { default: '#000000' },
     },
+    // The mean of the source demo's kraft paper photo.
+    sketch: {
+        paperColor: { default: '#b69b83' },
+    },
     dropShadow: {
         color: { default: '#000000' },
     },
@@ -315,6 +329,7 @@ export const EFFECT_BOOLEAN_SPECS = {
         transparentBackground: { default: false },
     },
     blur: { highQuality: { default: false } },
+    sketch: { paperBackground: { default: false } },
     bloom: {
         selectColors: { default: false },
         invertColors: { default: false },
@@ -435,6 +450,7 @@ export const ALL_EFFECT_STACK_ORDER = [
     'chromaticAberration',
     'bloom',
     'diffusion',
+    'sketch',
     'color',
     'levels',
     'colorWheels',

package/dist/values/limits.d.ts

@@ -212,6 +212,19 @@ export declare function pinnableParents(models: readonly {
     name: string;
     ridesThis: boolean;
 }[];
+/**
+ * Whether pinning puts an item inside its Live2D host's ArtMesh stack, where `attach.depth` places
+ * it: a Live2D item, or a 2D object as one quad. A 3D object only ever paints in front.
+ */
+export declare function pinEntersStack(item: {
+    kind: 'model';
+    ref: {
+        kind: ModelFormat;
+    };
+} | {
+    kind: 'object';
+    space: ObjectSpace;
+}): boolean;
 /**
  * The depth control's stops, back to front: behind the model, above each of its ArtMeshes in
  * paint order, then in front of it all. One continuous run, so depth is a slider over the host's
@@ -254,5 +267,7 @@ export declare const OUTLINER_DEFAULT_WIDTH = 288;
  * split must fit inside it, or no layout satisfies both floors and the group clips instead.
  */
 export declare const TWO_COLUMN_WIDTH = 672;
+/** Colors a color picker keeps saved — two rows of its swatch grid; saving more waits for a removal. */
+export declare const SAVED_COLORS_MAX = 12;
 /** 3D-stage resolution multipliers offered by both performance pickers. */
 export declare const RENDER_SCALE_PRESETS: readonly [1, 0.85, 0.75, 0.66, 0.5];

package/dist/values/limits.js

@@ -343,6 +343,13 @@ export function pinnableParents(models, items, instanceId) {
     }
     return out;
 }
+/**
+ * Whether pinning puts an item inside its Live2D host's ArtMesh stack, where `attach.depth` places
+ * it: a Live2D item, or a 2D object as one quad. A 3D object only ever paints in front.
+ */
+export function pinEntersStack(item) {
+    return item.kind === 'model' ? item.ref.kind === 'live2d' : item.space === '2d';
+}
 /**
  * The depth control's stops, back to front: behind the model, above each of its ArtMeshes in
  * paint order, then in front of it all. One continuous run, so depth is a slider over the host's
@@ -411,5 +418,7 @@ export const OUTLINER_DEFAULT_WIDTH = 288;
  * split must fit inside it, or no layout satisfies both floors and the group clips instead.
  */
 export const TWO_COLUMN_WIDTH = 672;
+/** Colors a color picker keeps saved — two rows of its swatch grid; saving more waits for a removal. */
+export const SAVED_COLORS_MAX = 12;
 /** 3D-stage resolution multipliers offered by both performance pickers. */
 export const RENDER_SCALE_PRESETS = [1, 0.85, 0.75, 0.66, 0.5];

package/dist/values/model-movement.d.ts

@@ -0,0 +1,29 @@
+/**
+ * VTube Studio's Movement Config: how far tracked face position slides (`x`, `y`) and scales (`z`)
+ * a whole Live2D model. It moves the model itself and never writes a parameter, so it stacks with
+ * a rig that binds `FacePositionZ` to a parameter of its own. Amounts are signed — a negative one
+ * inverts its axis, 0 switches it off.
+ */
+export interface ModelMovementConfig {
+    enabled: boolean;
+    x: number;
+    y: number;
+    z: number;
+    /** Smoothing levels 0–100, read once when the model loads; file-only, as in VTS. */
+    smoothingX: number;
+    smoothingY: number;
+    smoothingZ: number;
+}
+/** VTS's slider limit (`MAX_MOVEMENT`): an edited amount is a whole number within ±20. */
+export declare const MODEL_MOVEMENT_MAX = 20;
+/** VTS's `ModelPositionMovement` field initializers — a model nobody configured moves by default. */
+export declare const DEFAULT_MODEL_MOVEMENT: Readonly<ModelMovementConfig>;
+/**
+ * A stored or relayed configuration, read per field over the defaults. Amounts are taken as
+ * written: VTS clamps its sliders to ±20, never what a file holds.
+ */
+export declare function healModelMovement(raw: unknown): ModelMovementConfig;
+/** What the Movement Config editor changes; a file's smoothing levels are left as they are. */
+export type ModelMovementEdit = Partial<Pick<ModelMovementConfig, 'enabled' | 'x' | 'y' | 'z'>>;
+/** An edit healed to the editor's limits; an absent or unusable field is dropped, not defaulted. */
+export declare function healModelMovementEdit(raw: unknown): ModelMovementEdit;

package/dist/values/model-movement.js

@@ -0,0 +1,44 @@
+import { finiteOr, isFiniteNumber, isRecord } from "./guards.js";
+import { clamp } from "./limits.js";
+/** VTS's slider limit (`MAX_MOVEMENT`): an edited amount is a whole number within ±20. */
+export const MODEL_MOVEMENT_MAX = 20;
+/** VTS's `ModelPositionMovement` field initializers — a model nobody configured moves by default. */
+export const DEFAULT_MODEL_MOVEMENT = {
+    enabled: true,
+    x: 6,
+    y: 8,
+    z: 11,
+    smoothingX: 10,
+    smoothingY: 10,
+    smoothingZ: 10,
+};
+/**
+ * A stored or relayed configuration, read per field over the defaults. Amounts are taken as
+ * written: VTS clamps its sliders to ±20, never what a file holds.
+ */
+export function healModelMovement(raw) {
+    const r = isRecord(raw) ? raw : {};
+    const d = DEFAULT_MODEL_MOVEMENT;
+    return {
+        enabled: typeof r.enabled === 'boolean' ? r.enabled : d.enabled,
+        x: finiteOr(r.x, d.x),
+        y: finiteOr(r.y, d.y),
+        z: finiteOr(r.z, d.z),
+        smoothingX: finiteOr(r.smoothingX, d.smoothingX),
+        smoothingY: finiteOr(r.smoothingY, d.smoothingY),
+        smoothingZ: finiteOr(r.smoothingZ, d.smoothingZ),
+    };
+}
+/** An edit healed to the editor's limits; an absent or unusable field is dropped, not defaulted. */
+export function healModelMovementEdit(raw) {
+    const r = isRecord(raw) ? raw : {};
+    const edit = {};
+    if (typeof r.enabled === 'boolean')
+        edit.enabled = r.enabled;
+    for (const axis of ['x', 'y', 'z']) {
+        const v = r[axis];
+        if (isFiniteNumber(v))
+            edit[axis] = clamp(Math.round(v), -MODEL_MOVEMENT_MAX, MODEL_MOVEMENT_MAX);
+    }
+    return edit;
+}

package/dist/values/time.d.ts

@@ -0,0 +1,9 @@
+/** Desktop local wall-clock time, normalized over a repeating 24-hour or 12-hour cycle. */
+export declare const TIME_INPUT_RANGES: {
+    readonly Time24h: readonly [0, 1];
+    readonly Time12h: readonly [0, 1];
+};
+export type TimeInputName = keyof typeof TIME_INPUT_RANGES;
+export type TimeInputs = Readonly<Record<TimeInputName, number>>;
+export declare const TIME_INPUT_NAMES: readonly TimeInputName[];
+export declare function isTimeInputName(v: string): v is TimeInputName;

package/dist/values/time.js

@@ -0,0 +1,11 @@
+import { keysOf } from "./guards.js";
+/** Desktop local wall-clock time, normalized over a repeating 24-hour or 12-hour cycle. */
+export const TIME_INPUT_RANGES = {
+    Time24h: [0, 1],
+    Time12h: [0, 1],
+};
+export const TIME_INPUT_NAMES = keysOf(TIME_INPUT_RANGES);
+const TIME_INPUT_SET = new Set(TIME_INPUT_NAMES);
+export function isTimeInputName(v) {
+    return TIME_INPUT_SET.has(v);
+}

package/dist/wire/events.d.ts

@@ -1,3 +1,4 @@
+import type { ModelMovementConfig } from '../values/model-movement.ts';
 import type { AutomationInfo, ExpressionPersistence, HotkeyState, ModelFormat, PoseStatus, SceneState, Settings, TrackingStatus } from './types.ts';
 /** Every push event a session can subscribe to, with its payload. */
 export interface EventMap {
@@ -70,6 +71,11 @@ export interface EventMap {
         modelId: string;
         persistence: ExpressionPersistence;
     };
+    /** A model's Movement Config changed, from any editor; every instance of the model follows it. */
+    'model.movement': {
+        modelId: string;
+        movement: ModelMovementConfig;
+    };
 }
 export type EventName = keyof EventMap;
 export type EventData<E extends EventName = EventName> = EventMap[E];

package/dist/wire/events.js

@@ -17,6 +17,7 @@ export const EVENT_NAMES = Object.keys({
     'selection.changed': true,
     'registry.changed': true,
     'expression.persistence': true,
+    'model.movement': true,
 });
 export function isEventName(v) {
     return isOneOf(v, EVENT_NAMES);

package/dist/wire/methods.d.ts

@@ -2,6 +2,7 @@ import type { Binding, BindingEditorData, BindingLiveValues } from '../values/bi
 import type { ControllerMovementConfig, ControllerState } from '../values/controller.ts';
 import type { SpawnTransition } from '../values/item-transition.ts';
 import type { LipSyncCalibrationCommand, LipSyncConfig, LipSyncMode, LipSyncState } from '../values/lipsync.ts';
+import type { ModelMovementConfig, ModelMovementEdit } from '../values/model-movement.ts';
 import type { SceneInspection } from '../values/stage-info.ts';
 import type { EventName } from './events.ts';
 import type { AnchorOption, AppCapability, AssetKind, AssetRef, Attach, AttachHeadAngle, AutomationInfo, BindingInput, Expression, ExpressionPersistence, HandTrackingMode, HotkeyConfig, HotkeyState, InjectEntry, InjectTarget, InstanceRuntime, JsonValue, LayerEffectKey, LayerEffects, LayerEffectsPatch, MediaPipeConfig, ModelInfo, ModelRef, MotionGroup, MToonTuning, ObjectContent, ObjectLightOverride, ObjectSpace, Place2D, Place3D, PlayingMotion, PoseSourceId, PoseStatus, Scene, SceneItem, SceneLight, SceneLightCameraFollowOptions, ScenePatch, SceneState, ScreenPlacement, Settings, SettingsPatch, TrackingLostBehavior, TrackingSourceConfig, TrackingSourceId, TrackingSourceKind, TrackingStatus, VrmPlacement } from './types.ts';
@@ -633,6 +634,23 @@ export interface BindingOverrideRequest extends BindingTarget {
     value: number | null;
 }
 export type BindingOverrideResponse = EmptyResponse;
+/** `modelId` defaults to the primary model's; movement is Live2D-only. */
+export interface ModelGetMovementRequest {
+    modelId?: string;
+}
+export interface ModelGetMovementResponse {
+    movement: ModelMovementConfig;
+}
+export interface ModelSetMovementRequest {
+    modelId?: string;
+    movement: ModelMovementEdit;
+}
+export interface ModelSetMovementResponse {
+    /** The configuration now moving the model, whether or not it reached the file. */
+    movement: ModelMovementConfig;
+    /** False when nothing reached the file: a refused write (read-only, unreadable), or no usable field. */
+    saved: boolean;
+}
 export interface InstanceSetBreathRequest {
     instanceId: string;
     breath?: boolean;
@@ -974,6 +992,14 @@ export interface MethodMap {
         request: ModelRegisterRequest;
         response: ModelRegisterResponse;
     };
+    'model.getMovement': {
+        request: ModelGetMovementRequest;
+        response: ModelGetMovementResponse;
+    };
+    'model.setMovement': {
+        request: ModelSetMovementRequest;
+        response: ModelSetMovementResponse;
+    };
     'asset.register': {
         request: AssetRegisterRequest;
         response: AssetRegisterResponse;

package/dist/wire/methods.js

@@ -60,6 +60,8 @@ export const METHOD_NAMES = Object.keys({
     'automation.run': true,
     'model.list': true,
     'model.register': true,
+    'model.getMovement': true,
+    'model.setMovement': true,
     'asset.list': true,
     'asset.register': true,
     'registry.thumbnail': true,

package/dist/wire/schemas/requests.d.ts

@@ -216,6 +216,13 @@ export declare const requestSchemas: {
     'model.register': z.ZodObject<{
         path: z.ZodString;
     }, z.core.$strip>;
+    'model.getMovement': z.ZodObject<{
+        modelId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    'model.setMovement': z.ZodObject<{
+        modelId: z.ZodOptional<z.ZodString>;
+        movement: z.ZodCustom<Partial<Pick<import("../../index.ts").ModelMovementConfig, "enabled" | "x" | "y" | "z">>, Partial<Pick<import("../../index.ts").ModelMovementConfig, "enabled" | "x" | "y" | "z">>>;
+    }, z.core.$strip>;
     'asset.register': z.ZodObject<{
         path: z.ZodString;
         want: z.ZodOptional<z.ZodEnum<{

package/dist/wire/schemas/requests.js

@@ -128,6 +128,12 @@ export const requestSchemas = {
     }),
     'tracking.removeSource': z.object({ id: nonEmpty }),
     'model.register': z.object({ path: nonEmpty }),
+    'model.getMovement': z.object({ modelId: nonEmpty.optional() }),
+    // Healed by the host like the desktop editor's own edits, so only the shape is checked here.
+    'model.setMovement': z.object({
+        modelId: nonEmpty.optional(),
+        movement: z.custom(isRecord, 'movement must be an object'),
+    }),
     // Straight off ASSET_KINDS: a kind added there has to reach the wire gate too, or
     // `want` answers invalid-params for a kind the registry already knows how to take.
     'asset.register': z.object({ path: nonEmpty, want: z.enum(ASSET_KINDS).optional() }),

package/dist/wire/schemas/settings.d.ts

@@ -180,9 +180,14 @@ export declare const SettingsSchema: z.ZodObject<{
             width: z.ZodNumber;
             height: z.ZodNumber;
         }, z.core.$strip>>;
+        stageReferenceSize: z.ZodOptional<z.ZodObject<{
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+        }, z.core.$strip>>;
     }, z.core.$strip>;
     ui: z.ZodObject<{
         trayVisible: z.ZodBoolean;
+        streamMode: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>;
     performance: z.ZodObject<{
         showFps: z.ZodBoolean;

package/dist/wire/schemas/settings.js

@@ -99,11 +99,15 @@ export const SettingsSchema = z.object({
     window: z
         .object({
         alwaysOnTop: z.boolean().describe('Keep the control-panel window above other windows.'),
-        stageSize: StageSizeSchema.optional().describe('Read-only stage content size; absent on older hosts.'),
+        stageSize: StageSizeSchema.optional().describe('Read-only stage window content size; absent on older hosts.'),
+        stageReferenceSize: StageSizeSchema.optional().describe('Read-only initial stage size calibrating placement units and model fit; not the output aspect.'),
     })
         .describe('Public window configuration and read-only stage dimensions.'),
     ui: z
-        .object({ trayVisible: z.boolean().describe('Show the tray or menu bar icon.') })
+        .object({
+        trayVisible: z.boolean().describe('Show the tray or menu bar icon.'),
+        streamMode: z.boolean().optional().describe('Read-only Stream Mode state; absent on older hosts.'),
+    })
         .describe('Public interface preferences.'),
     performance: PerformanceSettingsSchema.partial({ renderScale: true }).describe('Renderer settings; renderScale is absent on older hosts.'),
     tracking: TrackingSettingsSchema.describe('Network face master switch and all configured tracking sources.'),
@@ -118,6 +122,10 @@ export const SettingsPatchSchema = z.object({
         .partial()
         .optional()
         .describe('Control-panel window fields to update.'),
-    ui: SettingsSchema.shape.ui.partial().optional().describe('Public interface fields to update.'),
+    ui: SettingsSchema.shape.ui
+        .pick({ trayVisible: true })
+        .partial()
+        .optional()
+        .describe('Public interface fields to update.'),
     performance: PerformanceSettingsSchema.partial().optional().describe('Renderer fields to update.'),
 });

package/dist/wire/types.d.ts

@@ -8,6 +8,7 @@ import { type BaseControllerInputName, type ControllerInputName, type Controller
 import { type HandInputName } from '../values/hands.ts';
 import { type LipSyncMode, type VoiceInputName } from '../values/lipsync.ts';
 import { type MouseInputName } from '../values/mouse.ts';
+import { type TimeInputName } from '../values/time.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';
@@ -80,7 +81,7 @@ export interface CatalogItem extends Omit<ContentRef, 'origin'> {
     /** Creator or content homepage (https). */
     url?: string;
 }
-/** Screen-space placement: pixels from the stage centre, rotation in radians. */
+/** Screen-space placement: calibrated stage units from the viewport centre, rotation in radians. */
 export interface ScreenPlacement {
     x: number;
     y: number;
@@ -207,8 +208,6 @@ export interface SceneModelItem {
 }
 export declare const OBJECT_SPACES: readonly ["2d", "3d"];
 export type ObjectSpace = (typeof OBJECT_SPACES)[number];
-/** Where a webpage overlay renders relative to the stage. */
-export type WebLayer = 'behind' | 'front';
 export type CaptureKind = 'display' | 'window';
 /** What an object renders. Mirrors VTube Studio's items and Warudo's screen/prop assets. */
 export type ObjectContent = {
@@ -236,8 +235,6 @@ export type ObjectContent = {
     transparent: boolean;
     /** Stylesheet injected into every page the object loads; empty for none. */
     css: string;
-    /** 2D only: composited behind or in front of the whole stage, not interleaved with other layers. */
-    layer: WebLayer;
     /** Close the page while the object is hidden and reload it on show, as an OBS browser source can. */
     shutdownWhenHidden: boolean;
 } | {
@@ -661,6 +658,28 @@ export interface EffectBlur {
     mode: 'gaussian' | 'bokeh';
     highQuality: boolean;
 }
+/**
+ * Pencil sketch on paper (Jaume Sanchez's NPR sketch shader): graphite grain shades the darker
+ * tones and pencil lines trace color and coverage edges, over a procedural paper grain.
+ */
+export interface EffectSketch {
+    enabled: boolean;
+    /** Paper tint (hex) under the drawing. */
+    paperColor: string;
+    /** Scene only: paper also fills transparent pixels. Layers always keep their coverage. */
+    paperBackground: boolean;
+    /** Pencil-line darkness, 0–2. */
+    lines: number;
+    /** Pencil-line width in CSS pixels, 0.5–4, so it holds across display densities. */
+    lineWidth: number;
+    /** Graphite grain in the darker tones, 0–2: 0 leaves only the lines, 1 is the source's density. */
+    shading: number;
+    /** How strongly a wide blur of the surrounding tones lightens the shading, 0–1. */
+    softness: number;
+    /** 0 draws in graphite, 1 keeps the image's colors at the same lightness. */
+    saturation: number;
+    opacity: number;
+}
 /** Lens fringing that grows toward frame edges (Unity PPv2's curve, the one VTube Studio wraps). */
 export interface SceneChromaticAberration {
     enabled: boolean;
@@ -877,6 +896,7 @@ export interface EffectValues {
     gradient: EffectGradient;
     flare: SceneFlare;
     blur: EffectBlur;
+    sketch: EffectSketch;
     chromaticAberration: SceneChromaticAberration;
     grain: SceneFilmGrain;
     dof: SceneDepthOfField;
@@ -1041,7 +1061,7 @@ export interface ScenePatch {
  * App-level features a client gates on (never version-sniff): `hello` and
  * `app.info` report them — the per-app mirror of {@link InstanceRuntime.capabilities}.
  */
-export declare const APP_CAPABILITIES: readonly ["storage", "speech", "automations", "controllers", "model-editing", "asset-inspection", "layer-effects", "scene-transitions", "area-lights", "spot-lights", "camera-follow-lights", "shadow-filters", "environment-map-model", "spawn", "tracking-lost", "motion-stop", "stage-capture"];
+export declare const APP_CAPABILITIES: readonly ["storage", "speech", "automations", "controllers", "model-editing", "asset-inspection", "layer-effects", "scene-transitions", "area-lights", "spot-lights", "camera-follow-lights", "shadow-filters", "environment-map-model", "spawn", "tracking-lost", "motion-stop", "stage-capture", "model-movement", "object-pin-depth"];
 export type AppCapability = (typeof APP_CAPABILITIES)[number];
 export declare function isAppCapability(v: unknown): v is AppCapability;
 /** What a loaded model instance can do; absent capabilities answer `unsupported-for-format`. */
@@ -1302,12 +1322,12 @@ declare const VTS_INPUT_RANGES: {
 };
 type VtsInputName = keyof typeof VTS_INPUT_RANGES;
 /**
- * Default input vocabulary: face, hand and cursor inputs, raw ARKit channels and controller
+ * Default input vocabulary: face, hand, cursor and time inputs, raw ARKit channels and controller
  * profile 1. Additional controller profile ids are accepted by isInputName without appearing
  * in this list.
  */
-export declare const INPUT_NAMES: readonly (VtsInputName | HandInputName | VoiceInputName | MouseInputName | ArkitInputName | BaseControllerInputName)[];
-export type InputName = VtsInputName | HandInputName | VoiceInputName | MouseInputName | ArkitInputName | ControllerInputName;
+export declare const INPUT_NAMES: readonly (VtsInputName | HandInputName | VoiceInputName | MouseInputName | TimeInputName | ArkitInputName | BaseControllerInputName)[];
+export type InputName = VtsInputName | HandInputName | VoiceInputName | MouseInputName | TimeInputName | ArkitInputName | ControllerInputName;
 /** Whether an untrusted string names a tracking input — the guard every wire boundary needs. */
 export declare function isInputName(v: string): v is InputName;
 /**
@@ -1335,7 +1355,7 @@ export declare function arkitTwinOf(input: InputName): BindingInput;
  * Default inputs' natural spans. Use getInputRange for a dynamically numbered controller input.
  * Head angles are degrees; the rest are unitless.
  */
-export declare const INPUT_RANGES: Record<VtsInputName | HandInputName | VoiceInputName | MouseInputName | ArkitInputName | BaseControllerInputName, readonly [number, number]>;
+export declare const INPUT_RANGES: Record<VtsInputName | HandInputName | VoiceInputName | MouseInputName | TimeInputName | ArkitInputName | BaseControllerInputName, readonly [number, number]>;
 /** Natural span of any valid input, including dynamically numbered controller profiles. */
 export declare function getInputRange(name: InputName): readonly [number, number];
 /**

package/dist/wire/types.js

@@ -7,6 +7,7 @@ import { isOneOf, keysOf } from "../values/guards.js";
 import { HAND_INPUT_NAMES, HAND_INPUT_RANGES } from "../values/hands.js";
 import { VOICE_INPUT_NAMES, VOICE_INPUT_RANGES } from "../values/lipsync.js";
 import { MOUSE_INPUT_NAMES, MOUSE_INPUT_RANGES } from "../values/mouse.js";
+import { TIME_INPUT_NAMES, TIME_INPUT_RANGES } from "../values/time.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
@@ -53,6 +54,13 @@ export const APP_CAPABILITIES = [
     'motion-stop',
     /** `stage.capture`. */
     'stage-capture',
+    /** `model.getMovement` / `model.setMovement` and the `model.movement` event. */
+    'model-movement',
+    /**
+     * 2D images, videos and webpages all paint in the stage's layer stack (a webpage has no `layer`), and
+     * one pinned to a Live2D model takes `attach.depth` in that model's stack, as a Live2D item does.
+     */
+    'object-pin-depth',
 ];
 export function isAppCapability(v) {
     return isOneOf(v, APP_CAPABILITIES);
@@ -193,7 +201,7 @@ const VTS_INPUT_RANGES = {
 /** VTS's input vocabulary, plus `JawOpen` — the derived half of {@link INPUT_NAMES}. */
 const VTS_INPUT_NAMES = keysOf(VTS_INPUT_RANGES);
 /**
- * Default input vocabulary: face, hand and cursor inputs, raw ARKit channels and controller
+ * Default input vocabulary: face, hand, cursor and time inputs, raw ARKit channels and controller
  * profile 1. Additional controller profile ids are accepted by isInputName without appearing
  * in this list.
  */
@@ -202,6 +210,7 @@ export const INPUT_NAMES = [
     ...VOICE_INPUT_NAMES,
     ...HAND_INPUT_NAMES,
     ...MOUSE_INPUT_NAMES,
+    ...TIME_INPUT_NAMES,
     ...ARKIT_INPUT_NAMES,
     ...BASE_CONTROLLER_INPUT_NAMES,
 ];
@@ -242,6 +251,7 @@ export const INPUT_RANGES = {
     ...VOICE_INPUT_RANGES,
     ...HAND_INPUT_RANGES,
     ...MOUSE_INPUT_RANGES,
+    ...TIME_INPUT_RANGES,
     ...BASE_CONTROLLER_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.

package/package.json

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