Merge branch 'main' into codex/product-usage-analytics

Author: a-baran-orhan

.changeset/motion-export-bvh-gltf.md

@@ -0,0 +1,5 @@
+---
+"posecode-render": patch
+---
+
+Add motion export. `exportBVH(ir, options?)` bakes a movement's authored joint motion and root travel/turn into a standard Biovision Hierarchy (`.bvh`) file, and `exportGLTF(ir, options?)` / `buildAnimatedRig(ir, options?)` export the mannequin rig plus a baked `AnimationClip` as a glTF/GLB asset that loads with Three.js `GLTFLoader`. Both sample the timeline headlessly (no WebGL) at a configurable frame rate and bake the full looped runtime; they export authored motion, not the contact/IK-solved motion.

README.md

@@ -409,6 +409,24 @@ npm run build
 
 ---
 
+### Editor support
+
+A VS Code extension provides syntax highlighting, ROM diagnostics, and
+completion for `.posecode` files — see
+[`editors/vscode`](editors/vscode/README.md). Until it is published, you can
+get basic highlighting immediately by associating `.posecode` files with
+Markdown:
+
+```json
+"files.associations": {
+  "*.posecode": "markdown"
+}
+```
+
+See the [editor guide](editors/vscode/README.md#file-association-before-the-extension-is-installed)
+for VS Code, Cursor, Sublime Text, and Neovim instructions.
+
+---
 
 ## MCP Server
 
@@ -505,6 +523,64 @@ if (!ir || errors.length > 0) {
 
 The `#viewer` element is an HTML `<canvas>`.
 
+### Exporting motion (BVH)
+
+`posecode-render` can bake a movement into a [Biovision Hierarchy](https://en.wikipedia.org/wiki/Biovision_Hierarchy)
+(`.bvh`) file for import into Blender and other animation tools. In the
+playground, use the **Download BVH** button; programmatically:
+
+```ts
+import { parse } from "posecode-parser";
+import { exportBVH } from "posecode-render";
+
+const { ir } = parse(source);
+const bvh = exportBVH(ir!, { fps: 30 }); // string, ready to write to disk
+```
+
+Options: `fps` (default 30), `scale` (default 1 = metres; pass `100` for
+centimetres), `includeFingers` (default false), and `proportions` for a
+calibrated rig.
+
+- **Coordinate system:** right-handed, **Y-up**, figure faces **+Z** in the
+  rest pose (identical to the renderer and Three.js). Enable Blender's "Y up"
+  BVH import option.
+- **Units:** metres by default.
+- **Rotation channels:** `Zrotation Xrotation Yrotation` (Euler order `ZXY`).
+- **Scope:** this exports the *authored* joint motion plus root travel/turn. It
+  does not yet re-run the renderer's contact/IK solve, so IK-dependent movements
+  (e.g. `reach: hand_left floor`) export the authored pose rather than the
+  solved one. See [issue #63](https://github.com/posecode-dev/posecode/issues/63).
+
+### Exporting motion (glTF / GLB)
+
+For web animation pipelines, `posecode-render` can export the rig **and** a
+baked animation clip as a glTF/GLB asset. In the playground, use **Download
+glTF**; programmatically:
+
+```ts
+import { parse } from "posecode-parser";
+import { exportGLTF } from "posecode-render";
+
+const { ir } = parse(source);
+const glb = await exportGLTF(ir!);            // GLB ArrayBuffer (default)
+const gltf = await exportGLTF(ir!, { binary: false }); // glTF JSON object
+```
+
+The result loads with Three.js [`GLTFLoader`](https://threejs.org/docs/#GLTFLoader.load),
+and the clip plays on the included rig:
+
+```ts
+const gltf = await new GLTFLoader().loadAsync(url);
+const mixer = new THREE.AnimationMixer(gltf.scene);
+mixer.clipAction(gltf.animations[0]).play();
+```
+
+- Joint nodes are named by Posecode bone id; the animated root is `posecode_root`.
+- **Limitations:** exports the procedural mannequin rig, not a humanoid/Mixamo
+  skeleton, so there is **no retargeting** onto external rigs yet, and (as with
+  BVH) it bakes the authored motion, not the contact/IK-solved motion. See
+  [issue #90](https://github.com/posecode-dev/posecode/issues/90).
+
 ---
 
 ## How Posecode Stays Honest

ROADMAP.md

@@ -122,7 +122,11 @@ Each prop is a small scene object + an anchor type; movements then reference it
 - Self-collision is a bounded corrective pass over selected body pairs, not a
   comprehensive physics system. It exposes residuals for those sampled pairs,
   but does not detect every possible body-body collision.
-- There is no glTF/GLB or BVH motion export yet.
+- BVH and glTF/GLB motion export bake the **authored** joint motion and root
+  choreography (travel/turn); they do not yet re-run the renderer's contact/IK
+  solve, so IK-dependent movements export their authored pose rather than the
+  solved one. glTF export uses the procedural mannequin rig with no retargeting
+  onto external/humanoid skeletons yet.
 - A **starter** prop set (chair / wall / bar / box / dip bars): no bench,
   rings, bands, or loaded implements yet, and props sit at fixed default
   placements.

editors/vscode/README.md

@@ -9,6 +9,52 @@ Language support for the **Posecode** (`.posecode`) kinematic motion DSL:
 
 The smart features are provided by [`posecode-lsp`](../../packages/posecode-lsp), which shares its language logic ([`posecode-language`](../../packages/posecode-language)) with the web playground, so the editor and the playground always agree.
 
+## File association (before the extension is installed)
+
+Until the full extension is published to the Marketplace, `.posecode` files
+open as plain text. You can get basic highlighting and comment/bracket
+behaviour right away by telling your editor to treat `.posecode` files as
+Markdown, which is the closest built-in grammar.
+
+### VS Code
+
+Add the following to your `settings.json` (open the Command Palette →
+**Preferences: Open User Settings (JSON)**, or use a workspace
+`.vscode/settings.json` to scope it to a single project):
+
+```json
+{
+  "files.associations": {
+    "*.posecode": "markdown"
+  }
+}
+```
+
+Alternatively, open any `.posecode` file, click the language indicator in the
+bottom-right status bar (it will say "Plain Text"), choose **Configure File
+Association for '.posecode'…**, and pick **Markdown**.
+
+### Cursor and other VS Code forks
+
+Cursor, VSCodium, and other VS Code forks read the same `files.associations`
+setting, so the JSON snippet above works unchanged.
+
+### Sublime Text
+
+Open a `.posecode` file, then use the menu **View → Syntax → Open all with
+current extension as… → Markdown**.
+
+### Neovim
+
+Register the extension in your config:
+
+```lua
+vim.filetype.add({ extension = { posecode = "markdown" } })
+```
+
+Once the dedicated extension is installed it registers the real `posecode`
+language id, and you can remove these fallbacks.
+
 ## Develop / run locally
 
 From the repo root:

packages/posecode-eval/src/diagnostics.ts

@@ -180,7 +180,10 @@ export interface ClipDiagnosticsCollector {
   finish(): ClipDiagnostics;
 }
 
-export function createClipDiagnosticsCollector(sampleRateHz: number): ClipDiagnosticsCollector {
+export function createClipDiagnosticsCollector(
+  sampleRateHz: number,
+  isLocomotion = false,
+): ClipDiagnosticsCollector {
   const rate = Math.max(
     1,
     Math.min(120, Number.isFinite(sampleRateHz) ? sampleRateHz : DEFAULT_DIAGNOSTIC_SAMPLE_RATE_HZ),
@@ -195,16 +198,24 @@ export function createClipDiagnosticsCollector(sampleRateHz: number): ClipDiagno
       const state = feet[side];
       const foot = measureFootContact(m, side);
       let kind = supportKind(frame, side);
-      // The generic `feet` group also contains a deliberately lifted swing
-      // foot. Match ground-lock's own near-floor selection so that swing height
-      // is not mislabeled as a failed planted contact; an explicit foot lock or
-      // floor pin is always evaluated.
+      // A supported foot whose sole is well off the floor is mid-swing, not
+      // planted. Skip it in two cases: (1) the generic `feet` group's lifted
+      // swing foot, and (2) any airborne foot in a locomotion clip — at a step
+      // transition the stance pin alternates a beat before the landing foot is
+      // actually down, so the descending foot is swinging, not a failed plant.
+      // The endpoint contact-position check still catches a pin left airborne.
+      const airborne =
+        kind !== null
+        && foot !== null
+        && !isGroundLockFootPlanted(floorContactHeight(m, `foot_${side}`) ?? NaN);
       if (
-        kind === "ground-lock"
-        && frame.groundLock.includes("feet")
-        && !frame.groundLock.includes(`foot_${side}`)
-        && foot
-        && !isGroundLockFootPlanted(floorContactHeight(m, `foot_${side}`) ?? NaN)
+        airborne
+        && (
+          (kind === "ground-lock"
+            && frame.groundLock.includes("feet")
+            && !frame.groundLock.includes(`foot_${side}`))
+          || isLocomotion
+        )
       ) kind = null;
       if (!kind || !foot) {
         state.supportKind = null;
@@ -214,21 +225,32 @@ export function createClipDiagnosticsCollector(sampleRateHz: number): ClipDiagno
       }
       state.supportedSamples++;
       const location = { timeSec: frame.timeSec, phaseName: frame.phaseName };
-      state.minToeHeightMeters = Math.min(state.minToeHeightMeters ?? Infinity, foot.toeHeight);
-      state.maxToeHeightMeters = Math.max(state.maxToeHeightMeters ?? -Infinity, foot.toeHeight);
-      if (Math.abs(foot.toeHeight) > state.worstToeAbs) {
-        state.worstToeAbs = Math.abs(foot.toeHeight);
-        state.worstToe = location;
-      }
-      // Flat-sole grounding checks only apply when a flat foot is expected: the
-      // ankle is not plantarflexed AND the shin stands near-vertical. A foot on
-      // its ball with the shin laid down (plank, knee-drive) legitimately shows
-      // a steep sole and lifted heel, so measuring it as a failed flat plant
-      // fabricates warnings.
+      // Flat-foot grounding checks (heel/toe height, sole tilt) only apply when a
+      // flat foot is expected: the ankle is not plantarflexed AND the shin stands
+      // near-vertical. A foot on its ball with the shin laid down (plank,
+      // knee-drive) legitimately shows a lifted heel/toe and a steep sole, so
+      // measuring it as a failed flat plant fabricates warnings.
       const shinDeg = shinFromVerticalDeg(m, side);
+      // A stance foot in a locomotion clip rolls onto its ball as the body
+      // travels over it — the toe stays planted while the heel lifts (push-off).
+      // That roll is correct gait, not a failed flat plant, so it is exempt from
+      // the flat-foot checks. A fully airborne foot (toe also lifted) is not a
+      // roll and stays measured; static clips keep the strict flat-foot bar.
+      const pushOffRoll =
+        isLocomotion
+        && Math.abs(foot.toeHeight) <= FOOT_CONTACT_HEIGHT_MAX
+        && foot.heelHeight > FOOT_CONTACT_HEIGHT_MAX;
       const expectedFlat =
-        foot.plantigrade && (shinDeg === null || shinDeg <= FLAT_SOLE_SHIN_MAX_DEG);
+        foot.plantigrade
+        && !pushOffRoll
+        && (shinDeg === null || shinDeg <= FLAT_SOLE_SHIN_MAX_DEG);
       if (expectedFlat) {
+        state.minToeHeightMeters = Math.min(state.minToeHeightMeters ?? Infinity, foot.toeHeight);
+        state.maxToeHeightMeters = Math.max(state.maxToeHeightMeters ?? -Infinity, foot.toeHeight);
+        if (Math.abs(foot.toeHeight) > state.worstToeAbs) {
+          state.worstToeAbs = Math.abs(foot.toeHeight);
+          state.worstToe = location;
+        }
         state.plantigradeSamples++;
         state.minHeelHeightMeters = Math.min(state.minHeelHeightMeters ?? Infinity, foot.heelHeight);
         state.maxHeelHeightMeters = Math.max(state.maxHeelHeightMeters ?? -Infinity, foot.heelHeight);

packages/posecode-eval/src/probe.ts

@@ -846,7 +846,7 @@ export function probeMovement(
   // Endpoint probes above power semantic movement checks. Separately sample
   // the solved clip between endpoints so a heel lift or collision that appears
   // only mid-transition cannot hide behind two valid terminal poses.
-  const diagnosticsCollector = createClipDiagnosticsCollector(diagnosticSampleRateHz);
+  const diagnosticsCollector = createClipDiagnosticsCollector(diagnosticSampleRateHz, clipHasTravel);
   for (let phaseIndex = 0; phaseIndex < tl.segments.length; phaseIndex++) {
     const seg = tl.segments[phaseIndex]!;
     const steps = Math.max(1, Math.ceil((seg.end - seg.start) * diagnosticSampleRateHz));

packages/posecode-eval/test/locomotion-grounding.test.ts

@@ -0,0 +1,47 @@
+import { describe, it, expect } from "vitest";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+import { probeMovement } from "../src/index.js";
+
+const examplesDir = resolve(
+  dirname(fileURLToPath(import.meta.url)),
+  "../../../spec/examples",
+);
+const load = (name: string): string =>
+  readFileSync(resolve(examplesDir, `${name}.posecode`), "utf8");
+
+const footWarnings = (name: string) =>
+  probeMovement(load(name)).diagnostics.warnings.filter((w) =>
+    ["heel-height", "toe-height", "sole-angle", "grounding-rom-conflict"].includes(w.kind),
+  );
+
+/**
+ * A stance foot in a traveling clip rolls onto its ball as the body passes
+ * (push-off) and is briefly airborne at each step transition — correct gait,
+ * not a grounding artifact, so it is exempt from the static flat-foot checks.
+ * A static clip keeps the strict bar, so genuine heel-lift must still surface.
+ */
+describe("locomotion grounding exemption", () => {
+  it("exempts a locomotion stance foot's airborne swing (no large float at a step transition)", () => {
+    // Before the fix, box-step's stance pin was measured while it was still
+    // descending from the previous phase's swing — a ~0.12m heel float and a
+    // ~33° sole tilt mid-transition. The airborne-swing exemption removes those
+    // large phase-transition floats (a smaller settling roll may remain).
+    const large = footWarnings("box-step").filter(
+      (w) =>
+        (w.kind === "heel-height" && w.value > 0.1) ||
+        (w.kind === "sole-angle" && w.value > 30),
+    );
+    expect(large, large.map((w) => w.detail).join("\n")).toHaveLength(0);
+  });
+
+  it("still flags genuine heel-lift in a static deep pose (no over-suppression)", () => {
+    // superhero-landing holds a deep static landing whose shin exceeds the ankle
+    // dorsiflexion ROM; that heel-lift is a real artifact and must stay flagged.
+    const warns = footWarnings("superhero-landing");
+    expect(warns.some((w) => w.kind === "grounding-rom-conflict" || w.kind === "heel-height")).toBe(
+      true,
+    );
+  });
+});