Address feedback on diagnostics and authoring

[a-baran-orhan]

Summary

• Make the formal specification the canonical language contract, clarify contact directives and display-only cues, and expose the spec directly from the playground.
• Add Posecode language/IR v0.3 custom start-pose blocks: a built-in pose plus sparse, ROM-checked joint overrides, with parser, completion/LSP, share-link, MCP-guide, reset, and documentation coverage.
• Add live and clip-wide grounding, sole-angle, planted-drift, ankle-ROM-conflict, and bounded residual self-collision diagnostics. The deadlift, demi-plié, and arms-lowering reports are now reproduced and named instead of failing silently.
• Add an accessible metric floor guide with load origin, current facing, one-metre scale, authored travel, waypoints, and a dashed implicit loop-reset path.
• Add release metadata/compatibility safeguards for the parser peer range, protocol version, embed language version, and MCP server identity.

Why

External UAT in #91 exposed four connected problems: the language contract was hard to discover, custom opening shapes were impossible without adding a phase, ground-lock/collision failures were silent, and turns/travel were difficult to read spatially.

The underlying causes were split documentation, a fixed preset-only timeline base pose, no public residual-measurement layer after solving, and a visually unscaled floor. This PR adds the smallest deterministic authoring and observability layers before changing ROM profiles or solver policy.

Impact and compatibility

• Existing one-line start poses remain valid. A scoped override block is additive; duplicate pose start declarations now produce an explicit error instead of silently replacing an earlier declaration.
• Viewer.getConstraintDiagnostics() and clip diagnostics expose measured outcomes without changing authored motion or current CI gates.
• Live diagnostics are cached at roughly 5 Hz, skipped during internal anchor precomputation, and refreshed after load/seek/playback changes.
• Constraint diagnostics describe the post-solver procedural driver before optional skin/mocap surface reconciliation. Self-collision remains limited to the renderer's existing bounded pairs.
• The floor guide defaults on and can be disabled with floorGuide: false.
• The changeset advances the fixed public package group to 0.4.0; the language/IR contract is explicitly v0.3.
• This does not yet change generalized ROM profiles, add comprehensive collision physics, or implement glTF/BVH export. Those larger slices remain on the roadmap (Add glTF animation export #90 and Add BVH motion export #63).

Validation

• npm test — 35 files, 393 tests passed
• npm run typecheck
• npm run eval — 1,561/1,561 biomechanical checks across the production XBot and procedural rigs; newly surfaced known constraints remain non-gating warnings
• npm run build:packages
• npm run check:packages — 5 publishable packages validated
• npm run build
• npx changeset status — five fixed-group packages at minor, no accidental majors
• Desktop and 390×844 browser QA: custom start pose, travel/reset paths, paused-scrub warnings, responsive legend, and no console errors

AI assistance

Material AI assistance was used to implement, test, review, and document this change under the maintainer's direction. The resulting diff was independently reviewed within the task and validated with the checks above.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
posecode	Ready	Preview, Comment	Jul 19, 2026 6:27pm