Merge remote-tracking branch 'origin/main' into codex/position-movement-format

# Conflicts:
#	playground/public/moves/box-step.html
#	playground/public/moves/chasse.html
#	playground/public/moves/grapevine.html
#	playground/public/moves/index.html
#	playground/public/moves/seated-torso-twist.html
#	playground/public/moves/shoulder-blade-retraction.html
#	playground/public/moves/walk-cycle.html
#	playground/public/moves/waltz-box.html
#	playground/public/moves/wrist-forearm-rolls.html
#	playground/src/main.ts

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.

docs/README.md

@@ -26,5 +26,6 @@ The repository root retains the canonical [`LICENSE`](../LICENSE) and [`NOTICE`]
 
 ## Development references
 
+- [Product usage analytics](product-analytics.md)
 - [Vercel agent notes](development/VERCEL_AGENTS.md)
 - [Pose diagnostics summary](diagnostics/pose-summary.json)

docs/product-analytics.md

@@ -0,0 +1,71 @@
+# Product usage analytics
+
+Posecode keeps Vercel pageviews and product-usage events separate. Pageviews
+answer “which routes were visited?”; the events below answer “did someone use
+the product?”
+
+## Provider and production configuration
+
+The implementation is provider-neutral at the call sites. Event names, payload
+types, failure isolation, and session deduplication live in
+`playground/src/analytics.ts`. The current adapter is
+`playground/src/vercel-analytics.ts`.
+
+Vercel Web Analytics pageviews remain enabled without extra configuration.
+Vercel's current plan table says custom events are **not available on Hobby**;
+they are available on Pro and Enterprise. Pro allows at most two properties per
+custom event. The schema below deliberately stays within that limit.
+
+To enable product events on a Vercel Pro or Enterprise production project:
+
+1. Enable Web Analytics for the project in Vercel.
+2. Set `VITE_PRODUCT_ANALYTICS_PROVIDER=vercel` for the Production environment.
+3. Redeploy so Vite includes the provider choice in the client bundle.
+4. Exercise one event and confirm it in **Project → Analytics → Events**.
+
+Do not set the variable on Hobby expecting dashboard data: Hobby continues to
+show pageviews but does not expose custom events. No alternate paid analytics
+vendor is installed. A future adapter can call `configureUsageAnalytics`
+without changing UI event call sites.
+
+Sources:
+
+- [Vercel custom events](https://vercel.com/docs/analytics/custom-events)
+- [Vercel Web Analytics limits and pricing](https://vercel.com/docs/analytics/limits-and-pricing)
+
+## Event dictionary
+
+| Event | Fires when | Properties |
+|---|---|---|
+| `preset_opened` | A bundled movement is actually opened at initial load or selected in the library. | `source`: `library`, `direct_url`, `shared_link`, or `landing_cta`; `preset_id`: bundled stable ID |
+| `editor_changed` | The first real CodeMirror user edit in the page session. Programmatic preset loads do not count. | `document_kind`: `preset`, `shared`, or `custom` |
+| `render_succeeded` | `viewer.load()` successfully accepts a new meaningful document revision. Lazy boot and repeated recompiles of the same revision are deduplicated. The animation frame loop never emits this event. | `trigger`: `initial`, `preset_open`, `shared_link`, or `editor_change`; `document_kind` |
+| `share_created` | The generated preset/encoded URL has successfully been written to the clipboard. | `share_kind`: `preset` or `encoded` |
+| `embed_docs_clicked` | The embed documentation CTA on `/for-products` is clicked. | `location`: `for_products` |
+| `install_command_copied` | An npm/npx command on `/for-products` is successfully written to the clipboard. | `command`: `embed`, `packages`, or `mcp`; `location`: `for_products` |
+
+## Reading the dashboard
+
+Open **Analytics → Events**, select an event, then drill into its properties.
+Useful readings include:
+
+- `preset_opened` grouped by `source` separates library discovery from direct,
+  shared, and landing-page entry.
+- Compare `editor_changed` and `render_succeeded` counts to see whether editing
+  reaches a valid renderer update. They are intentionally not a strict funnel:
+  initial and preset renders also count.
+- `share_created` is a confirmed clipboard outcome, not a button-click count.
+- Group `install_command_copied` by `command` to compare integration intent.
+
+Vercel reports aggregate events rather than a user-level funnel. Do not attempt
+to join individual visitors or reconstruct sessions from these payloads.
+
+## Privacy and resilience
+
+Events never contain Posecode source text, authoring prompts, personal data,
+full share tokens, query strings, referrers, or sensitive URLs. `preset_id` is a
+bounded public catalogue identifier; all other values are closed enums.
+
+Every analytics call is best-effort and catches provider failures. Ad blockers,
+network failures, a missing provider configuration, or plan limitations do not
+change editing, rendering, sharing, navigation, or clipboard behavior.

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:

package-lock.json

@@ -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/diagnostics.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));