@laplace.live/persona-sdk 1.20.0 → 1.22.0

package/dist/client/client.js

@@ -2,6 +2,7 @@ import { parseServerMessage } from "../wire/envelope.js";
 import { PersonaApiError } from "../wire/errors.js";
 import { CLOSE_FORCE_DISCONNECTED, CLOSE_KEY_REVOKED, INJECT_HEARTBEAT_MS, injectTargetKey, PROTOCOL_VERSION, SCENE_ACTIVATION_TIMEOUT_MS, } from "../wire/protocol.js";
 import { personaWsUrl } from "./address.js";
+import { renameLegacyKinds } from "./legacy-kinds.js";
 const DEFAULTS = {
     url: personaWsUrl(),
     reconnectDelayMs: 500,
@@ -109,7 +110,8 @@ export class PersonaClient {
                 reject(new Error(`request timed out: ${method}`));
             }, this.opts.requestTimeoutMs ??
                 (method === 'scene.activate' ? SCENE_ACTIVATION_TIMEOUT_MS : DEFAULTS.requestTimeoutMs));
-            this.pending.set(id, { resolve: resolve, reject, timer });
+            // Only the runtime id ties a response back to `M`, and its result is unvalidated wire JSON.
+            this.pending.set(id, { method, resolve: resolve, reject, timer });
             ws.send(JSON.stringify({ kind: 'request', id, method, ...(params === undefined ? {} : { params }) }));
         });
     }
@@ -355,8 +357,10 @@ export class PersonaClient {
             const set = this.listeners.get(msg.event);
             if (!set)
                 return;
+            const data = renameLegacyKinds(msg.event, msg.data);
+            // Only `msg.event` ties these callbacks to their payload type, and the payload is unvalidated wire JSON.
             for (const cb of set)
-                cb(msg.data);
+                cb(data);
             return;
         }
         const { id } = msg;
@@ -368,7 +372,7 @@ export class PersonaClient {
         this.pending.delete(id);
         clearTimeout(p.timer);
         if (msg.kind === 'response')
-            p.resolve(msg.result);
+            p.resolve(renameLegacyKinds(p.method, msg.result));
         else
             p.reject(new PersonaApiError(msg.code, msg.message));
     }

package/dist/client/legacy-kinds.d.ts

@@ -0,0 +1,2 @@
+/** A method result or event payload with the action kinds an older host still sends renamed to current ones. */
+export declare function renameLegacyKinds(name: string, data: unknown): unknown;

package/dist/client/legacy-kinds.js

@@ -0,0 +1,40 @@
+import { isRecord } from "../values/guards.js";
+import { canonicalActionKind } from "../wire/types.js";
+function renameHotkeyActions(state) {
+    if (!isRecord(state) || !Array.isArray(state.hotkeys))
+        return state;
+    return {
+        ...state,
+        hotkeys: state.hotkeys.map((hotkey) => isRecord(hotkey) && typeof hotkey.action === 'string'
+            ? { ...hotkey, action: canonicalActionKind(hotkey.action) }
+            : hotkey),
+    };
+}
+function renameActionKinds(list) {
+    if (!isRecord(list) || !Array.isArray(list.automations))
+        return list;
+    return {
+        ...list,
+        automations: list.automations.map((automation) => isRecord(automation) && Array.isArray(automation.actionKinds)
+            ? {
+                ...automation,
+                actionKinds: automation.actionKinds.map((kind) => typeof kind === 'string' ? canonicalActionKind(kind) : kind),
+            }
+            : automation),
+    };
+}
+/** A method result or event payload with the action kinds an older host still sends renamed to current ones. */
+export function renameLegacyKinds(name, data) {
+    switch (name) {
+        case 'hotkey.list':
+        case 'hotkey.set':
+            return renameHotkeyActions(data);
+        case 'hotkey.state':
+            return isRecord(data) ? { ...data, config: renameHotkeyActions(data.config) } : data;
+        case 'automation.list':
+        case 'automation.state':
+            return renameActionKinds(data);
+        default:
+            return data;
+    }
+}

package/dist/index.d.ts

@@ -10,6 +10,7 @@ export * from './values/effect-schema.ts';
 export * from './values/gltf-extensions.ts';
 export * from './values/guards.ts';
 export * from './values/hands.ts';
+export * from './values/hotkey-targets.ts';
 export * from './values/hotkeys.ts';
 export * from './values/item-transition.ts';
 export * from './values/labels.ts';
@@ -22,6 +23,7 @@ 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

@@ -12,6 +12,7 @@ export * from "./values/effect-schema.js";
 export * from "./values/gltf-extensions.js";
 export * from "./values/guards.js";
 export * from "./values/hands.js";
+export * from "./values/hotkey-targets.js";
 export * from "./values/hotkeys.js";
 export * from "./values/item-transition.js";
 export * from "./values/labels.js";
@@ -24,6 +25,7 @@ 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/hotkey-targets.d.ts

@@ -0,0 +1,56 @@
+import type { Hotkey, MotionGroup } from '../wire/types.ts';
+/** A hotkey action Persona can run. */
+type HotkeyAction = NonNullable<Hotkey['action']>;
+/** What a model offers hotkeys: its expressions (a null `file` on formats with none) and its motion groups. */
+export interface HotkeyListing {
+    expressions: readonly {
+        name: string;
+        file: string | null;
+    }[];
+    motions: readonly MotionGroup[];
+}
+/**
+ * The id an expression is stored and bound by: its exp3 basename on Live2D (VTS parity),
+ * its name on VRM, which declares no per-expression file. Every persisted or hotkey-bound
+ * reference to an expression goes through this, so the two can never disagree.
+ */
+export declare function expressionKey(def: {
+    name: string;
+    file: string | null;
+}): string;
+/** Saved basenames → definition Names, in saved order; unmatched entries dropped. */
+export declare function matchSavedToDefinitions(saved: readonly string[], defs: readonly {
+    Name: string;
+    File: string;
+}[]): string[];
+/** Expression Name for a stored expression key, or null when the model no longer declares it. */
+export declare function resolveExpressionName(listing: HotkeyListing, file: string): string | null;
+/** Motion group and index for a stored motion3 basename, or null when it's gone. */
+export declare function resolveMotion(listing: {
+    motions: readonly MotionGroup[];
+}, file: string): {
+    group: string;
+    index: number;
+} | null;
+/** `file` is a basename throughout — the form hotkeys are stored in. */
+export interface HotkeyTarget {
+    file: string;
+    label: string;
+}
+/**
+ * The files an action's hotkey can point at, with display labels. Deduped by basename,
+ * first occurrence wins — the same rule the resolvers above apply, so the picker always
+ * lists exactly what a hotkey would run.
+ * @param groupLabel Display name for a motion group; VRM groups are clip refs, not names.
+ */
+export declare function hotkeyTargets(listing: HotkeyListing, action: HotkeyAction, groupLabel?: (group: string) => string): HotkeyTarget[];
+/**
+ * Whether a model-load hotkey's stored `File` names this model: its `.vtube.json` name (what VTS
+ * stores) or its entry file, case-insensitively — VTS's own file-name resolution. A `ModelRef`
+ * from an older host lists neither, and matches nothing.
+ */
+export declare function modelMatchesFile(file: string, model: {
+    vtubeFile?: string | null;
+    entryFile?: string;
+}): boolean;
+export {};

package/dist/values/hotkey-targets.js

@@ -0,0 +1,88 @@
+import { fileBasename, motionLabel, motionSlots } from "./labels.js";
+/**
+ * The id an expression is stored and bound by: its exp3 basename on Live2D (VTS parity),
+ * its name on VRM, which declares no per-expression file. Every persisted or hotkey-bound
+ * reference to an expression goes through this, so the two can never disagree.
+ */
+export function expressionKey(def) {
+    return def.file === null ? def.name : fileBasename(def.file);
+}
+/** Saved basenames → definition Names, in saved order; unmatched entries dropped. */
+export function matchSavedToDefinitions(saved, defs) {
+    const byBase = new Map();
+    for (const d of defs) {
+        const base = fileBasename(d.File);
+        if (!byBase.has(base))
+            byBase.set(base, d.Name);
+    }
+    return saved.flatMap(s => {
+        const name = byBase.get(fileBasename(s));
+        return name === undefined ? [] : [name];
+    });
+}
+// A hotkey stores the same id expression persistence does, so a VRM entry binds by name.
+// A keyless entry (a model3 declaring an empty File) is dropped — nothing could bind it.
+function expressionDefs(listing) {
+    return listing.expressions.flatMap(d => {
+        const key = expressionKey(d);
+        return key === '' ? [] : [{ Name: d.name, File: key }];
+    });
+}
+/** Expression Name for a stored expression key, or null when the model no longer declares it. */
+export function resolveExpressionName(listing, file) {
+    return matchSavedToDefinitions([file], expressionDefs(listing))[0] ?? null;
+}
+/** Motion group and index for a stored motion3 basename, or null when it's gone. */
+export function resolveMotion(listing, file) {
+    const base = fileBasename(file);
+    for (const { group, files } of listing.motions) {
+        const slot = motionSlots(files).find(s => fileBasename(s.file) === base);
+        if (slot)
+            return { group, index: slot.index };
+    }
+    return null;
+}
+/**
+ * The files an action's hotkey can point at, with display labels. Deduped by basename,
+ * first occurrence wins — the same rule the resolvers above apply, so the picker always
+ * lists exactly what a hotkey would run.
+ * @param groupLabel Display name for a motion group; VRM groups are clip refs, not names.
+ */
+export function hotkeyTargets(listing, action, groupLabel = g => g) {
+    const seen = new Set();
+    if (action === 'expression-toggle') {
+        return expressionDefs(listing).flatMap(d => {
+            const file = fileBasename(d.File);
+            if (seen.has(file))
+                return [];
+            seen.add(file);
+            return [{ file, label: d.Name }];
+        });
+    }
+    if (action === 'motion-play') {
+        return listing.motions.flatMap(g => motionSlots(g.files).flatMap(({ file: f }) => {
+            const file = fileBasename(f);
+            if (seen.has(file))
+                return [];
+            seen.add(file);
+            // A VRM group is a single clip named for its own file, so the ` · file` half
+            // would just repeat the group.
+            const label = g.group === f ? groupLabel(g.group) : `${groupLabel(g.group)} · ${motionLabel(f)}`;
+            return [{ file, label }];
+        }));
+    }
+    return [];
+}
+/**
+ * Whether a model-load hotkey's stored `File` names this model: its `.vtube.json` name (what VTS
+ * stores) or its entry file, case-insensitively — VTS's own file-name resolution. A `ModelRef`
+ * from an older host lists neither, and matches nothing.
+ */
+export function modelMatchesFile(file, model) {
+    const base = fileBasename(file).toLowerCase();
+    if (base === '')
+        return false;
+    if (model.vtubeFile?.toLowerCase() === base)
+        return true;
+    return model.entryFile !== undefined && fileBasename(model.entryFile).toLowerCase() === base;
+}

package/dist/values/labels.d.ts

@@ -1,4 +1,4 @@
-import type { AutomationBoundaryKind, AutomationInfo } from '../wire/types.ts';
+import type { AutomationInfo, AutomationSetupKind } from '../wire/types.ts';
 /** Last path segment, tolerating both `/` and `\` separators. */
 export declare function fileBasename(path: string): string;
 /**
@@ -20,7 +20,9 @@ export declare function motionSlots(files: readonly string[]): {
 /** English label for one automation action kind; kinds newer than this SDK read `Action`. */
 export declare function automationActionLabel(kind: string): string;
 /** True for an action that prepares the scene before playback. */
-export declare function isAutomationBoundary(kind: string | undefined): kind is AutomationBoundaryKind;
+export declare function isAutomationSetup(kind: string | undefined): kind is AutomationSetupKind;
+/** @deprecated Use `isAutomationSetup`. */
+export declare const isAutomationBoundary: typeof isAutomationSetup;
 /** Join action labels without implying timing that the client summary does not carry. */
 export declare function joinAutomationActionLabels(labels: readonly string[], kinds: readonly string[]): string;
 /** Display label for an app automation: its title, else its joined action-kind labels. */