{
  "markdown": "<h1 align=\"center\">Posecode</h1>\n\n<p align=\"center\">\n  <b>Kinematic motion as text.</b>\n  <br />\n  An inspectable, editable movement format for animation tools, LLMs, and web products.\n</p>\n\n<p align=\"center\">\n  Like Mermaid for movement: small text documents for describing, validating, and rendering\n  <br />\n  deterministic human motion without hiding the source inside a black box.\n</p>\n\n<p align=\"center\">\n  <a href=\"https://posecode.org/play\"><b>Live Playground</b></a> ·\n  <a href=\"https://posecode.org/moves/\">Movement Library</a> ·\n  <a href=\"https://posecode.org/spec.html\">Language Specification</a> ·\n  <a href=\"spec/examples\">Examples</a> ·\n  <a href=\"packages/posecode-mcp\">MCP Server</a>\n</p>\n\n<p align=\"center\">\n  <a href=\"https://github.com/posecode-dev/posecode/actions/workflows/ci.yml\">\n    <img src=\"https://github.com/posecode-dev/posecode/actions/workflows/ci.yml/badge.svg\" alt=\"CI status\" />\n  </a>\n  <a href=\"https://www.npmjs.com/package/posecode-parser\">\n    <img src=\"https://img.shields.io/npm/v/posecode-parser.svg?color=emerald\" alt=\"npm version\" />\n  </a>\n  <a href=\"https://github.com/posecode-dev/posecode/blob/main/docs/legal/LICENSING.md\">\n    <img src=\"https://img.shields.io/badge/license-Apache--2.0%20%2B%20AGPL--3.0-blue.svg\" alt=\"Apache 2.0 and AGPL 3.0 licenses\" />\n  </a>\n  <a href=\"https://github.com/posecode-dev/posecode/tree/main/packages/posecode-mcp\">\n    <img src=\"https://img.shields.io/badge/MCP-Compatible-orange.svg\" alt=\"MCP compatible\" />\n  </a>\n</p>\n\n---\n\n## Why Posecode?\n\nAnimation clips and generated trajectories can show movement, but they often hide the semantic decisions that produced it.\n\nPosecode keeps those decisions in readable source. A human can write the document, an animation tool can emit it, or an LLM can draft it. Parsing, validation, editing, and rendering do not require an AI model.\n\n\n<p align=\"center\">\n  <img\n    src=\"docs/media/jumping-jacks.gif\"\n    width=\"440\"\n    alt=\"Jumping jacks rendered from a Posecode document\"\n  />\n</p>\n\n<p align=\"center\">\n  <sub>\n    One <code>.posecode</code> document —\n    <code>shoulders: abduct 160</code>,\n    <code>hips: abduct 30</code>,\n    <code>repeat 12</code> —\n    rendered live in the browser.\n  </sub>\n</p>\n\nFor example:\n\n> Bend your knees, move your hips backward, and keep your chest upright.\n\nA human may understand that instruction, but a renderer cannot reliably determine:\n\n- which joints should move,\n- by how many degrees,\n- in which coordinate frame,\n- over what duration,\n- in what sequence,\n- or within which physical limits.\n\nHumans, tools, and language models all need a shared syntax for expressing movement in a renderable and testable form.\n\nPosecode provides that missing representation.\n\n### See Posecode in 28 seconds\n\nFrom readable movement source to validated 3D rendering, MCP tools, and a\none-script web embed.\n\n<p align=\"center\">\n  <a href=\"docs/launch-media/posecode-cut2-builder-16x9.mp4\">\n    <img\n      src=\"docs/launch-media/posecode-cut2-payoff.png\"\n      width=\"800\"\n      alt=\"Watch the 28-second Posecode builder demo\"\n    />\n  </a>\n</p>\n\n<p align=\"center\">\n  <a href=\"docs/launch-media/posecode-cut2-builder-16x9.mp4\"><b>▶ Watch the 28-second builder demo</b></a>\n  <br />\n  <sub>Plain text in. Smooth, programmable 3D motion out.</sub>\n</p>\n\n### Movement examples\n\n<table align=\"center\">\n  <tr>\n    <td align=\"center\">\n      <img src=\"docs/media/deadlift.gif\" width=\"230\" alt=\"Deadlift rendered from Posecode\" />\n      <br />\n      <sub><code>pelvis: hinge</code> — deadlift</sub>\n    </td>\n    <td align=\"center\">\n      <img src=\"docs/media/squat.gif\" width=\"230\" alt=\"Squat rendered from Posecode\" />\n      <br />\n      <sub><code>knees: flex 95</code> — squat</sub>\n    </td>\n    <td align=\"center\">\n      <img src=\"docs/media/lateral-raise.gif\" width=\"230\" alt=\"Lateral raise rendered from Posecode\" />\n      <br />\n      <sub><code>shoulders: abduct 90</code> — lateral raise</sub>\n    </td>\n  </tr>\n</table>\n\n---\n\n## Why Not Diffusion Text-to-Motion?\n\nNeural text-to-motion systems can generate impressive movement, but they introduce problems for lightweight, programmable applications.\n\n### Resource intensive\n\nMany systems require large models and GPU-backed inference, making real-time consumer deployment expensive.\n\n### Difficult to control\n\nThey usually produce coordinate trajectories rather than editable semantic instructions.\n\nIt is difficult to request a precise change such as:\n\n> Reduce knee flexion by 10 degrees during the second phase.\n\n### Hard to validate\n\nBlack-box trajectories do not naturally expose readable joint rules, phase definitions, or range-of-motion limits.\n\n### Hard to debug\n\nWhen a movement looks wrong, developers may not know which semantic instruction caused the problem.\n\n---\n\n## The Posecode Approach\n\nPosecode uses a lightweight, text-driven pipeline.\n\n- **Readable:** movements are stored as small `.posecode` documents.\n- **Structured:** joints, actions, angles, timings, and constraints are explicit.\n- **Editable:** developers and models can modify individual movement properties.\n- **Fast:** parsing and rendering happen client-side.\n- **Deterministic:** the same Posecode input produces the same validated representation.\n- **Inspectable:** parser warnings and fidelity checks explain problems.\n- **Agent-friendly:** the MCP server exposes generation, validation, critique, and sharing tools.\n- **Safety-aware:** authored and IK-generated angles are constrained by configured range-of-motion limits.\n\n---\n\n## The Idea in 30 Seconds\n\nA `.posecode` file describes movement as timed phases with targeted joint actions.\n\n| 1. Write `.posecode` | 2. Render the movement |\n| :--- | :--- |\n| **`posecode`** `exercise \"Body-weight squat\"`<br />**`rig`** `humanoid`<br />**`pose`** `start = standing`<br /><br />**`step`** `\"Descend\" 1.6s settle`:<br />&nbsp;&nbsp;`hips: flex 80`<br />&nbsp;&nbsp;`knees: flex 95`<br />&nbsp;&nbsp;`ankles: dorsiflex 14`<br />&nbsp;&nbsp;`ground-lock: feet`<br />&nbsp;&nbsp;`cue \"Sit the hips back\"`<br /><br />**`step`** `\"Drive up\" 1.2s drive`:<br />&nbsp;&nbsp;`hips: flex 0`<br />&nbsp;&nbsp;`knees: flex 0`<br />&nbsp;&nbsp;`ankles: dorsiflex 0`<br />&nbsp;&nbsp;`ground-lock: feet`<br /><br />**`repeat`** `8` | <img src=\"docs/media/squat.gif\" width=\"340\" alt=\"Squat animation\" /> |\n\n---\n\n\n\n> **OpenAI Build Week 2026:** Posecode existed before the hackathon. During Build Week, the project was extended using **Codex** — running on **GPT-5.6** — as the primary engineering tool for a real batch of shipped work: motion/grounding quality, language contract diagnostics, licensing restructuring, release automation, and product-facing pages. The sections below distinguish previous work from Build Week work using actual commit history, not a roadmap.\n\n---\n\n## OpenAI Build Week Extension\n\n### What existed before Build Week\n\nBefore Build Week, Posecode already included:\n\n- the core `.posecode` domain-specific language,\n- a parser and intermediate motion representation,\n- basic range-of-motion validation,\n- a Three.js/WebGL renderer,\n- forward kinematics,\n- basic inverse-kinematics and ground-lock behavior,\n- a browser playground,\n- example movement files,\n- shareable Posecode links,\n- and an MCP server foundation.\n\nThis original version was developed primarily with **Claude** as an AI-assisted engineering tool.\n\nThat prior work provides the foundation for the project, but it is not presented as the new hackathon contribution.\n\n### What was added during Build Week\n\nEvery item below is a merged, dated pull request built with Codex (GPT-5.6) — see [Build Week Evidence](#build-week-evidence) for direct links.\n\n1. **Motion and grounding overhaul** — ROM-constrained reach IK, semantic palm/fist/sole/knee/pelvis contact surfaces, multi-contact refinement, stable support handoffs, and XBot-aware grounding ([#76](https://github.com/posecode-dev/posecode/pull/76)).\n2. **Language contract and diagnostics** — Posecode language/IR v0.3 custom start-pose blocks with ROM-checked overrides, live and clip-wide grounding/self-collision diagnostics, and an accessible metric floor guide ([#92](https://github.com/posecode-dev/posecode/pull/92)).\n3. **Licensing restructure** — split the monorepo into an Apache-2.0 standard layer (spec, parser, share, language, LSP, VS Code) and an AGPL-3.0 product layer (render, embed, MCP, eval, playground), with a commercial-license path ([#84](https://github.com/posecode-dev/posecode/pull/84)).\n4. **Release automation** — Changesets-driven npm publishing via GitHub OIDC, MCP Registry publishing, and CI validation of package versions, entry points, and tarball contents ([#66](https://github.com/posecode-dev/posecode/pull/66)).\n5. **Third-party integration readiness** — Posecode 0.2 timing vocabulary (`drive`/`settle`/`flow`/`snap`), a parser validation CLI, and embed compatibility metadata ([#62](https://github.com/posecode-dev/posecode/pull/62)).\n6. **Ground-lock correctness** — parser-owned validation for per-side foot/hand/elbow ground locks and back-contact support for supine movements, replacing silent acceptance of invalid contacts ([#61](https://github.com/posecode-dev/posecode/pull/61), [#64](https://github.com/posecode-dev/posecode/pull/64)).\n7. **LLM-first landing page and product page** — redesigned the landing page around a prompt → Posecode → live 3D story, and added a `/for-products` page documenting the web component, parser, renderer, and MCP server for integrators ([#82](https://github.com/posecode-dev/posecode/pull/82), [#74](https://github.com/posecode-dev/posecode/pull/74)).\n8. **Mobile and search fixes** — mobile toolbar/viewer layout, natural hand orientation, and Google Search indexing corrections ([#78](https://github.com/posecode-dev/posecode/pull/78), [#65](https://github.com/posecode-dev/posecode/pull/65)).\n\n### Build Week feature status\n\n- [x] Motion/grounding quality overhaul shipped ([#76](https://github.com/posecode-dev/posecode/pull/76))\n- [x] Language contract + diagnostics shipped ([#92](https://github.com/posecode-dev/posecode/pull/92))\n- [x] Licensing restructure shipped ([#84](https://github.com/posecode-dev/posecode/pull/84))\n- [x] Release automation shipped ([#66](https://github.com/posecode-dev/posecode/pull/66))\n- [x] Ground-lock correctness shipped ([#61](https://github.com/posecode-dev/posecode/pull/61), [#64](https://github.com/posecode-dev/posecode/pull/64))\n- [x] Landing/product pages shipped ([#82](https://github.com/posecode-dev/posecode/pull/82), [#74](https://github.com/posecode-dev/posecode/pull/74))\n\n---\n\n## How GPT-5.6 Is Used\n\nDuring Build Week, Codex sessions ran on **GPT-5.6** (GPT-5.6 Terra), which is the model that powers Codex for this event. GPT-5.6 is the reasoning engine behind every Build Week change listed above: reading the existing monorepo, proposing the ROM-constrained IK and contact-surface design in [#76](https://github.com/posecode-dev/posecode/pull/76), designing the language/IR v0.3 diagnostics in [#92](https://github.com/posecode-dev/posecode/pull/92), and drafting the licensing boundary in [#84](https://github.com/posecode-dev/posecode/pull/84).\n\nA GPT-5.6-powered natural-language-to-Posecode generation feature (describe a movement in plain English, get a validated `.posecode` document back) is a natural next step given the existing [`posecode_authoring_guide` MCP tool](packages/posecode-mcp/README.md), but it is **not yet built** — it is not claimed as shipped functionality here.\n\n---\n\n## How Codex Is Used\n\nCodex is the primary engineering tool used for the Build Week extension.\n\nDuring the hackathon period, Codex was used to:\n\n- inspect and understand the existing monorepo before each change,\n- design and implement the ROM-constrained reach IK and contact-surface system ([#76](https://github.com/posecode-dev/posecode/pull/76)),\n- design and implement the language/IR v0.3 diagnostics and floor guide ([#92](https://github.com/posecode-dev/posecode/pull/92)),\n- restructure package licensing across the monorepo ([#84](https://github.com/posecode-dev/posecode/pull/84)),\n- build the Changesets/OIDC npm and MCP Registry release pipeline ([#66](https://github.com/posecode-dev/posecode/pull/66)),\n- fix ground-lock validation and silent-acceptance bugs ([#61](https://github.com/posecode-dev/posecode/pull/61), [#64](https://github.com/posecode-dev/posecode/pull/64)),\n- redesign the landing page and add the product integration page ([#82](https://github.com/posecode-dev/posecode/pull/82), [#74](https://github.com/posecode-dev/posecode/pull/74)),\n- write unit, integration, and evaluation-harness tests for each change,\n- and fix mobile UI and search-indexing regressions.\n\nCodex accelerates implementation, but the project remains human-directed. The following decisions were reviewed and selected manually: DSL semantics, system architecture, licensing boundaries, biomechanical constraints, validation policy, user experience, and acceptance or rejection of generated code.\n\n### Codex development workflow\n\nThe Build Week workflow follows this process:\n\n1. Define a specific product or engineering problem.\n2. Ask Codex to inspect the relevant implementation.\n3. Request one or more possible approaches.\n4. Review the trade-offs and choose the architecture.\n5. Use Codex to implement the selected approach.\n6. Run type checking, tests, and biomechanical evaluations (`npm run eval`).\n7. Inspect failures manually.\n8. Refine the implementation with additional Codex sessions.\n9. Review the final changes before committing.\n\n---\n\n## Build Week Evidence\n\nAll Build Week work is public, dated, and directly linked below — no placeholders.\n\n### Build Week pull requests\n\n| PR | Merged | What it did |\n| --- | --- | --- |\n| [#62](https://github.com/posecode-dev/posecode/pull/62) | 2026-07-15 | Posecode 0.2 timing vocabulary, validation CLI, embed compatibility |\n| [#61](https://github.com/posecode-dev/posecode/pull/61) | 2026-07-15 | Per-side ground-lock validation |\n| [#65](https://github.com/posecode-dev/posecode/pull/65) | 2026-07-16 | Google Search indexing fix |\n| [#66](https://github.com/posecode-dev/posecode/pull/66) | 2026-07-16 | npm + MCP Registry release automation |\n| [#64](https://github.com/posecode-dev/posecode/pull/64) | 2026-07-16 | Back ground-lock for supine movements |\n| [#74](https://github.com/posecode-dev/posecode/pull/74) | 2026-07-16 | `/for-products` integration page |\n| [#76](https://github.com/posecode-dev/posecode/pull/76) | 2026-07-17 | Motion/grounding overhaul: ROM-constrained reach IK, contact surfaces |\n| [#78](https://github.com/posecode-dev/posecode/pull/78) | 2026-07-17 | Mobile viewer sizing and natural hand orientation |\n| [#82](https://github.com/posecode-dev/posecode/pull/82) | 2026-07-17 | LLM-first landing page redesign |\n| [#84](https://github.com/posecode-dev/posecode/pull/84) | 2026-07-17 | Apache-2.0 / AGPL-3.0 licensing restructure |\n| [#92](https://github.com/posecode-dev/posecode/pull/92) | 2026-07-19 | Language/IR v0.3, grounding/self-collision diagnostics, floor guide |\n\n### Build Week comparison\n\n| Before Build Week | Added during Build Week |\n| --- | --- |\n| Core Posecode DSL | Language/IR v0.3 custom start-pose blocks |\n| Basic ROM clamping | Grounding, self-collision, and floor-guide diagnostics |\n| Working IK/grounding | ROM-constrained reach IK with semantic contact surfaces |\n| Single license file | Apache-2.0 / AGPL-3.0 layered licensing with commercial path |\n| Manual publishing | Automated npm + MCP Registry release pipeline |\n| Editorial landing page | LLM-first landing page + `/for-products` integration page |\n| Existing tests | New diagnostics, IK, and licensing regression tests |\n\n---\n\n\n---\n\n## Architecture\n\n```text\n┌─────────────────────────┐\n│ Natural-language prompt │\n└────────────┬────────────┘\n             │\n             ▼\n┌─────────────────────────┐\n│ GPT-5.6 authoring layer │\n└────────────┬────────────┘\n             │\n             ▼\n┌─────────────────────────┐\n│     .posecode source    │\n└────────────┬────────────┘\n             │\n             ▼\n┌─────────────────────────┐\n│ Parser and ROM checking │\n└────────────┬────────────┘\n             │\n             ▼\n┌─────────────────────────┐\n│ Kinematics and IK layer │\n└────────────┬────────────┘\n             │\n             ├─────────────────────┐\n             ▼                     ▼\n┌─────────────────────────┐  ┌──────────────────────┐\n│ Three.js/WebGL renderer │  │ Fidelity measurements│\n└─────────────────────────┘  └──────────┬───────────┘\n                                        │\n                                        ▼\n                             ┌──────────────────────┐\n                             │ GPT-5.6 Physics     │\n                             │ Critic and revision │\n                             └──────────────────────┘\n```\n\n---\n\n## Installation and Usage\n\n### Live Playground\n\nPreview, edit, and share movements without installing anything:\n\n**https://posecode.org/play**\n\n---\n\n### Local Development\n\nRequirements:\n\n- Node.js 20 or newer\n- npm\n\nClone the repository:\n\n```bash\ngit clone https://github.com/posecode-dev/posecode.git\ncd posecode\n```\n\nInstall dependencies:\n\n```bash\nnpm install\n```\n\nStart the playground:\n\n```bash\nnpm run dev\n```\n\nRun tests:\n\n```bash\nnpm test\n```\n\nRun type checking:\n\n```bash\nnpm run typecheck\n```\n\nRun fidelity evaluations:\n\n```bash\nnpm run eval\n```\n\nBuild the playground:\n\n```bash\nnpm run build\n```\n\n---\n\n### Editor support\n\nA VS Code extension provides syntax highlighting, ROM diagnostics, and\ncompletion for `.posecode` files — see\n[`editors/vscode`](editors/vscode/README.md). Until it is published, you can\nget basic highlighting immediately by associating `.posecode` files with\nMarkdown:\n\n```json\n\"files.associations\": {\n  \"*.posecode\": \"markdown\"\n}\n```\n\nSee the [editor guide](editors/vscode/README.md#file-association-before-the-extension-is-installed)\nfor VS Code, Cursor, Sublime Text, and Neovim instructions.\n\n---\n\n## MCP Server\n\nPosecode includes a Model Context Protocol server for AI agents.\n\nRun it with:\n\n```bash\nnpx -y posecode-mcp@latest\n```\n\nExample MCP client configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"posecode\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"posecode-mcp@latest\"]\n    }\n  }\n}\n```\n\nThe MCP server exposes:\n\n- `validate_posecode`\n- `render_posecode`\n\nSee [`packages/posecode-mcp`](packages/posecode-mcp) for the complete configuration and tool documentation.\n\n---\n\n## Web Component Embed\n\nEmbed a Posecode player on a page:\n\n```html\n<script src=\"https://unpkg.com/posecode-embed/dist/posecode-embed.js\"></script>\n\n<posecode-player src=\"/movements/squat.posecode\"></posecode-player>\n```\n\nThe player can be used in:\n\n- documentation,\n- educational content,\n- exercise guides,\n- blog posts,\n- and movement libraries.\n\n---\n\n## Core Libraries\n\nInstall the parser:\n\n```bash\nnpm install posecode-parser\n```\n\nInstall the renderer:\n\n```bash\nnpm install posecode-render\n```\n\nExample:\n\n```ts\nimport { parse } from \"posecode-parser\";\nimport { createViewer } from \"posecode-render\";\n\nconst source = `\nposecode exercise \"Lateral raise\"\n  rig humanoid\n  pose start = standing\n\n  step \"Raise\" 1.4s settle:\n    shoulders: abduct 90\n`;\n\nconst { ir, errors, warnings } = parse(source);\n\nif (!ir || errors.length > 0) {\n  console.error(errors);\n} else {\n  console.warn(warnings);\n  const viewer = createViewer(document.querySelector(\"#viewer\"));\n  viewer.load(ir);\n  viewer.play();\n}\n```\n\nThe `#viewer` element is an HTML `<canvas>`.\n\n### Exporting motion (BVH)\n\n`posecode-render` can bake a movement into a [Biovision Hierarchy](https://en.wikipedia.org/wiki/Biovision_Hierarchy)\n(`.bvh`) file for import into Blender and other animation tools. In the\nplayground, use the **Download BVH** button; programmatically:\n\n```ts\nimport { parse } from \"posecode-parser\";\nimport { exportBVH } from \"posecode-render\";\n\nconst { ir } = parse(source);\nconst bvh = exportBVH(ir!, { fps: 30 }); // string, ready to write to disk\n```\n\nOptions: `fps` (default 30), `scale` (default 1 = metres; pass `100` for\ncentimetres), `includeFingers` (default false), and `proportions` for a\ncalibrated rig.\n\n- **Coordinate system:** right-handed, **Y-up**, figure faces **+Z** in the\n  rest pose (identical to the renderer and Three.js). Enable Blender's \"Y up\"\n  BVH import option.\n- **Units:** metres by default.\n- **Rotation channels:** `Zrotation Xrotation Yrotation` (Euler order `ZXY`).\n- **Scope:** this exports the *authored* joint motion plus root travel/turn. It\n  does not yet re-run the renderer's contact/IK solve, so IK-dependent movements\n  (e.g. `reach: hand_left floor`) export the authored pose rather than the\n  solved one. See [issue #63](https://github.com/posecode-dev/posecode/issues/63).\n\n### Exporting motion (glTF / GLB)\n\nFor web animation pipelines, `posecode-render` can export the rig **and** a\nbaked animation clip as a glTF/GLB asset. In the playground, use **Download\nglTF**; programmatically:\n\n```ts\nimport { parse } from \"posecode-parser\";\nimport { exportGLTF } from \"posecode-render\";\n\nconst { ir } = parse(source);\nconst glb = await exportGLTF(ir!);            // GLB ArrayBuffer (default)\nconst gltf = await exportGLTF(ir!, { binary: false }); // glTF JSON object\n```\n\nThe result loads with Three.js [`GLTFLoader`](https://threejs.org/docs/#GLTFLoader.load),\nand the clip plays on the included rig:\n\n```ts\nconst gltf = await new GLTFLoader().loadAsync(url);\nconst mixer = new THREE.AnimationMixer(gltf.scene);\nmixer.clipAction(gltf.animations[0]).play();\n```\n\n- Joint nodes are named by Posecode bone id; the animated root is `posecode_root`.\n- **Limitations:** exports the procedural mannequin rig, not a humanoid/Mixamo\n  skeleton, so there is **no retargeting** onto external rigs yet, and (as with\n  BVH) it bakes the authored motion, not the contact/IK-solved motion. See\n  [issue #90](https://github.com/posecode-dev/posecode/issues/90).\n\n---\n\n## How Posecode Stays Honest\n\nPosecode uses multiple layers of checking.\n\n### 1. Range-of-motion clamping\n\nJoint angles are constrained before rendering.\n\nFor example:\n\n```posecode\nknees: flex 200\n```\n\nis clamped to the configured knee-flexion limit and produces a warning instead of rendering an impossible angle.\n\n### 2. Kinematic evaluation\n\nThe engine measures the actual resulting skeleton after:\n\n- parsing,\n- forward kinematics,\n- inverse kinematics,\n- and ground-lock corrections.\n\n### 3. Geometric fidelity invariants\n\nMovement examples can define expected properties.\n\nFor example, a deadlift may require:\n\n- sufficient torso pitch,\n- limited forward knee travel,\n- stable foot contact,\n- and symmetrical hip movement.\n\n### 4. GPT-5.6 Physics Critic\n\nThe Build Week critic interprets the movement and deterministic measurements together.\n\nIt explains biomechanical problems in natural language and proposes specific revisions.\n\n---\n\n## Packages\n\n| Package | Purpose |\n| --- | --- |\n| [`posecode-language`](packages/posecode-language) | Language definitions and editor support |\n| [`posecode-parser`](packages/posecode-parser) | Converts `.posecode` text into a validated, range-constrained intermediate representation |\n| [`posecode-render`](packages/posecode-render) | Renders animated figures with Three.js, forward kinematics, and IK |\n| [`posecode-share`](packages/posecode-share) | Encodes Posecode documents into URL-safe share tokens |\n| [`posecode-mcp`](packages/posecode-mcp) | Exposes Posecode capabilities to AI agents through MCP |\n| [`posecode-eval`](packages/posecode-eval) | Runs headless biomechanical and geometric fidelity evaluations |\n| [`playground`](playground) | Interactive editor, 3D viewport, warnings, generation, critique, and sharing |\n\n---\n\n## Technology\n\nPosecode is built with:\n\n- TypeScript\n- JavaScript\n- Node.js\n- Three.js\n- WebGL\n- Vite\n- CodeMirror\n- Model Context Protocol\n- Zod\n- Vitest\n- Playwright\n- esbuild\n- GPT-5.6\n- Codex\n\n---\n\n## Scope\n\n### Version 0.1\n\nPosecode currently focuses on:\n\n- single-person human movement,\n- fitness,\n- physiotherapy demonstrations,\n- posture,\n- dance,\n- education,\n- rehabilitation visualization,\n- forward kinematics,\n- ground locking,\n- ROM-constrained inverse kinematics,\n- hip hinging,\n- standing, seated, and lying poses,\n- basic scene props,\n- and browser-based rendering.\n\n### Deferred\n\nThe following are outside the current scope:\n\n- two-person or partner motion,\n- comprehensive collision detection and rigid-body dynamics,\n- detailed object physics,\n- advanced equipment simulation,\n- multi-joint finger animation,\n- FBX or GLB animation export,\n- and medical diagnosis.\n\n---\n\n## Limitations and Safety\n\nPosecode is an engineering and visualization project.\n\nIts range-of-motion values and biomechanical checks are based on general reference data and simplified models.\n\nThey are not:\n\n- medical advice,\n- diagnosis,\n- injury-prevention guarantees,\n- physiotherapy prescriptions,\n- or a substitute for a qualified professional.\n\nGenerated movements should be reviewed by a qualified expert before being used for healthcare, rehabilitation, or safety-critical applications.\n\n---\n\n## Potential Applications\n\nPosecode could support:\n\n- game and character animation,\n- fitness instruction,\n- exercise visualization,\n- anatomy education,\n- physiotherapy demonstrations,\n- posture training,\n- dance and choreography prototyping,\n- sports technique analysis,\n- robotics research,\n- synthetic motion-data generation,\n- and embodied AI systems.\n\n---\n\n## Repository Structure\n\n```text\nposecode/\n├── packages/\n│   ├── posecode-language/\n│   ├── posecode-parser/\n│   ├── posecode-render/\n│   ├── posecode-share/\n│   ├── posecode-mcp/\n│   └── posecode-eval/\n├── playground/\n├── editors/\n├── spec/\n├── docs/\n├── scripts/\n└── README.md\n```\n\n---\n\n## Testing\n\nRun all unit tests:\n\n```bash\nnpm test\n```\n\nRun coverage:\n\n```bash\nnpm run coverage\n```\n\nRun type checking:\n\n```bash\nnpm run typecheck\n```\n\nRun biomechanical evaluations:\n\n```bash\nnpm run eval\n```\n\nThe CI workflow verifies that the project:\n\n- builds successfully,\n- passes type checking,\n- passes unit tests,\n- and satisfies configured movement invariants.\n\n---\n\n## Background\n\nPosecode follows the design study:\n\n> *Kinematic Motion Definition Protocols for Large Language Models*\n\nThe project explores whether semantic, text-based movement programs can provide a controllable and inspectable alternative to black-box motion generation.\n\nThe specification covers:\n\n- DSL design,\n- biomechanical constraints,\n- client-side rendering,\n- agent integration,\n- and possible product applications.\n\nSee:\n\n- [`spec/SPEC.md`](spec/SPEC.md)\n- [`spec/llm-authoring.md`](spec/llm-authoring.md)\n- [`docs/market-research.md`](docs/market-research.md)\n\n---\n\n## Character assets\n\nThe hosted playground currently uses an Adobe Mixamo character and one showcase animation under the applicable Adobe terms. These binary assets are not covered by Posecode's software licenses. See [third-party notices](docs/legal/THIRD_PARTY_NOTICES.md).\n\nThe renderer also includes a zero-asset procedural figure and accepts compatible humanoid GLB characters through `characterUrl`.\n\n### Multiple character appearances (`avatar avatar1` / `avatar2` / `avatar3`)\n\nAll built-in characters use the same `rig humanoid` skeleton topology. An\noptional `avatar` directive selects appearance without redefining that rig (see\n[`spec/SPEC.md`](spec/SPEC.md)). Pass `characterUrls` (selector → GLB URL map)\nto `createViewer` instead of a single `characterUrl`; `ir.avatar` is used when\npresent and `ir.rig` supplies the default selector otherwise. Switching\ndocuments, or editing the `avatar` directive, swaps the visible character. A\nselector with no entry in the map (or any load failure) falls back to the\nprocedural figure. See\n[`packages/posecode-render/README.md`](packages/posecode-render/README.md#usage)\nfor the option, and `packages/posecode-embed`'s `character` attribute docs for\nthe same behavior in the web component (absent by default; set an explicit URL\nto pin one character regardless of `avatar`).\n\n### Bringing your own character rig\n\nPass a `characterUrl` (fixed) or `characterUrls` (per-selector, see above) pointing\nto a skinned GLB to replace the bundled Mixamo character. Requirements:\n\n- **Format:** glTF binary (`.glb`) containing a `THREE.SkinnedMesh`.\n- **Rest pose:** T-pose.\n- **Bone naming:** Mixamo convention. Names may carry the `mixamorig:` /\n  `mixamorigN:` namespace prefix — it's stripped automatically. These bones\n  must all be present:\n  - Torso/head: `Hips`, `Spine`, `Spine2`, `Neck`, `Head`\n  - Arms: `LeftArm`, `LeftForeArm`, `LeftHand`, `RightArm`, `RightForeArm`, `RightHand`\n  - Legs: `LeftUpLeg`, `LeftLeg`, `LeftFoot`, `RightUpLeg`, `RightLeg`, `RightFoot`\n  - Fingers (first phalanx only): `LeftHandThumb1`, `LeftHandIndex1`,\n    `LeftHandMiddle1`, `LeftHandRing1`, `LeftHandPinky1`, and the\n    `RightHand*1` equivalents\n\nIf any required bone is missing, loading the character rejects and the\nviewer silently falls back to the zero-asset procedural figure — a bad rig\nnever breaks the scene.\n\nThe simplest way to source a compatible rig is [mixamo.com](https://www.mixamo.com):\nexport a character in T-pose with \"skin with skeleton,\" then convert\nFBX → GLB (e.g. with Blender's glTF exporter or `FBX2glTF`). Bone names come\nout Mixamo-compatible automatically.\n\nThe bone map and retarget/calibration logic live in\n[`packages/posecode-render/src/character.ts`](packages/posecode-render/src/character.ts).\nSupporting a different naming convention (e.g. VRM humanoid bones) means\nediting the `BONE_MAP` table and `plainName()` prefix-stripping there.\n\n---\n\n## Licensing\n\nPosecode is open source with a clear standard and product boundary:\n\n| Layer | Components | License |\n| --- | --- | --- |\n| Open standard | Specification, examples, parser, share codec, language service, LSP, VS Code extension | Apache-2.0 |\n| Product layer | Renderer, web embed, MCP server, eval harness, hosted playground | AGPL-3.0-only |\n\nOrganizations that need to use an AGPL component in a closed-source product may contact [hello@posecode.org](mailto:hello@posecode.org?subject=Posecode%20commercial%20license) about a separate commercial agreement.\n\nEarlier grants are unchanged. MIT revisions remain MIT, and the 0.2.2 npm packages remain Apache-2.0. See [licensing](docs/legal/LICENSING.md), [commercial licensing](docs/legal/COMMERCIAL-LICENSE.md), and [trademark policy](docs/legal/TRADEMARK.md).\n\n---\n\n## Feedback and Support\n\nFeedback and contributions are welcome.\n\n- Email: [hello@posecode.org](mailto:hello@posecode.org?subject=Posecode%20Feedback)\n- Issues: [GitHub Issues](https://github.com/posecode-dev/posecode/issues)\n\n---\n<p align=\"center\">\n  <b>Animation tools, LLMs, and web products need movement they can inspect.</b>\n  <br />\n  <b>Posecode makes movement readable source.</b>\n</p>\n",
  "bytes": 30874,
  "sha": "dc0f9541672ebc65f19be632e4a5a8146e54bd3eb8efb7d344d5703812223215",
  "repo_slug": "posecode-dev/posecode",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_posecode_dev_posecode_mcp_430aca8c/readme"
}