@melite/formats 0.0.0-stage → 0.1.5-pre-alpha

package/lib/glbLoad.d.ts

@@ -0,0 +1,54 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+import * as THREE from '@melite/three-client/client';
+import { GLTFLoader } from '@melite/three-client/client';
+import type { GLTF } from '@melite/three-client/client';
+/** A GLTFLoader configured with the estate's shared DRACO decoder —
+ *  for parse-based consumers (glbSkin parses pre-fetched bytes). */
+export declare function makeGLTFLoader(): GLTFLoader;
+/** Load a GLB/GLTF from a URL with the estate's shared DRACO-configured
+ *  loader. One loader instance + one decoder worker pool for every
+ *  consumer (the decoder worker is reused, never respawned per view). */
+export declare function loadGLB(url: string): Promise<GLTF>;
+/**
+ * Normalize a loaded scene to a known viewing size: center X/Z, scale
+ * the largest dimension to `targetHeight`, feet on y=0. Mutates the
+ * root IN PLACE (scale + position) and returns the computed box.
+ *
+ * The shared normalization every viewer applies — TRELLIS props,
+ * SOMAX/Anny characters, and composite uploads arrive at wildly
+ * different scales (cm, m, 100× unit boxes); this is the one place
+ * that reconciles them, so the poster tile, the dialog viewer, and
+ * the stage floor all frame the mesh identically.
+ */
+export declare function fitObjectToHeight(root: THREE.Object3D, targetHeight?: number): THREE.Box3;
+/** The historical spelling (the card-base glb-stage's name for the
+ *  same algorithm). The default is ONE value: the two copies said
+ *  1.8 and 1.6, so the same mesh framed in a card stage and framed
+ *  in the gallery came out at different heights. 1.6 is the de-facto
+ *  law — every explicit call site already passed it. */
+export { fitObjectToHeight as autoFitToHeight };
+//# sourceMappingURL=glbLoad.d.ts.map

package/lib/glbLoad.js

@@ -0,0 +1,96 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+import * as THREE from '@melite/three-client/client';
+import { GLTFLoader } from '@melite/three-client/client';
+import { DRACOLoader } from '@melite/three-client/client';
+let _draco = null;
+let _loader = null;
+// import.meta.env is Vite runtime truth; the cast states the read
+// locally (a global ImportMeta augmentation collides with the
+
+
+
+
+
+
+const base = import.meta.env?.BASE_URL ?? "/";
+function dracoLoader() {
+    if (!_draco) {
+        _draco = new DRACOLoader();
+        // LOCAL decoder (offline, deterministic — no CDN, no SPOF). The
+        // trailing slash matters: DRACOLoader concatenates filenames onto
+        // the path verbatim.
+        _draco.setDecoderPath(`${base}draco/gltf/`);
+    }
+    return _draco;
+}
+/** A GLTFLoader configured with the estate's shared DRACO decoder —
+ *  for parse-based consumers (glbSkin parses pre-fetched bytes). */
+export function makeGLTFLoader() {
+    const loader = new GLTFLoader();
+    loader.setDRACOLoader(dracoLoader());
+    return loader;
+}
+/** Load a GLB/GLTF from a URL with the estate's shared DRACO-configured
+ *  loader. One loader instance + one decoder worker pool for every
+ *  consumer (the decoder worker is reused, never respawned per view). */
+export function loadGLB(url) {
+    if (!_loader)
+        _loader = makeGLTFLoader();
+    return new Promise((resolve, reject) => {
+        _loader.load(url, resolve, undefined, reject);
+    });
+}
+/**
+ * Normalize a loaded scene to a known viewing size: center X/Z, scale
+ * the largest dimension to `targetHeight`, feet on y=0. Mutates the
+ * root IN PLACE (scale + position) and returns the computed box.
+ *
+ * The shared normalization every viewer applies — TRELLIS props,
+ * SOMAX/Anny characters, and composite uploads arrive at wildly
+ * different scales (cm, m, 100× unit boxes); this is the one place
+ * that reconciles them, so the poster tile, the dialog viewer, and
+ * the stage floor all frame the mesh identically.
+ */
+export function fitObjectToHeight(root, targetHeight = 1.6) {
+    const box = new THREE.Box3().setFromObject(root);
+    const size = box.getSize(new THREE.Vector3());
+    const center = box.getCenter(new THREE.Vector3());
+    const maxDim = Math.max(size.x, size.y, size.z);
+    const scale = maxDim > 0 ? targetHeight / maxDim : 1;
+    root.scale.setScalar(scale);
+    root.position.x = -center.x * scale;
+    root.position.z = -center.z * scale;
+    root.position.y = -box.min.y * scale;
+    return box;
+}
+/** The historical spelling (the card-base glb-stage's name for the
+ *  same algorithm). The default is ONE value: the two copies said
+ *  1.8 and 1.6, so the same mesh framed in a card stage and framed
+ *  in the gallery came out at different heights. 1.6 is the de-facto
+ *  law — every explicit call site already passed it. */
+export { fitObjectToHeight as autoFitToHeight };
+//# sourceMappingURL=glbLoad.js.map

package/lib/glbSkin.d.ts

@@ -0,0 +1,14 @@
+import { type SomaSkin } from "./somaSkin.js";
+export declare class NotSomaxGlbError extends Error {
+    constructor(reason: string);
+}
+/**
+ * Load a SOMAX-rigged character GLB as a SomaSkin.
+ *
+ * @param url a data: URL (studio upload) or a same-origin asset URL
+ *            (/editor/assets/... — asset tray or a wired upstream card).
+ * @throws NotSomaxGlbError when the GLB has no 77-joint skinned mesh.
+ * @throws Error on fetch/parse failures.
+ */
+export declare function loadGlbSkin(url: string): Promise<SomaSkin>;
+//# sourceMappingURL=glbSkin.d.ts.map

package/lib/glbSkin.js

@@ -0,0 +1,124 @@
+import { makeGLTFLoader } from "./glbLoad.js";
+import { invert4, restPoseFromBind } from "./somaSkin.js";
+/** SOMA-77 — the rig every SOMAX GLB carries (skin.name "SOMA-Mixamo"). */
+const SOMA_JOINTS = 77;
+/** glTF skins are VEC4 — four influences per vertex. */
+const GLTF_INFLUENCES = 4;
+export class NotSomaxGlbError extends Error {
+    constructor(reason) {
+        super(`Not a SOMAX-rigged GLB (77-joint SOMA skeleton required): ${reason}`);
+        this.name = "NotSomaxGlbError";
+    }
+}
+/** Column-major 16 (three.js Matrix4.elements) → row-major Float32Array. */
+function colMajorToRowMajor(elements) {
+    const out = new Float32Array(16);
+    for (let r = 0; r < 4; r++) {
+        for (let c = 0; c < 4; c++) {
+            out[r * 4 + c] = elements[c * 4 + r];
+        }
+    }
+    return out;
+}
+/**
+ * Load a SOMAX-rigged character GLB as a SomaSkin.
+ *
+ * @param url a data: URL (studio upload) or a same-origin asset URL
+ *            (/editor/assets/... — asset tray or a wired upstream card).
+ * @throws NotSomaxGlbError when the GLB has no 77-joint skinned mesh.
+ * @throws Error on fetch/parse failures.
+ */
+export async function loadGlbSkin(url) {
+    const res = await fetch(url);
+    if (!res.ok)
+        throw new Error(`Failed to fetch character GLB: ${res.status}`);
+    const buffer = await res.arrayBuffer();
+    // The shared loader kernel — DRACO-configured (a compressed character
+    // GLB parses identically here and in every viewer; before the kernel,
+    // this bare loader was the ONE GLB path in the estate with no decoder).
+    const loader = makeGLTFLoader();
+    const gltf = await new Promise((resolve, reject) => loader.parse(buffer, "", resolve, reject));
+    // Collect EVERY 77-joint skinned mesh (composite characters layer
+    // body + outfit + hair on one shared rig).
+    const meshes = [];
+    gltf.scene.traverse((obj) => {
+        const m = obj;
+        if (!m.isSkinnedMesh || !m.geometry)
+            return;
+        if (m.skeleton?.bones?.length === SOMA_JOINTS)
+            meshes.push(m);
+    });
+    if (meshes.length === 0) {
+        throw new NotSomaxGlbError("no skinned mesh with 77 joints found (static meshes and other rigs cannot play SOMA-77 motion)");
+    }
+    // ── The rig terms (shared by every merged mesh — one rig per SOMAX GLB)
+    const skeleton = meshes[0].skeleton;
+    const J = skeleton.bones.length;
+    const bindRigInv = new Float32Array(J * 16);
+    for (let j = 0; j < J; j++) {
+        // boneInverses ARE the inverse bind matrices — bindRigInv verbatim,
+        // transposed from three.js column-major into somaSkin's row-major.
+        bindRigInv.set(colMajorToRowMajor(skeleton.boneInverses[j].elements), j * 16);
+    }
+    // Forward bind = invert(inverse bind); its translation + rotation blocks
+    // are the rest pose (the same extraction the npz loader runs).
+    const bindRigFwd = new Float32Array(J * 16);
+    for (let j = 0; j < J; j++) {
+        bindRigFwd.set(invert4(bindRigInv.subarray(j * 16, j * 16 + 16)), j * 16);
+    }
+    const { restJoints, restRots } = restPoseFromBind(bindRigFwd, J);
+    // ── Merge the meshes: positions + faces + per-vertex skin attributes
+    let vertexCount = 0;
+    let faceCount = 0;
+    for (const m of meshes) {
+        vertexCount += m.geometry.attributes.position.count;
+        if (!m.geometry.index) {
+            throw new NotSomaxGlbError(`mesh "${m.name}" is not triangulated (no index buffer)`);
+        }
+        faceCount += m.geometry.index.count / 3;
+    }
+    const bindVertices = new Float32Array(vertexCount * 3);
+    const faces = new Uint32Array(faceCount * 3);
+    const lbsIndices = new Uint32Array(vertexCount * GLTF_INFLUENCES);
+    const lbsWeights = new Float32Array(vertexCount * GLTF_INFLUENCES);
+    let vOff = 0;
+    let iOff = 0;
+    for (const m of meshes) {
+        const pos = m.geometry.attributes.position;
+        bindVertices.set(pos.array, vOff * 3);
+        const si = m.geometry.attributes.skinIndex;
+        const sw = m.geometry.attributes.skinWeight;
+        if (!si || !sw) {
+            throw new NotSomaxGlbError(`mesh "${m.name}" has no skinIndex/skinWeight attributes (not skinned)`);
+        }
+        if (si.itemSize !== GLTF_INFLUENCES || sw.itemSize !== GLTF_INFLUENCES) {
+            throw new NotSomaxGlbError(`mesh "${m.name}" skin attributes are ${si.itemSize}-wide (glTF requires VEC4)`);
+        }
+        lbsIndices.set(si.array, vOff * GLTF_INFLUENCES);
+        lbsWeights.set(sw.array, vOff * GLTF_INFLUENCES);
+        // Non-null by the counting pass's own refusal (`!m.geometry.index`
+        // threw above) — the assertion rides that enforced invariant, not
+        
+        const idx = m.geometry.index;
+        const base = vOff;
+        for (let i = 0; i < idx.count; i++) {
+            faces[iOff + i] = idx.array[i] + base;
+        }
+        iOff += idx.count;
+        vOff += pos.count;
+    }
+    return {
+        bindVertices,
+        faces,
+        lbsIndices,
+        lbsWeights,
+        bindRigInv,
+        restJoints,
+        restRots,
+        vertexCount,
+        faceCount,
+        jointCount: J,
+        influences: GLTF_INFLUENCES,
+    };
+}
+//# sourceMappingURL=glbSkin.js.map

package/lib/handPose.d.ts

@@ -0,0 +1,46 @@
+/**
+ * handPose — finger joint indices and helpers for SOMA-77 hand pose presets
+ * (Kimodo-TO method #3: pose libraries for fingers).
+ *
+ * The SOMA-77 skeleton stores JOINT POSITIONS (not rotations), so a finger
+ * preset is a snapshot of finger-joint positions. To make presets portable
+ * across wrist positions, we store them as OFFSETS relative to the wrist
+ * joint (LeftHand=14, RightHand=42). On apply, the offset is re-based to
+ * the current wrist position.
+ *
+ * NOTE: This translation-only rebasing ignores wrist rotation. If the wrist
+ * has rotated since the preset was captured, the fingers will point in the
+ * original direction. For MVP this is acceptable — the user can either
+ * recapture the preset at the new orientation, or fine-tune manually after
+ * applying. A full rotation-aware version would derive the wrist frame from
+ * the wrist→knuckle direction and re-orient offsets accordingly.
+ *
+ * Joint layout (vendor/kimodo/kimodo/skeleton/definitions.py SOMASkeleton77):
+ *   LeftHand(14) [thumb 15-18, index 19-23, middle 24-28, ring 29-33, pinky 34-38]
+ *   RightHand(42) [thumb 43-46, index 47-51, middle 52-56, ring 57-61, pinky 62-66]
+ */
+/** Wrist joint index per hand side. */
+export declare const WRIST_INDEX: Record<"left" | "right", number>;
+/** Finger joint indices per hand side (wrist NOT included — wrist is the
+ *  anchor that offsets are relative to). */
+export declare const FINGER_JOINTS: Record<"left" | "right", number[]>;
+/**
+ * Extract a hand pose from a flat 77×3 joint array as wrist-relative offsets.
+ * The result is a sparse {jointIdx: [dx, dy, dz]} map (only finger joints).
+ * The wrist position is subtracted so the preset is portable.
+ */
+export declare function captureHandPose(side: "left" | "right", joints: Float32Array | number[]): Record<number, [number, number, number]>;
+/**
+ * Apply a captured hand pose to a flat 77×3 joint array. Each finger joint
+ * is set to the current wrist position + the stored offset. Only finger
+ * joints are touched — the rest of the pose (including the wrist) is left
+ * intact. Returns a new Float32Array (does not mutate the input).
+ */
+export declare function applyHandPose(side: "left" | "right", joints: Float32Array | number[], offsets: Record<number, [number, number, number]>): Float32Array;
+/** Encode a hand-pose offset map as a plain number[] for the pose library.
+ *  Stores the wrist-relative offsets inline at their joint indices in a 77×3
+ *  array (zero elsewhere). Round-trips with decodeHandPose. */
+export declare function encodeHandPose(side: "left" | "right", offsets: Record<number, [number, number, number]>): number[];
+/** Decode a stored hand-pose number[] back into an offset map. */
+export declare function decodeHandPose(arr: number[]): Record<number, [number, number, number]>;
+//# sourceMappingURL=handPose.d.ts.map

package/lib/handPose.js

@@ -0,0 +1,122 @@
+/**
+ * handPose — finger joint indices and helpers for SOMA-77 hand pose presets
+ * (Kimodo-TO method #3: pose libraries for fingers).
+ *
+ * The SOMA-77 skeleton stores JOINT POSITIONS (not rotations), so a finger
+ * preset is a snapshot of finger-joint positions. To make presets portable
+ * across wrist positions, we store them as OFFSETS relative to the wrist
+ * joint (LeftHand=14, RightHand=42). On apply, the offset is re-based to
+ * the current wrist position.
+ *
+ * NOTE: This translation-only rebasing ignores wrist rotation. If the wrist
+ * has rotated since the preset was captured, the fingers will point in the
+ * original direction. For MVP this is acceptable — the user can either
+ * recapture the preset at the new orientation, or fine-tune manually after
+ * applying. A full rotation-aware version would derive the wrist frame from
+ * the wrist→knuckle direction and re-orient offsets accordingly.
+ *
+ * Joint layout (vendor/kimodo/kimodo/skeleton/definitions.py SOMASkeleton77):
+ *   LeftHand(14) [thumb 15-18, index 19-23, middle 24-28, ring 29-33, pinky 34-38]
+ *   RightHand(42) [thumb 43-46, index 47-51, middle 52-56, ring 57-61, pinky 62-66]
+ */
+/** Wrist joint index per hand side. */
+export const WRIST_INDEX = {
+    left: 14,
+    right: 42,
+};
+/** Finger joint indices per hand side (wrist NOT included — wrist is the
+ *  anchor that offsets are relative to). */
+export const FINGER_JOINTS = {
+    left: [
+        15, 16, 17, 18, // thumb (4 joints)
+        19, 20, 21, 22, 23, // index (5)
+        24, 25, 26, 27, 28, // middle (5)
+        29, 30, 31, 32, 33, // ring (5)
+        34, 35, 36, 37, 38, // pinky (5)
+    ],
+    right: [
+        43, 44, 45, 46,
+        47, 48, 49, 50, 51,
+        52, 53, 54, 55, 56,
+        57, 58, 59, 60, 61,
+        62, 63, 64, 65, 66,
+    ],
+};
+/**
+ * Extract a hand pose from a flat 77×3 joint array as wrist-relative offsets.
+ * The result is a sparse {jointIdx: [dx, dy, dz]} map (only finger joints).
+ * The wrist position is subtracted so the preset is portable.
+ */
+export function captureHandPose(side, joints) {
+    const wrist = WRIST_INDEX[side];
+    const wx = joints[wrist * 3];
+    const wy = joints[wrist * 3 + 1];
+    const wz = joints[wrist * 3 + 2];
+    const out = {};
+    for (const idx of FINGER_JOINTS[side]) {
+        out[idx] = [
+            joints[idx * 3] - wx,
+            joints[idx * 3 + 1] - wy,
+            joints[idx * 3 + 2] - wz,
+        ];
+    }
+    return out;
+}
+/**
+ * Apply a captured hand pose to a flat 77×3 joint array. Each finger joint
+ * is set to the current wrist position + the stored offset. Only finger
+ * joints are touched — the rest of the pose (including the wrist) is left
+ * intact. Returns a new Float32Array (does not mutate the input).
+ */
+export function applyHandPose(side, joints, offsets) {
+    const out = joints instanceof Float32Array
+        ? new Float32Array(joints)
+        : new Float32Array(joints);
+    const wrist = WRIST_INDEX[side];
+    const wx = out[wrist * 3];
+    const wy = out[wrist * 3 + 1];
+    const wz = out[wrist * 3 + 2];
+    for (const idx of FINGER_JOINTS[side]) {
+        const off = offsets[idx];
+        if (!off)
+            continue;
+        out[idx * 3] = wx + off[0];
+        out[idx * 3 + 1] = wy + off[1];
+        out[idx * 3 + 2] = wz + off[2];
+    }
+    return out;
+}
+/** Encode a hand-pose offset map as a plain number[] for the pose library.
+ *  Stores the wrist-relative offsets inline at their joint indices in a 77×3
+ *  array (zero elsewhere). Round-trips with decodeHandPose. */
+export function encodeHandPose(side, offsets) {
+    const arr = new Array(77 * 3).fill(0);
+    for (const idx of FINGER_JOINTS[side]) {
+        const off = offsets[idx];
+        if (!off)
+            continue;
+        arr[idx * 3] = off[0];
+        arr[idx * 3 + 1] = off[1];
+        arr[idx * 3 + 2] = off[2];
+    }
+    return arr;
+}
+/** Decode a stored hand-pose number[] back into an offset map. */
+export function decodeHandPose(arr) {
+    const out = {};
+    // The encoding stores offsets only at finger-joint indices; we don't need
+    // to know the side to decode (the indices tell us). Scan all 77 joints.
+    for (let idx = 0; idx < 77; idx++) {
+        const x = arr[idx * 3];
+        const y = arr[idx * 3 + 1];
+        const z = arr[idx * 3 + 2];
+        // Skip zeros (uninitialized slots). Note: this conflates genuinely-zero
+        // offsets with empty slots, but a real finger offset is never exactly at
+        // the wrist (would mean a zero-length bone), so this is safe in practice.
+        if (x === 0 && y === 0 && z === 0)
+            continue;
+        out[idx] = [x, y, z];
+    }
+    return out;
+}
+//# sourceMappingURL=handPose.js.map

package/lib/index.d.ts

@@ -0,0 +1,25 @@
+/** @melite/formats — pure media codecs + math (npz, skins, masks, presets).
+ * Fetch-free by law; three.js types only where geometry demands. */
+export * from "./npz.js";
+export * from "./somaSkin.js";
+export * from "./motionNpz.js";
+export * from "./glbSkin.js";
+export * from "./maskPrep.js";
+export * from "./bodyPresets.js";
+export * from "./poseCodec.js";
+export * from "./motionConstraints.js";
+export * from "./openPoseCanvas.js";
+export * from "./downloads.js";
+export * from "./b64.js";
+export * from "./poseTransforms.js";
+export * from "./psdExport.js";
+export * from "./pngMetaInfo.js";
+export * from "./pngMeta.js";
+export * from "./captionSplitter.js";
+export * from "./promptTags.js";
+export * from "./motionEnvelope.js";
+export * from "./extractVideoFrame.js";
+export * from "./keyframeExtract.js";
+export * from "./handPose.js";
+export * from "./cardMutations.js";
+//# sourceMappingURL=index.d.ts.map

package/lib/index.js

@@ -0,0 +1,25 @@
+/** @melite/formats — pure media codecs + math (npz, skins, masks, presets).
+ * Fetch-free by law; three.js types only where geometry demands. */
+export * from "./npz.js";
+export * from "./somaSkin.js";
+export * from "./motionNpz.js";
+export * from "./glbSkin.js";
+export * from "./maskPrep.js";
+export * from "./bodyPresets.js";
+export * from "./poseCodec.js";
+export * from "./motionConstraints.js";
+export * from "./openPoseCanvas.js";
+export * from "./downloads.js";
+export * from "./b64.js";
+export * from "./poseTransforms.js";
+export * from "./psdExport.js";
+export * from "./pngMetaInfo.js";
+export * from "./pngMeta.js";
+export * from "./captionSplitter.js";
+export * from "./promptTags.js";
+export * from "./motionEnvelope.js";
+export * from "./extractVideoFrame.js";
+export * from "./keyframeExtract.js";
+export * from "./handPose.js";
+export * from "./cardMutations.js";
+//# sourceMappingURL=index.js.map

package/lib/keyframeExtract.d.ts

@@ -0,0 +1,46 @@
+/**
+ * keyframeExtract — pick anchor frames from a SOMA-77 motion trajectory.
+ *
+ * Used by Pose Studio's "Auto Keyframes" action (Kimodo-TO (g)) to turn a
+ * generated motion into a sparse set of keyframe constraints without the
+ * user scrubbing and pinning by hand.
+ *
+ * Two regimes:
+ *
+ *   1. Multi-prompt motion → the semantic boundaries are already known:
+ *      each prompt segment's start_frame / end_frame is a natural keyframe
+ *      (the motion changes intent there). No signal processing needed.
+ *
+ *   2. Single-prompt motion → run velocity-minima detection on the joint
+ *      trajectory. Per-frame velocity = total squared displacement of all
+ *      77 joints from the previous frame. Local MINIMA of this signal are
+ *      the holds / extremes (top of a reach, contact frame, pause) — clean,
+ *      readable anchor poses. Local MAXIMA are mid-motion blur frames and
+ *      make BAD anchors, so we explicitly look for minima, not peaks.
+ *
+ * Both paths return frame indices, deduped and sorted, with endpoints and a
+ * minimum spacing enforced.
+ */
+import type { PromptSegmentOutput } from "./textToPose.js";
+export interface ExtractOptions {
+    /** Minimum frames between extracted keyframes (anti-clustering). */
+    minSpacing?: number;
+    /** Always include frame 0 and the last frame as anchors. Default true. */
+    includeEndpoints?: boolean;
+}
+/**
+ * Extract keyframe frame indices from a motion's per-frame joint trajectory.
+ *
+ * @param framesJoints  Per-frame joint positions. Shape: [frame][joint][3].
+ *                       (result.motion.frames_soma77_3d from the pose API.)
+ * @param segments      Optional prompt segments. When present (>1), their
+ *                       boundaries are used directly instead of velocity
+ *                       detection — they ARE the semantic keyframes.
+ */
+export declare function extractKeyframeFrames(framesJoints: number[][][], segments?: PromptSegmentOutput[], opts?: ExtractOptions): number[];
+/**
+ * Per-frame velocity (total squared joint displacement). Exposed for the
+ * optional velocity-curve visualization in the timeline.
+ */
+export declare function frameVelocities(framesJoints: number[][][]): number[];
+//# sourceMappingURL=keyframeExtract.d.ts.map

package/lib/keyframeExtract.js

@@ -0,0 +1,89 @@
+/**
+ * Extract keyframe frame indices from a motion's per-frame joint trajectory.
+ *
+ * @param framesJoints  Per-frame joint positions. Shape: [frame][joint][3].
+ *                       (result.motion.frames_soma77_3d from the pose API.)
+ * @param segments      Optional prompt segments. When present (>1), their
+ *                       boundaries are used directly instead of velocity
+ *                       detection — they ARE the semantic keyframes.
+ */
+export function extractKeyframeFrames(framesJoints, segments, opts = {}) {
+    if (!framesJoints?.length)
+        return [];
+    const total = framesJoints.length;
+    const minSpacing = opts.minSpacing ?? Math.max(2, Math.floor(total / 12));
+    const includeEndpoints = opts.includeEndpoints ?? true;
+    let raw;
+    if (segments && segments.length > 1) {
+        // Multi-prompt: segment boundaries are the keyframes.
+        raw = new Set();
+        for (const seg of segments) {
+            raw.add(seg.start_frame);
+            raw.add(seg.end_frame);
+        }
+        // Also include the peak if provided — it's often a strong anchor.
+    }
+    else {
+        // Single-prompt (or no segments): velocity-minima detection.
+        raw = new Set(velocityMinima(framesJoints));
+    }
+    // Enforce endpoints.
+    if (includeEndpoints) {
+        raw.add(0);
+        raw.add(total - 1);
+    }
+    // Dedupe + sort + enforce min spacing (greedy — keep first, skip too-close).
+    const sorted = Array.from(raw).sort((a, b) => a - b)
+        .filter(f => f >= 0 && f < total);
+    const out = [];
+    for (const f of sorted) {
+        if (out.length === 0 || f - out[out.length - 1] >= minSpacing) {
+            out.push(f);
+        }
+        else if (f === total - 1) {
+            // Always keep the last frame even if close to the previous — it's
+            
+            // non-empty and f - prev < minSpacing with f === total - 1, so the
+            // end-anchor unconditionally replaces its too-close predecessor.
+            out[out.length - 1] = f;
+        }
+    }
+    return out;
+}
+/**
+ * Per-frame velocity (total squared joint displacement). Exposed for the
+ * optional velocity-curve visualization in the timeline.
+ */
+export function frameVelocities(framesJoints) {
+    const v = new Array(framesJoints.length).fill(0);
+    for (let f = 1; f < framesJoints.length; f++) {
+        const a = framesJoints[f - 1];
+        const b = framesJoints[f];
+        let sum = 0;
+        const n = Math.min(a.length, b.length);
+        for (let j = 0; j < n; j++) {
+            const aj = a[j], bj = b[j];
+            const dx = bj[0] - aj[0];
+            const dy = bj[1] - aj[1];
+            const dz = bj[2] - aj[2];
+            sum += dx * dx + dy * dy + dz * dz;
+        }
+        v[f] = sum;
+    }
+    v[0] = v[1] ?? 0;
+    return v;
+}
+/** Local minima of the velocity curve → holds / extremes = good anchors. */
+function velocityMinima(framesJoints) {
+    const v = frameVelocities(framesJoints);
+    const minima = [];
+    // A frame is a local minimum if it's lower than its neighbors. Use a
+    // smoothing window of 2 to avoid jitter-induced false minima.
+    for (let f = 2; f < v.length - 2; f++) {
+        if (v[f] < v[f - 1] && v[f] < v[f + 1] && v[f] < v[f - 2] && v[f] < v[f + 2]) {
+            minima.push(f);
+        }
+    }
+    return minima;
+}
+//# sourceMappingURL=keyframeExtract.js.map