Address feedback on diagnostics and authoring (#92)

* Address feedback on diagnostics and authoring

Signed-off-by: a-baran-orhan <a.baranorhan@gmail.com>

* Stabilize fixture scorecard test

Signed-off-by: a-baran-orhan <a.baranorhan@gmail.com>

* fix: keep deadlift heels planted through the hip hinge

The deadlift's Lower phase rose onto the balls of the feet at the bottom
of the hinge: with knees flexed 25° the shin tilted 25° forward, but
keeping the sole flat needs the ankle to dorsiflex that far while its ROM
caps dorsiflexion at 15°, so levelPlantedFeet clamped at the limit and
left a ~3.2cm heel lift.

Ease the Lower-phase knee flexion 25° → 14° so the shin only tilts as far
as the ankle can absorb. A hip hinge keeps soft knees and near-vertical
shins anyway, so both soles now stay flat on the floor across the whole
clip (0.00cm heel lift, no grounding warnings).

Raising the ankle dorsiflexion ROM was explored but reverted: the
superhero-landing fixture's planted foot fights its floor reaches across
the XBot and procedural proportions once the ROM widens, so a global ROM
bump can't stay green in `npm run eval` without a larger landing redesign.

---------

Signed-off-by: a-baran-orhan <a.baranorhan@gmail.com>

Author: a-baran-orhan

.changeset/bright-dancers-guide.md

@@ -0,0 +1,14 @@
+---
+"posecode-parser": minor
+"posecode-render": minor
+"posecode-embed": minor
+"posecode-mcp": patch
+---
+
+Add scoped, ROM-checked custom start-pose overrides with deterministic loop resets, Posecode language/IR v0.3 metadata, and updated authoring guidance.
+
+Expose solved-frame grounding and residual self-collision diagnostics, plus a metric floor guide with facing, authored travel, and loop-reset paths.
+
+Keep the renderer peer range compatible with the parser's new start-pose IR.
+
+Keep the MCP initialization identity synchronized with its published package version.

ROADMAP.md

@@ -18,7 +18,7 @@ domain needs, so contributions land where they unlock the most.
 | **Fitness / strength** | Body-weight and free-form movement coaching |  Core today (squat, curl, raise). Barbell/dumbbell/machine work needs props + grip. |
 | **Functional / elderly care** | Sit-to-stand, balance, gentle ROM, fall-prevention drills |  Partial: sit-to-stand works; reaching/balance need reach-IK + props. |
 | **Sports technique** | Golf swing, tennis serve, throwing, kicking |  Partial: needs trunk rotation fidelity, weight shift, and implements (club/racket/ball). |
-| **Dance / choreography** | Notating sequences, port de bras, phrases that turn & travel |  Phrases, port de bras, pirouettes, and traveling combos (box-step, grapevine, chassé) work via `turn`/`travel`; partner work is future. |
+| **Dance / choreography** | Notating sequences, port de bras, phrases that turn & travel |  `turn` / `travel` and several experimental examples exist. Ballet terminology, technique fidelity, spotting, and floor-pattern readability still need expert review; partner work is future. |
 | **Martial arts** | Stances, strikes, basic forms |  Stances/strikes partly work; contact and weapons are future. |
 | **Sign language / gesture** | Finger-spelling, signs, expressive gesture |  Partial: single-DOF finger curls render visibly (fist, pinch, wave, rough finger-spelling); exact sign language needs multi-joint fingers + wrist orientation. |
 
@@ -65,6 +65,33 @@ These are the unlocks, roughly in order of leverage:
 7. **Two-person + collision**: partner stretches, assisted rehab, contact sports
    (still deferred in the spec).
 
+## Feedback-driven implementation order (July 2026)
+
+This sequence turns the first external-user review into small, testable slices. It
+starts with correctness and observability, then builds one shared motion-export
+foundation before adding formats. The detailed dance/UAT list remains in
+[issue #91](https://github.com/posecode-dev/posecode/issues/91), glTF in
+[issue #90](https://github.com/posecode-dev/posecode/issues/90), and BVH in
+[issue #63](https://github.com/posecode-dev/posecode/issues/63).
+
+| Order | Slice | Completion evidence |
+| --- | --- | --- |
+| 0 | **Clarify the language contract.** Keep the public spec canonical, distinguish it from the LLM guide, define `ground-lock` / `reach` / `pin` / `grip`, and state that cues are display-only. | Implemented in the feedback branch with documentation-contract, playground, and renderer regression tests. |
+| 1 | **Make current solver failures visible.** Add heel/toe height, sole-angle, foot-drift, and residual-collision diagnostics over whole clips. Reproduce the deadlift, demi-plié, and arms-lowering reports as fixtures. | **Implemented in the feedback branch.** Live viewer warnings and 12Hz clip diagnostics now name the grounding/ROM conflict or residual collision; strict known failures remain non-gating until their solver fixes land. |
+| 2 | **Add small authoring controls.** Support a built-in start pose plus sparse joint overrides; improve floor origin, facing, and metre-scale markers. | **Implemented in the feedback branch.** Parser, LSP, share-link, loop-reset, floor-guide, travel/reset-path, accessibility, and responsive UI tests cover the new behavior. |
+| 3 | **Separate shape from motion limits.** Introduce explicit, named ROM profiles and contact-aware ankle limits. Do not infer movement limits from a `male` / `female` label; body proportions, rig topology, and an individual's mobility are separate inputs. | General and expert-reviewed dance profiles produce deterministic clamp diagnostics; old documents retain today's default. |
+| 4 | **Run expert dance UAT.** Mark unreviewed ballet examples experimental; record the school/convention and reviewer; then fix demi-plié, rise terminology, pirouette/spotting, and chassé mechanics. | Each promoted example has a reviewer/reference and pose/contact/orientation regression checks. |
+| 5 | **Extract a solved-motion sampler.** Move the final post-grounding, post-IK, post-collision pose sampling out of the viewer so evaluation and exporters consume identical transforms. | Configurable-FPS samples round-trip through the viewer with matching root and local joint transforms. |
+| 6 | **Ship glTF/GLB export.** First export one compatible skinned rig plus one baked animation clip; then add multiple clips on the same rig and minimal editable materials. | Three.js `GLTFLoader` round-trip plus a Godot smoke test; no retargeting required for the first version. |
+| 7 | **Ship BVH export from the same sampler.** Specify hierarchy, axes, units, Euler order, frame time, and end sites before serializing. | `BVHLoader` round-trip plus documented Blender import/export validation. |
+| 8 | **Broaden the pipeline.** Add configurable rig adapters/retargeting, then a visual authoring layer and optional natural-language front end. Explore Labanotation only as a bounded translator with an explicit unsupported-feature report. | Additional rigs pass adapter fixtures; non-code edits remain deterministic and export the same motion as text-authored documents. |
+
+Natural-language animation is best treated as an input surface, not the competing
+core. Posecode's role is the deterministic, inspectable, editable constraint and
+interchange layer underneath a prompt UI, visual editor, cache, or generated clip.
+The comparison should be measured on repeatability, targeted edits, contact
+correctness, diagnostics, and export—not only first-draft generation speed.
+
 ## Prop / equipment library (future)
 
 Each prop is a small scene object + an anchor type; movements then reference it
@@ -86,7 +113,16 @@ Each prop is a small scene object + an anchor type; movements then reference it
 
 ## Current limitations (honest)
 
-- One figure only; partner work and collision are still deferred.
+- One figure only; partner work and inter-person collision are still deferred.
+- The character adapter currently expects a Mixamo-compatible bone set. Body
+  proportions can vary, but arbitrary naming/topology and distributing motion
+  across extra spine or shoulder bones are not supported yet.
+- Range-of-motion uses one general profile. It is not individualized by body,
+  training background, task, or weight-bearing context.
+- 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.
 - 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.

package-lock.json

@@ -9,7 +9,7 @@ the movement as an animated 3D figure, right where a share link would have gone.
 ## Quick start (CDN, no build step)
 
 ```html
-<script src="https://unpkg.com/posecode-embed@0.2.0/dist/posecode-embed.js"></script>
+<script src="https://unpkg.com/posecode-embed@latest/dist/posecode-embed.js"></script>
 
 <!-- 1. From a share token (what a posecode.org permalink carries) -->
 <posecode-player doc="cG9zZWNvZGUgZXhlcmNpc2Ug…"></posecode-player>
@@ -35,9 +35,9 @@ posecode exercise "Lateral raise"
 The script auto-registers the element and boots each player when it scrolls into
 view. That's it.
 
-Pin a package version in production, as above, so a deployment always uses a
-known parser/render pair. A `src` URL can be relative or absolute; cross-origin
-movement files must be served with CORS permission.
+Replace `@latest` with an exact package version in production so a deployment
+always uses a known parser/render pair. A `src` URL can be relative or absolute;
+cross-origin movement files must be served with CORS permission.
 
 ## With a bundler
 
@@ -116,7 +116,7 @@ console.log(Posecode.version, Posecode.languageVersion, result.errors);
 For a movement library in CI, run:
 
 ```bash
-npx posecode-parser@0.2.0 validate --strict ./movements
+npx posecode-parser@latest validate --strict ./movements
 ```
 
 AGPL-3.0-only, part of [Posecode](https://github.com/posecode-dev/posecode). A [separate commercial license](https://github.com/posecode-dev/posecode/blob/main/docs/legal/COMMERCIAL-LICENSE.md) is available for closed-source product use.

packages/posecode-embed/README.md

@@ -28,6 +28,6 @@ describe("embed compatibility contract", () => {
       readFileSync(resolve(import.meta.dirname, "../package.json"), "utf8"),
     ) as { version: string };
     expect(version).toBe(pkg.version);
-    expect(languageVersion).toBe("0.2");
+    expect(languageVersion).toBe("0.3");
   });
 });