chore: initial commit — Movit kinematic motion protocol

Mermaid-style .movit DSL that renders to an animated 3D figure.
Monorepo: parser, renderer, share codec, MCP server, language
service, LSP, VS Code extension, plus the playground + landing.

Author: a-baran-orhan

.claude/launch.json

@@ -0,0 +1,11 @@
+{
+  "version": "0.0.1",
+  "configurations": [
+    {
+      "name": "playground",
+      "runtimeExecutable": "npm",
+      "runtimeArgs": ["run", "dev", "-w", "playground"],
+      "port": 5173
+    }
+  ]
+}

.gitignore

@@ -0,0 +1,7 @@
+node_modules/
+dist/
+coverage/
+*.tsbuildinfo
+.DS_Store
+.vite/
+.vercel

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Movit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,91 @@
+<h1 align="center">◆ Movit</h1>
+
+<p align="center"><b>Kinematic motion as text.</b> Mermaid gave LLMs a way to draw diagrams.<br/>
+Movit gives them a way to <i>show movement</i> — exercises, physiotherapy, posture —<br/>
+as a tiny human-readable language that renders to an animated 3D figure in the browser.</p>
+
+---
+
+## Why
+
+Ask an LLM to explain a push-up and it can only give you prose or a flat image.
+The model *knows* the biomechanics ("elbows flex, shoulders abduct on the
+descent") — it just has no syntax to express it that a renderer can read.
+Diffusion-based text-to-motion models exist, but they're heavy, expensive, and
+give you no fine control over the anatomical phases.
+
+Movit takes the opposite, lightweight approach (see [the research](#background)):
+
+- The LLM writes a small **`.movit`** document — semantic phases, not 3D matrices.
+- A **client-side** parser + Three.js renderer animates it. Generation is a
+  fraction of a cent of text; rendering runs at 60fps on a phone.
+- Every angle is **hard-clamped to a healthy range of motion**, so a model
+  hallucinating "knee flex 200°" can't produce an anatomically impossible joint.
+
+```movit
+movit exercise "Body-weight squat"
+  rig humanoid
+  pose start = standing
+
+  step "Descend" 1.6s ease-in-out:
+    hips: flex 80
+    knees: flex 95
+    ankles: dorsiflex 14
+    ground-lock: feet
+    cue "Sit the hips back, chest proud, knees track over the toes"
+
+  step "Drive up" 1.2s ease-out:
+    hips: flex 0
+    knees: flex 0
+    ankles: dorsiflex 0
+    ground-lock: feet
+    cue "Drive through the heels to stand tall"
+
+  repeat 8
+```
+
+## Try it
+
+```bash
+npm install
+npm run dev      # opens the playground (Vite) at http://localhost:5173
+npm test         # parser + renderer test suites
+```
+
+In the playground: pick an example, watch it animate, edit the text live, and
+hit **Copy LLM prompt** to get a system prompt that teaches ChatGPT/Claude to
+write Movit for you.
+
+## Packages
+
+| Package | What it does |
+| --- | --- |
+| [`movit-parser`](packages/movit-parser) | `.movit` text → validated, ROM-clamped IR. Pure TypeScript, framework-agnostic. |
+| [`movit-render`](packages/movit-render) | IR → animated low-poly mannequin (Three.js), forward kinematics + ground-lock CCD IK. |
+| [`movit-share`](packages/movit-share) | Encode a `.movit` doc to a URL-safe token so a movement travels as a link. Pure, dependency-free. |
+| [`movit-mcp`](packages/movit-mcp) | MCP server: lets an LLM agent author, ROM-validate, and get a render link for a movement — natively. |
+| [`playground`](playground) | Live editor + 3D viewport + warnings + the LLM prompt + shareable links. |
+
+The protocol and both libraries are **MIT-licensed** — the open core. See
+[`spec/SPEC.md`](spec/SPEC.md) for the full language and
+[`spec/llm-authoring.md`](spec/llm-authoring.md) for the authoring prompt.
+
+## Scope (v0.1)
+
+✅ Single-person fitness, stretching & posture · Mermaid-style DSL · ROM safety
+clamping · forward kinematics · ground-lock IK · live playground.
+
+⏳ Deferred: reach-IK, two-person / partner movements + collision detection,
+FBX/GLB export, hosted SaaS editor and the expert-verified motion marketplace.
+
+## Background
+
+This project follows a design study, *"Kinematic Motion Definition Protocols for
+Large Language Models"*, which argues for a semantic DSL over diffusion models,
+specifies ROM-based safety constraints from clinical normative data, and lays
+out the open-core commercialization path. The spec cross-references its
+sections (§4 DSL, §5 biomechanics, §6 client rendering, §7 strategy).
+
+> ⚠️ Movit's range-of-motion values are general literature data, not medical
+> advice. Consult a qualified professional for physiotherapy or exercise
+> prescription.

VERCEL_AGENTS.md

@@ -0,0 +1,68 @@
+# Vercel Plugin — AI Agent Instructions
+
+> Drop this file into any GitHub repo. AI coding agents (Claude Code, Codex, Cursor, Copilot, Grok Build) will pick it up automatically.
+
+## Setup (one-time per machine)
+
+```bash
+npx plugins add vercel/vercel-plugin
+```
+
+Requires Node.js 18+ and Bun. After install, session context is injected automatically for Vercel/Next.js projects.
+
+## Slash commands
+
+| Command | Purpose |
+|---|---|
+| `/vercel-plugin:bootstrap` | Link project, provision env vars, set up DB |
+| `/vercel-plugin:deploy` | Deploy preview; pass `prod` for production |
+| `/vercel-plugin:env` | List, pull, add, remove, diff env vars |
+| `/vercel-plugin:status` | Recent deployments and environment overview |
+| `/vercel-plugin:marketplace` | Discover and install Marketplace integrations |
+
+## Key skills (invoke on demand)
+
+- `nextjs` — App Router, Server Components, Server Actions, rendering strategies
+- `ai-sdk` — AI SDK v6: streaming, tool calling, agents, MCP, embeddings
+- `ai-gateway` — Unified API to 100+ models with failover and cost tracking
+- `vercel-functions` — Serverless, Edge, Fluid Compute, streaming, Cron Jobs
+- `vercel-storage` — Blob, Edge Config, Neon Postgres, Upstash Redis
+- `deployments-cicd` — Deploy, promote, rollback, `--prebuilt`, CI config
+- `env-vars` — `.env` files, `vercel env`, OIDC tokens
+- `routing-middleware` — Rewrites, redirects, personalization (Node.js/Edge/Bun)
+- `runtime-cache` — Per-region KV cache with tag-based invalidation
+- `shadcn` — shadcn/ui CLI, components, theming, Tailwind integration
+- `workflow` — Durable execution, DurableAgent, steps, pause/resume
+- `vercel-sandbox` — Ephemeral VMs for running untrusted/AI-generated code
+- `verification` — Browser, API, data, and response flow verification
+
+## Specialist agents
+
+- `deployment-expert` — CI/CD, deploy strategies, environment variables, rollbacks
+- `performance-optimizer` — Core Web Vitals, caching, rendering, asset optimization
+- `ai-architect` — AI app design, model selection, streaming, MCP integration
+
+## Platform defaults to assume
+
+- Framework: Next.js App Router
+- Compute: Fluid Compute (not legacy Edge Functions)
+- Node.js: 24 LTS (18 is deprecated)
+- Function timeout: 300s default
+- AI SDK: v6 with `"provider/model"` strings via AI Gateway
+- Config: `vercel.ts` preferred over `vercel.json`
+- Databases: Via Vercel Marketplace (Vercel Postgres/KV are retired)
+
+## Telemetry
+
+```bash
+export VERCEL_PLUGIN_TELEMETRY=off   # disable
+export VERCEL_PLUGIN_LOG_LEVEL=debug # enable debug logs
+```
+
+```bash
+npx vercel-plugin doctor  # validate plugin health
+```
+
+## Issues
+
+File bugs at <https://github.com/vercel/vercel-plugin/issues> with debug logs enabled.

editors/vscode/README.md

@@ -0,0 +1,27 @@
+# Movit for VS Code
+
+Language support for the **Movit** (`.movit`) kinematic motion DSL:
+
+- **Syntax highlighting** (TextMate grammar) — keywords, kinds, joints, actions, easings, strings, numbers.
+- **Diagnostics** — parse errors and **range-of-motion safety clamps** as you type (e.g. `knees: flex 200° → clamped to 144°`).
+- **Completion** — context-aware: kinds after `movit`, joints at line start, actions after `<joint>:`, easings in a `step` header, poses after `pose start =`, effectors after `ground-lock:`.
+- **Hover** — the safe ROM range for a joint + action, and short docs for keywords.
+
+The smart features are provided by [`movit-lsp`](../../packages/movit-lsp), which shares its language logic ([`movit-language`](../../packages/movit-language)) with the web playground — so the editor and the playground always agree.
+
+## Develop / run locally
+
+From the repo root:
+
+```bash
+npm install
+npm run build -w movit-vscode   # compiles the client + bundles the LSP to dist/server.cjs
+```
+
+Then open this folder in VS Code and press **F5** ("Run Extension") to launch an Extension Development Host, and open any `.movit` file.
+
+## Package
+
+```bash
+npx @vscode/vsce package   # produces movit-vscode-0.1.0.vsix
+```

editors/vscode/language-configuration.json

@@ -0,0 +1,11 @@
+{
+  "comments": {
+    "lineComment": "#"
+  },
+  "brackets": [["[", "]"]],
+  "autoClosingPairs": [
+    { "open": "\"", "close": "\"" },
+    { "open": "[", "close": "]" }
+  ],
+  "surroundingPairs": [["\"", "\""]]
+}

editors/vscode/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "movit-vscode",
+  "private": true,
+  "displayName": "Movit",
+  "description": "Language support for the Movit (.movit) kinematic motion DSL — syntax highlighting, range-of-motion diagnostics, completion, and hover.",
+  "version": "0.1.0",
+  "license": "MIT",
+  "engines": {
+    "vscode": "^1.85.0"
+  },
+  "categories": ["Programming Languages"],
+  "activationEvents": ["onLanguage:movit"],
+  "main": "./dist/extension.js",
+  "contributes": {
+    "languages": [
+      {
+        "id": "movit",
+        "aliases": ["Movit", "movit"],
+        "extensions": [".movit"],
+        "configuration": "./language-configuration.json"
+      }
+    ],
+    "grammars": [
+      {
+        "language": "movit",
+        "scopeName": "source.movit",
+        "path": "./syntaxes/movit.tmLanguage.json"
+      }
+    ]
+  },
+  "scripts": {
+    "compile": "tsc -p ./",
+    "bundle-server": "esbuild ../../packages/movit-lsp/src/server.ts --bundle --platform=node --format=cjs --outfile=dist/server.cjs",
+    "build": "npm run compile && npm run bundle-server"
+  },
+  "dependencies": {
+    "vscode-languageclient": "^9.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "@types/vscode": "^1.85.0",
+    "esbuild": "^0.24.2",
+    "typescript": "^5.7.2"
+  }
+}

editors/vscode/src/extension.ts

@@ -0,0 +1,42 @@
+/**
+ * Movit VS Code extension entry point.
+ *
+ * Syntax highlighting comes from the bundled TextMate grammar; everything
+ * smarter (range-of-motion diagnostics, completion, hover) comes from the
+ * Movit language server, which this client launches over stdio. The server is
+ * bundled to `dist/server.cjs` by `npm run build` so it runs with plain node.
+ */
+
+import * as path from "node:path";
+import { type ExtensionContext } from "vscode";
+import {
+  LanguageClient,
+  type LanguageClientOptions,
+  type ServerOptions,
+  TransportKind,
+} from "vscode-languageclient/node";
+
+let client: LanguageClient | undefined;
+
+export function activate(context: ExtensionContext): void {
+  const serverModule = context.asAbsolutePath(path.join("dist", "server.cjs"));
+  const serverOptions: ServerOptions = {
+    run: { module: serverModule, transport: TransportKind.stdio },
+    debug: { module: serverModule, transport: TransportKind.stdio },
+  };
+  const clientOptions: LanguageClientOptions = {
+    documentSelector: [{ scheme: "file", language: "movit" }],
+  };
+
+  client = new LanguageClient(
+    "movit",
+    "Movit Language Server",
+    serverOptions,
+    clientOptions,
+  );
+  void client.start();
+}
+
+export function deactivate(): Thenable<void> | undefined {
+  return client?.stop();
+}

editors/vscode/syntaxes/movit.tmLanguage.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "https://raw.githubusercontent.com/martinring/tmlanguage/master/tmlanguage.json",
+  "name": "Movit",
+  "scopeName": "source.movit",
+  "patterns": [
+    { "include": "#comments" },
+    { "include": "#strings" },
+    { "include": "#keywords" },
+    { "include": "#kinds" },
+    { "include": "#actions" },
+    { "include": "#joints" },
+    { "include": "#constants" },
+    { "include": "#numbers" }
+  ],
+  "repository": {
+    "comments": {
+      "patterns": [
+        { "name": "comment.line.number-sign.movit", "match": "#.*$" },
+        { "name": "comment.line.double-slash.movit", "match": "//.*$" }
+      ]
+    },
+    "strings": {
+      "name": "string.quoted.double.movit",
+      "begin": "\"",
+      "end": "\"",
+      "patterns": [
+        { "name": "constant.character.escape.movit", "match": "\\\\." }
+      ]
+    },
+    "keywords": {
+      "name": "keyword.control.movit",
+      "match": "\\b(movit|rig|pose|start|step|repeat|ground-lock|cue|hold)\\b"
+    },
+    "kinds": {
+      "name": "storage.type.movit",
+      "match": "\\b(exercise|stretch|posture)\\b"
+    },
+    "actions": {
+      "name": "keyword.operator.movit",
+      "match": "\\b(flex|extend|abduct|adduct|rotate-in|rotate-out|supinate|pronate|dorsiflex|plantarflex)\\b"
+    },
+    "joints": {
+      "name": "variable.other.movit",
+      "match": "\\b(shoulders|elbows|wrists|hips|knees|ankles|pelvis|spine|chest|neck|head|shoulder_left|shoulder_right|elbow_left|elbow_right|wrist_left|wrist_right|hip_left|hip_right|knee_left|knee_right|ankle_left|ankle_right)\\b"
+    },
+    "constants": {
+      "name": "constant.language.movit",
+      "match": "\\b(ease-in-out|ease-in|ease-out|linear|neutral|standing|plank|hands|feet|humanoid)\\b"
+    },
+    "numbers": {
+      "name": "constant.numeric.movit",
+      "match": "\\b[0-9]+(\\.[0-9]+)?s?\\b"
+    }
+  }
+}