{"id":45543510,"url":"https://github.com/ivg-design/rive-animation-viewer","last_synced_at":"2026-04-05T12:02:25.703Z","repository":{"id":323708826,"uuid":"1094286266","full_name":"ivg-design/rive-animation-viewer","owner":"ivg-design","description":"Rive animation viewer with web frontend (if desired), and desktop (Tauri) dual platform (Mac/PC) support. Features demo bundle generation for distributing self-contained animation executables to clients.","archived":false,"fork":false,"pushed_at":"2026-04-03T12:50:54.000Z","size":14094,"stargazers_count":19,"open_issues_count":2,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-03T12:58:32.213Z","etag":null,"topics":["app","rive","standalone"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ivg-design.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-11T14:06:11.000Z","updated_at":"2026-04-03T12:51:02.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ivg-design/rive-animation-viewer","commit_stats":null,"previous_names":["ivg-design/rive-animation-viewer"],"tags_count":32,"template":false,"template_full_name":null,"purl":"pkg:github/ivg-design/rive-animation-viewer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ivg-design%2Frive-animation-viewer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ivg-design%2Frive-animation-viewer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ivg-design%2Frive-animation-viewer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ivg-design%2Frive-animation-viewer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ivg-design","download_url":"https://codeload.github.com/ivg-design/rive-animation-viewer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ivg-design%2Frive-animation-viewer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31434625,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-05T08:13:15.228Z","status":"ssl_error","status_checked_at":"2026-04-05T08:13:11.839Z","response_time":75,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["app","rive","standalone"],"created_at":"2026-02-23T04:34:21.989Z","updated_at":"2026-04-05T12:02:25.696Z","avatar_url":"https://github.com/ivg-design.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Rive Animation Viewer\n\nA local and desktop viewer for `.riv` files with runtime controls, JavaScript configuration editing, ViewModelInstance debugging tools, standalone export, a bundled native MCP sidecar, and desktop auto-update support.\n\n## Release\n\n- Current release: `2.0.1` (2026-04-02)\n- Latest patch: `2.0.1` hardens desktop updater install/check behavior, provisions signed updater release publishing, fixes sidecar packaging for release builds, and publishes a merged cross-architecture updater manifest for Apple Silicon, Intel macOS, and Windows.\n- Validated updater path: installed `/Applications/Rive Animation Viewer.app` was tested from `2.0.0` to `2.0.1` end to end, including install, relaunch, and a final `no update available` check.\n\n## 2.0.0 Highlights\n\n- **Bundled native MCP sidecar**: Packaged builds no longer require Node.js to expose MCP. RAV ships with a native `rav-mcp` binary and an always-on bridge.\n- **One-click MCP setup**: The MCP dialog detects Codex, Claude Code, and Claude Desktop, shows whether `rav-mcp` is already configured, and offers `ADD`, `REINSTALL`, and `REMOVE`.\n- **Script Access permission**: MCP scripting tools are gated behind an explicit `Script Access` toggle so you can keep MCP in read-only control mode when needed.\n- **Snippet \u0026 Export Controls**: `EXPORT` opens a dialog that previews the generated web snippet, lets you choose CDN vs local package output, and serializes only the selected or changed controls.\n- **Readable integration snippets**: Generated snippets are organized for real integration use, round numbers to 2 decimals, annotate enum choices inline, and expose a `window.ravRive` helper API.\n- **Unified consoles**: Event Console and JavaScript Console now share the same newest-first transcript model, timestamps, search/filter workflow, and `FOLLOW` behavior.\n- **Live-source-aware editor**: The editor title itself indicates whether the live runtime is being driven by internal RAV wiring or the applied editor config.\n- **Background app updates**: The desktop app checks for signed updates on launch and exposes an update chip for install/relaunch flow.\n- **Cross-architecture updater feed**: Signed release feeds now publish Apple Silicon, Intel macOS, and Windows updater entries together so one release can serve all supported desktop targets.\n\n## Quick Start\n\n```bash\nnpm install\nnpm start  # Opens browser at http://localhost:1420\n```\n\n## Features\n\n### Core Viewer\n- **File Loading**: Open button plus drag/drop file loading for `.riv` files\n- **Desktop Open With**: Double-click / open-with / single-instance handoff for `.riv` files\n- **Runtime Selection**: Toggle between Canvas and WebGL2 renderers\n- **Runtime Version Selection**: Pick runtime semver (`Latest (auto)`, the latest 4 concrete versions, or `Custom`) from Settings\n- **Layout Options**: Fit and alignment are surfaced directly in the main toolbar next to playback controls\n- **Background Color**: Color picker with `No BG` reset for transparent canvas backgrounds\n- **Transparency Mode**: Toggle transparent canvas/window mode for overlay-style playback\n- **Click-through (Desktop)**: Cursor-synced transparent-pixel click-through while keeping the viewer topmost in transparency mode\n- **Playback Controls**: Play, pause, and reset/restart (reset reloads animation with autoplay and restores control values)\n- **Autoplay on Open**: Fresh file opens, drag/drop loads, open-with events, and MCP file opens all autoplay by default\n- **Event Console**: Source toggles (`Native`, `Rive User`, `UI`, `MCP`), text search, timestamps, newest-first ordering, and `FOLLOW`\n- **Artboard Switcher**: Auto-populating dropdowns for artboards and playback targets (state machines + animations), VM instance selector, reset-to-default button\n- **State Machine Detection**: Automatically detects and initializes available state machines\n- **Auto Update Chip**: Desktop app checks for updates on launch and exposes `UPDATE \u003cversion\u003e`, `UPDATING`, `RESTARTING`, or `UPDATE RETRY`\n\n### Code Editor Panel\n- **CodeMirror 6 Editor**: JavaScript syntax highlighting with One Dark theme\n- **JavaScript Configuration**: Write JavaScript objects (NOT JSON) for Rive initialization\n- **Live Source Indicator**: The `EDITOR` title block itself indicates the current live source. Neutral gray means internal wiring is live. Green pulsing state means the applied editor config is live.\n- **Apply \u0026 Reload**: `APPLY` evaluates the current editor code, switches the live source to the editor, and refreshes the current view without throwing away the active artboard/playback state\n- **Internal Wiring Toggle**: You can switch back to internal RAV wiring without deleting editor content\n- **Tab Support**: Tab inserts 2 spaces, Shift+Tab removes indentation\n- **Error Display**: Shows errors in red banner when configuration fails\n- **Resizable Panel**: Drag to resize panel to any width for comfortable editing\n- **VM Explorer Injection**: Injects helper APIs for console-driven VM inspection and mutation\n\n### JavaScript Console\n- **Integrated JS Console**: Executable REPL panel styled to match RAV\n- **Console Capture**: Captures `console.log/info/warn/error/debug` output from the running app/runtime\n- **REPL Execution**: Execute live JavaScript against the active browser/runtime context\n- **Shared Console UX**: Same transcript layout as the Event Console, with timestamps, newest-first ordering, filters/search, and `FOLLOW`\n- **MCP Console Tools**: Open, close, read, and execute console commands remotely through MCP\n\n**Important**: The editor accepts JavaScript code, not JSON. You can use JavaScript features like comments, trailing commas, and unquoted keys:\n\n```javascript\n{\n  // This is a valid comment\n  artboard: \"MyArtboard\",\n  stateMachines: [\"StateMachine1\"],\n  autoplay: true,\n}\n```\n\n### ViewModelInstance Explorer\nDeveloper tool for debugging Rive files with ViewModelInstances.\n\n#### How to Use\n1. Load a Rive file\n2. Click \"Inject VM Explorer\" button in toolbar\n3. Open browser console (F12 or Cmd+Option+I)\n4. Use the following commands:\n\n```javascript\nvmExplore()                  // Show root properties\nvmExplore(\"path/to/prop\")    // Navigate to specific path\nvmGet(\"settings/volume\")     // Get value\nvmSet(\"settings/volume\", 0.5) // Set value\nvmTree                       // View full hierarchy\nvmPaths                      // List all property paths\n```\n\nThe explorer displays a comprehensive usage guide in the console when injected.\n\n### MCP Integration\n\nRAV includes a built-in MCP (Model Context Protocol) sidecar that lets Claude Code, Claude Desktop, Codex, or any MCP client control the viewer remotely — open files, inspect ViewModels, drive playback, manipulate inputs, run JS, generate web snippets, and export demos.\n\n#### Architecture\n\n```\nMCP Client ←(stdio)→ rav-mcp sidecar ←(WebSocket :9274)→ RAV Frontend\n```\n\nThe desktop app bundles a native `rav-mcp` sidecar binary inside the app resources. The frontend bridge (`mcp-bridge.js`) starts automatically when RAV launches, connects to the configured port, and keeps retrying until a client attaches.\n\n#### Setup (one-time)\n\nOpen the desktop app, click the cable icon, and use the **MCP Setup** dialog:\n\n- **Bundled sidecar path**: Copy the exact `rav-mcp` binary path shipped inside the app bundle\n- **Client detection**: Detect whether Codex, Claude Code, and Claude Desktop are present and whether `rav-mcp` is already configured\n- **One-click installs**: Add RAV to Codex, Claude Code, or Claude Desktop directly from the dialog when those clients are detected\n- **Reinstall / remove**: Already-configured clients show `REINSTALL` and `REMOVE`\n- **Configurable port**: Change the MCP bridge port from inside the MCP dialog and all generated snippets update to match\n- **Script Access**: Keep MCP in read-only mode, or explicitly allow JavaScript execution (`rav_eval`, `rav_console_exec`, `rav_apply_code`)\n- **Copy/paste snippets**: Ready-to-paste snippets are shown for Codex, Claude Code, Claude Desktop, and a generic MCP client\n\nRepresentative snippets:\n\n```bash\nclaude mcp add-json -s user rav-mcp '{\"type\":\"stdio\",\"command\":\"/Applications/Rive Animation Viewer.app/Contents/Resources/resources/rav-mcp\",\"args\":[\"--stdio-only\",\"--port\",\"9274\"]}'\n```\n\n```toml\n[mcp_servers.\"rav-mcp\"]\ncommand = \"/Applications/Rive Animation Viewer.app/Contents/Resources/resources/rav-mcp\"\nargs = [\"--stdio-only\", \"--port\", \"9274\"]\n```\n\nOpen the RAV desktop app and enable the MCP bridge — the **MCP** indicator in the runtime strip brightens when connected. From then on, your MCP client can control RAV whenever both are running.\n\n#### Available Tools (30)\n\n| Tool | Description |\n|------|-------------|\n| `rav_status` | App status: file, runtime, playback, ViewModel summary |\n| `rav_open_file` | Open a .riv file by absolute path |\n| `rav_play` / `rav_pause` / `rav_reset` | Playback controls |\n| `rav_get_artboards` | List artboard names |\n| `rav_get_state_machines` | List state machine names |\n| `rav_switch_artboard` / `rav_reset_artboard` | Switch artboard/animation, reset to default |\n| `rav_get_vm_tree` | Full ViewModel hierarchy |\n| `rav_vm_get` / `rav_vm_set` / `rav_vm_fire` | Read, write, and fire ViewModel properties |\n| `rav_get_event_log` | Recent event log entries (filterable by source) |\n| `rav_get_editor_code` / `rav_set_editor_code` | Read/write the script editor |\n| `rav_apply_code` | Apply editor code and reload animation (`Script Access` required) |\n| `rav_set_runtime` | Switch runtime (webgl2/canvas) |\n| `rav_set_layout` | Set layout fit mode |\n| `rav_set_canvas_color` | Set background color or transparent |\n| `rav_export_demo` | Export standalone HTML demo |\n| `generate_web_instantiation_code` | Generate the canonical live web-instantiation snippet (`local` npm package or `cdn`) with `window.ravRive` helpers and current control values |\n| `rav_toggle_instantiation_controls_dialog` | Open/close the in-app Snippet \u0026 Export Controls dialog so a human can choose which controls are serialized |\n| `rav_get_sm_inputs` / `rav_set_sm_input` | State machine input access |\n| `rav_eval` | Evaluate JS in RAV's browser context (`Script Access` required) |\n| `rav_console_open` / `rav_console_close` | Toggle the JS console remotely |\n| `rav_console_read` / `rav_console_exec` | Read captured console output or run REPL code (`rav_console_exec` requires `Script Access`) |\n\n#### Editor and Export Semantics\n\n- The live runtime can run in either internal mode or editor-driven mode.\n- `rav_apply_code` switches the live runtime to the last applied editor config.\n- Unsaved editor draft changes do not change the running animation until applied.\n- `rav_status` reports the active instantiation source and whether the editor draft is dirty.\n- `generate_web_instantiation_code` always reflects what is actually running.\n- `generate_web_instantiation_code` defaults to the CDN form unless you explicitly request `package_source: \"local\"`.\n- Generated snippets restore only the checked ViewModel/state-machine values on load, round numbers to 2 decimals, annotate enum choices inline, and expose helper methods on `window.ravRive`.\n- The **Snippet \u0026 Export Controls** dialog lets you choose exactly which controls are serialized. Branch checkboxes select nested controls; individual rows affect one value only and branch expansion stays open while you curate nested values.\n- If you never open the dialog, RAV defaults to serializing only the controls that differ from the load-time baseline.\n- Exported demos mirror the active live source, keep fit/alignment in the main toolbar, and include a **Copy Instantiation Code** button in the demo toolbar.\n\n#### Event Console\n\nAll MCP commands, responses, and connection events appear in the event console with the `MCP` source tag (indigo). Messages are formatted as human-readable summaries with elapsed time — no raw JSON. Use the `MCP` filter toggle to show/hide MCP traffic.\n\n#### Configuration\n\n| Environment Variable | Default | Description |\n|---------------------|---------|-------------|\n| `RAV_MCP_PORT` | `9274` | WebSocket bridge port |\n| `RAV_MCP_TIMEOUT` | `15000` | Command timeout in ms |\n\n### Desktop Features (Tauri)\n- **Native App**: Runs as a desktop application on macOS/Windows/Linux\n- **Demo Bundle Export**: Create self-contained HTML files with embedded animations and copyable instantiation snippets\n- **Demo Runtime Guardrails**: Exported demos intentionally disable desktop-only transparency toggle behavior\n- **Offline Support**: Caches runtime scripts for offline use\n- **Dev Tools Access**: Programmatic DevTools opening via inject button to access console\n- **Background App Updates**: Check, download, install, and relaunch signed updates from GitHub Releases\n- **Merged updater publishing**: Release automation now rebuilds a combined `latest.json` so macOS Apple Silicon, macOS Intel, and Windows updater payloads all stay present in the same feed\n\n## Project Structure\n\n```\nrive-local/\n├── app.js                    # Composition root / bootstrap\n├── mcp-bridge.js             # MCP WebSocket bridge client (frontend)\n├── index.html                # Main UI shell\n├── styles/                   # Split UI stylesheets\n├── mcp-server/\n│   ├── index.js              # Reference JS MCP server\n│   └── README.md             # MCP protocol/setup guide\n├── src/app/\n│   ├── core/                 # Constants + DOM element registry\n│   ├── platform/             # Runtime loader, export, updater, bridge helpers\n│   ├── rive/                 # Instance, playback, VM, artboard controllers\n│   └── ui/                   # Editor, consoles, dialogs, shell/status controllers\n├── vendor/\n│   └── codemirror-bundle.js  # Bundled CodeMirror\n├── scripts/\n│   ├── build-dist.mjs        # Production build\n│   ├── build-mcp-sidecar.mjs # Native rav-mcp sidecar builder\n│   └── generate-updater-manifest.mjs # Merges multi-platform updater assets into one latest.json\n└── src-tauri/                # Rust/Tauri desktop wrapper + native rav-mcp\n```\n\n## Desktop Development\n\n### Prerequisites\n- Rust toolchain (`rustup`)\n- Node.js 18+\n- Xcode Command Line Tools (macOS)\n\n### Build Commands\n```bash\nnpm run tauri dev   # Development mode\nnpm run tauri build # Production build\n```\n\n### Test Build Numbering\n\n`npm run build` now stamps builds as `bNNNN-YYYYMMDD-HHMM-\u003cgitsha\u003e`:\n- `bNNNN` auto-increments on every local build via `.cache/build-counter.txt`\n- Timestamp uses local system time\n- Tail is short git SHA\n\nOverride the test build number when needed:\n\n```bash\nnpm run build -- --build-number=172\nAPP_BUILD_NUMBER=172 npm run tauri build\n```\n\n## Technical Details\n\n### Configuration Format\nThe editor uses `eval()` to evaluate JavaScript code, allowing full JavaScript syntax:\n\n```javascript\n{\n  artboard: \"Main\",\n  stateMachines: [\"State Machine 1\"],\n  autoplay: true,\n  layout: {\n    fit: \"contain\",\n    alignment: \"center\"\n  },\n  // Custom onLoad callback\n  onLoad: () =\u003e {\n    console.log(\"Animation loaded!\");\n    riveInst.resizeDrawingSurfaceToCanvas();\n  }\n}\n```\n\n### Error Handling\n- Configuration errors display in a red error banner\n- Errors auto-dismiss after 5 seconds\n- Invalid JavaScript shows syntax errors\n- File loading errors display detailed messages\n\n### Tab Key Implementation\nThe editor intercepts Tab key events when focused:\n- Captures keydown events in capture phase\n- Prevents default browser tab behavior\n- Manually inserts/removes spaces at cursor position\n\n### VM Explorer Architecture\n- Loaded as external module from `vm-explorer-snippet.js` (contains only functional code)\n- Usage guide displayed when injecting, not in the snippet itself\n- Walks ViewModelInstance property trees recursively\n- Builds path references for direct access\n- Uses Rive runtime's path resolution for get/set operations\n\n## Known Issues\n\n### CSP Warnings (Desktop)\nThe desktop app shows harmless CSP warnings about `blob://` URLs. These are WebKit quirks and don't affect functionality.\n\n### DMG Creation\nDMG bundling may fail on some systems. The `.app` bundle in `src-tauri/target/release/bundle/macos/` works regardless.\n\n### Tab Key\nTab indentation only works when the editor has focus. Click in the editor area before using Tab.\n\n## Troubleshooting\n\n**Animation won't load**\n- Check browser console for errors\n- Verify the .riv file is valid\n- Try a different runtime (Canvas vs WebGL2)\n\n**Configuration won't apply**\n- Ensure you're writing valid JavaScript (not JSON)\n- Check for syntax errors in the code\n- Look for error messages in the red banner\n\n**VM Explorer not working**\n- Verify your Rive file has ViewModelInstances\n- Check console for injection confirmation\n- Try reloading after injection\n\n**Desktop build fails**\n- Run `rustup update` to ensure latest Rust\n- Check `npm run tauri info` for missing dependencies\n- Verify Xcode Command Line Tools installed (macOS)\n\n## License\n\nMIT License - Copyright © 2025 IVG Design\n\nRive runtimes are provided by [Rive](https://rive.app/) under their own licensing terms.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fivg-design%2Frive-animation-viewer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fivg-design%2Frive-animation-viewer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fivg-design%2Frive-animation-viewer/lists"}