Rive Analyzer

v1.1.0 — "Living Canvas"

Where your animation goes from a file to a living product.

Inspect, validate, control, and ship Rive .riv animation files — from the terminal, AI assistants, or a visual playground. The complete toolchain for teams that build with Rive at scale.

---

What's New in v1.1.0 — "Living Canvas"

Area	Feature
Parser	Animation loopType — oneShot / loop / pingPong
Parser	workStart / workEnd frame range per animation
Parser	ViewModel extraction — real data from viewModelCount() / getProperties()
Parser	DataEnum extraction — full enum names and values
CLI	list-assets — enumerate embedded/CDN images, fonts, audio
CLI	init — scaffold .rive-playground/ project directory
CLI	contract-generate — generate .rive-contract.yaml from .riv
CLI	contract-validate — validate .riv against contract (CI-friendly)
CLI	generate-platform — codegen for Swift, Kotlin, JSON Schema, Zod, Dart
CLI	compare — diff two .riv files, detect breaking changes
MCP	5 new tools: list-rive-assets, generate-rive-contract, validate-rive-contract, generate-platform-types, compare-rive-files
Playground	Events Log Panel — real-time Rive event stream
Playground	Preset Library — save/load/apply named configurations
Playground	URL deep-linking — ?file=<url>&artboard=Main&sm=...
Playground	Keyboard shortcuts — Space play/pause, R reset, Ctrl+S save preset
Playground	Error toasts — surface silent failures visually
Infra	Vitest test suite (16 tests)
Infra	.rive-playground/ project config directory

---

Overview

rive-analyzer CLI     Terminal-first inspection, codegen, validation
MCP Server            AI assistant integration (Claude, OpenCode)
Rive Playground       Visual editor + preset library + event log
.rive-playground/     Project config — presets, contracts (git-trackable)

---

Installation

cd /path/to/rive-mcp-analyzer
npm install
npm run build
npm link           # optional: global CLI install

---

CLI Reference

inspect

rive-analyzer inspect ./animation.riv
rive-analyzer inspect ./animation.riv --json

scan

rive-analyzer scan ./public/

validate

rive-analyzer validate ./animation.riv ./src/constants/rive.ts

generate-types

rive-analyzer generate-types ./animation.riv -o ./src/rive-generated.ts

generate-platform

rive-analyzer generate-platform ./animation.riv --target swift
rive-analyzer generate-platform ./animation.riv --target kotlin -o RiveConstants.kt
rive-analyzer generate-platform ./animation.riv --target json-schema
rive-analyzer generate-platform ./animation.riv --target zod
rive-analyzer generate-platform ./animation.riv --target dart

contract-generate

rive-analyzer contract-generate ./animation.riv -o .rive-playground/contracts/animation.yaml

Contract example:

version: 1.1.0
file: animation.riv
artboard: Main
stateMachine: Main SM
inputs:
  speed:
    type: number
    min: 0
    max: 10
    description: "Animation speed multiplier"
  isVisible:
    type: boolean
  RESET:
    type: trigger

contract-validate

rive-analyzer contract-validate ./animation.riv ./animation.rive-contract.yaml
# Exits 1 if: input removed, type changed, artboard renamed

compare

rive-analyzer compare ./animation-v1.riv ./animation-v2.riv
# Exits 1 on breaking changes — CI-safe

list-assets

rive-analyzer list-assets ./animation.riv

export-fields

rive-analyzer export-fields ./animation.riv --json

init

rive-analyzer init
# Creates: .rive-playground/{presets,contracts,schedules,config.json}

watch

rive-analyzer watch "./public/**/*.riv"

---

MCP Server (11 tools)

node dist/mcp.js

Add to Claude Desktop:

{
  "mcpServers": {
    "rive-analyzer": {
      "command": "node",
      "args": ["/absolute/path/to/rive-mcp-analyzer/dist/mcp.js"]
    }
  }
}

Tool	Description
inspect-rive	Parse .riv — artboards, SMs, animations
scan-rive-files	Scan directory recursively
validate-rive-config	Check JS/TS config against .riv
generate-rive-types	TypeScript constants
watch-rive-files	Watch for changes
export-rive-fields	Deep extract ViewModels, DataEnums
list-rive-assets	Enumerate embedded/CDN assets
generate-rive-contract	Generate .rive-contract.yaml
validate-rive-contract	Validate .riv against contract
generate-platform-types	Swift/Kotlin/JSON Schema/Zod/Dart
compare-rive-files	Diff two files, detect breaking changes

---

Playground

cd playground
npm install
npm run dev
# Open http://localhost:5173

Panels

Panel	What it does
Artboard	Select artboard and animation
State Machine	Live boolean/number/trigger controls
ViewModel	All property types with live editing
Text Runs	Edit text content, auto-discover from VMs
Events	Real-time Rive event log
Presets	Save / load / apply named configurations
Export	JSON + Markdown export

Keyboard Shortcuts

Key	Action
Space	Play / Pause
R	Reset animation
Ctrl/Cmd + S	Save current state as preset
Ctrl + Scroll	Zoom canvas
Alt + Drag	Pan canvas
Alt + Double-click	Reset view

URL Deep-linking

http://localhost:5173?file=https://cdn.example.com/animation.riv&artboard=Main&sm=Main+SM

---

Rive Contract System

The safety net between designers and developers. Define constraints on inputs — validate on every CI run.

# 1. Generate contract scaffold from .riv
rive-analyzer contract-generate hero.riv -o .rive-playground/contracts/hero.yaml

# 2. Edit: add min/max, required, descriptions
# 3. Validate in CI
rive-analyzer contract-validate hero.riv .rive-playground/contracts/hero.yaml

---

Project Structure

src/
  cli.ts                      CLI (Commander + Clack, banner + NhoNH signature)
  mcp.ts                      MCP server (11 tools)
  parser/riveParser.ts        WASM headless parser
  tools/
    contract.ts               Contract system (YAML + Zod)
    compareFiles.ts           Breaking change detection
    generateMultiplatform.ts  Swift/Kotlin/JSON Schema/Zod/Dart codegen
    listAssets.ts             Asset enumeration
    exportFields.ts           ViewModel/DataEnum extraction
    [inspect, scan, validate, generateTypes, watch].ts
  ui/theme.ts                 CLI design system
  ui/banner.ts                ASCII art + NhoNH signature

playground/src/
  hooks/useRivePlayground.ts  Core state + event capture
  hooks/usePresets.ts         localStorage preset library
  components/panels/
    EventsPanel.tsx           Real-time event log
    PresetsPanel.tsx          Save/load configurations
  components/Toast.tsx        Error notifications
  types.ts                    RiveEvent, Preset, PlaygroundState

.rive-playground/             Git-trackable project config
  presets/                    Named configuration snapshots
  contracts/                  .rive-contract.yaml files
  schedules/                  (v1.2.0)

---

Roadmap

Version	Theme	Highlights
v1.1.0	Living Canvas	Contract system, multi-platform codegen, preset library, events
v1.2.0	Living Server	LiveConfig HTTP+WS, Config Scheduler, MCP-Playground bridge
v1.3.0	Intelligence	AI Narrator, AI Config Assistant (opt-in), SM Visual Graph

---

Built by NhoNH · rive-analyzer · github.com/hoainho