exodeui-vanilla 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,199 @@
-# Temporary Holding Version
+# ExodeUI Vanilla
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Framework-free JavaScript runtime for the [ExodeUI](https://exodeui.com/?utm_source=npm&utm_medium=readme&utm_campaign=exodeui-vanilla) motion engine.** Render interactive, physics-driven UI animations exported from the ExodeUI Motion Development Environment on any web page — no React, Vue, Svelte or Angular required.
+
+[![npm version](https://img.shields.io/npm/v/exodeui-vanilla.svg)](https://www.npmjs.com/package/exodeui-vanilla)
+[![license](https://img.shields.io/npm/l/exodeui-vanilla.svg)](https://www.npmjs.com/package/exodeui-vanilla)
+[![website](https://img.shields.io/badge/docs-exodeui.com-0f172a)](https://exodeui.com/docs?utm_source=npm&utm_medium=readme&utm_campaign=exodeui-vanilla)
+
+ExodeUI is an AI-native **motion design environment (MDE)** for building animated interfaces, micro-interactions, prototypes and interactive data visualisations on a single canvas, then shipping them as data. This package is the dependency-free player for that data: a Canvas 2D renderer with a state machine, 2D physics, gesture handling and chart support built in.
+
+---
+
+## Why ExodeUI Vanilla
+
+- **Zero framework lock-in.** Drop one class into any page, CMS, Webflow/WordPress build, Electron shell, Chrome extension or game HUD.
+- **Design once, run everywhere.** The same `.exode` artboard runs here and in the [React](https://www.npmjs.com/package/exodeui), [Vue](https://www.npmjs.com/package/exodeui-vue), [Svelte](https://www.npmjs.com/package/exodeui-svelte), [Solid](https://www.npmjs.com/package/exodeui-solid) and [Angular](https://www.npmjs.com/package/exodeui-angular) runtimes, with identical behaviour.
+- **Interactive by default.** Pointer, touch, wheel, keyboard and gamepad sensors are wired in.
+- **Real state machines.** Boolean, number, text, trigger, array and random inputs drive transitions declaratively.
+- **Physics you can feel.** Rapier-backed 2D rigid bodies, joints, gravity, wind and material properties.
+- **Tiny integration surface.** `new ExodeUICanvas({ element, artboard })` and you are running.
+
+## Installation
+
+```bash
+npm install exodeui-vanilla
+# or
+pnpm add exodeui-vanilla
+# or use it straight from a CDN
+```
+
+```html
+<script type="module">
+  import { ExodeUICanvas } from 'https://esm.sh/exodeui-vanilla';
+</script>
+```
+
+## Quick start
+
+```html
+<canvas id="hero" style="width: 800px; height: 600px;"></canvas>
+
+<script type="module">
+  import { ExodeUICanvas } from 'exodeui-vanilla';
+
+  const player = new ExodeUICanvas({
+    element: '#hero',
+    fit: 'Contain',
+    alignment: 'Center',
+    onReady: (engine) => engine.setInputBool('isPlaying', true),
+    onTrigger: (name, animation) => console.log('trigger', name, animation),
+    onNavigation: ({ type, value }) => {
+      if (type === 'url') window.location.href = value;
+    },
+  });
+
+  // JSON, .exode URL, or a pre-fetched .bexode buffer
+  await player.load('/animations/hero.exode');
+  player.play();
+</script>
+```
+
+### Drive it from existing UI
+
+```js
+const player = new ExodeUICanvas({ element: '#menu' });
+
+document.querySelector('#open-menu').addEventListener('click', () => {
+  player.fireTrigger('OpenMenu');
+  player.updateInput('activeTab', 2);
+});
+```
+
+### Render into your own loop
+
+`ExodeUICanvas` owns the RAF loop, but the engine is public when you need full control:
+
+```js
+import { ExodeUIEngine } from 'exodeui-vanilla';
+
+const engine = new ExodeUIEngine();
+engine.load(artboardJSON);
+engine.setLayout('Contain', 'Center');
+
+const ctx = canvas.getContext('2d');
+let last = 0;
+requestAnimationFrame(function loop(t) {
+  const dt = Math.min((t - last) / 1000, 0.05);
+  last = t;
+  engine.advance(dt);
+  engine.render(ctx, canvas.width, canvas.height);
+  requestAnimationFrame(loop);
+});
+```
+
+## Supported features
+
+| Capability | Included |
+| --- | --- |
+| Canvas 2D renderer with DPR-aware scaling | ✅ |
+| State machine + logic nodes (AND / OR / XOR / NOT) | ✅ |
+| Boolean, number, text, trigger, array, random inputs | ✅ |
+| 2D physics (Rapier): dynamic, static, kinematic bodies | ✅ |
+| Spring, drag, joystick, pointer and keyboard sensors | ✅ |
+| Responsive layouts, breakpoints and spatial constraints | ✅ |
+| Line graphs, bar charts and pie charts with live data | ✅ |
+| Text inputs, toggles, dropdowns, sliders and list views | ✅ |
+| Scroll-linked and viewport-driven animation | ✅ |
+| `.exode` JSON and compressed `.bexode` loading | ✅ |
+| Inner/outer glow, light trails, pattern grids, masks | ✅ |
+| Custom effect scripts with `update(env, dt)` hooks | ✅ |
+
+## API
+
+### `new ExodeUICanvas(options)`
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `element` | `string \| HTMLCanvasElement` | required | Selector or canvas element |
+| `artboard` | `Artboard` | — | Already parsed artboard JSON |
+| `src` | `string` | — | `.exode` / `.bexode` URL or JSON string |
+| `buffer` | `ArrayBuffer \| Uint8Array` | — | Pre-read `.bexode` buffer |
+| `revision` | `number` | `0` | Bump to force a reload |
+| `fit` | `Fit` | `'Contain'` | Layout fit mode |
+| `alignment` | `Alignment` | `'Center'` | Layout alignment |
+| `layoutScaleFactor` | `number` | — | Extra scale for `Fit: 'Layout'` |
+| `autoPlay` | `boolean` | `true` | Auto-start the loop |
+| `interactive` | `boolean` | `true` | Enable pointer/keyboard input |
+| `preventScroll` | `boolean` | `true` | Block page scroll on wheel/touch |
+| `highRefreshRate` | `boolean` | `true` | Pump sub-frames on 120Hz displays |
+| `scrollX/Y`, `viewportScrollX/Y` | `number` | — | External scroll sensors |
+| `mouseX/Y`, `isMouseDown` | `number \| boolean` | — | External pointer sensors |
+| `inputs` | `Record<string, any>` | — | Inputs applied on load |
+| `callbacks` | `Record<string, Function>` | — | Named listeners from the editor |
+| `onReady` | `(engine) => void` | — | Artboard loaded |
+| `onTrigger` | `(name, anim) => void` | — | Trigger fired |
+| `onInputUpdate` | `(id, value) => void` | — | Input changed |
+| `onComponentChange` | `(event) => void` | — | Component event |
+| `onToggle` / `onInputChange` | `(id, value) => void` | — | Toggle / text input |
+| `onInputFocus` / `onInputBlur` | `(id) => void` | — | Field focus |
+| `onButtonClick` | `(name, objectId) => void` | — | Button pressed |
+| `onGraphPointClick` | `(graphId, point) => void` | — | Chart point clicked |
+| `onLogicUpdate` | `(state) => void` | — | Logic values changed |
+| `onFPSUpdate` | `(fps) => void` | — | ~every 400ms |
+| `onLog` | `(message) => void` | — | Engine logs and errors |
+| `onNavigation` | `({ type, value }) => void` | — | Navigation action |
+
+### Methods
+
+| Method | Description |
+| --- | --- |
+| `load(data)` | Load JSON, a URL, or a `.bexode` buffer |
+| `setOptions(options)` | Update any runtime option |
+| `play()` / `pause()` | Control the animation loop |
+| `seek(time)` | Jump to a time in seconds |
+| `resize()` | Re-measure the canvas and redraw |
+| `setLayout(fit, alignment?, scale?)` | Change layout at runtime |
+| `setInputBool / setInputNumber / setInputText` | Set scalar inputs |
+| `setInputNumberArray / setInputStringArray` | Set array inputs |
+| `updateInput(nameOrId, value)` | Set any input by name or id |
+| `fireTrigger(name)` | Fire a trigger input |
+| `updateObjectOptions(id, opts)` | Replace dropdown / list options |
+| `updateGraphData / updateBarChartData / updatePieChartData` | Live chart data |
+| `updateConstraint(id, index, props)` | Change a spatial constraint |
+| `handleScroll(x, y)` / `setViewportScroll(x, y)` | Feed scroll offset |
+| `getInputValue(nameOrId)` | Read a resolved input |
+| `getArtboard()` | The loaded artboard |
+| `destroy()` | Remove every listener |
+
+## FAQ
+
+**What is ExodeUI?** An AI-native motion development environment for designing, animating and shipping interactive vector interfaces, plus the runtimes that play the exported artboards. Start at [exodeui.com](https://exodeui.com/?utm_source=npm&utm_medium=readme&utm_campaign=exodeui-vanilla).
+
+**Is ExodeUI a Lottie or Rive alternative?** It overlaps with both but targets interactive UI: state machines, physics and real component behaviour rather than linear playback. See the [Rive comparison](https://exodeui.com/alternatives/rive/?utm_source=npm&utm_medium=readme&utm_campaign=exodeui-vanilla).
+
+**Does it need a build step?** No. Load the ESM/CJS bundle or the IIFE build (`dist/index.iife.js`) and go.
+
+**Can it run offline?** Yes. No network access is required after the artboard is loaded, and `.bexode` files can be bundled with your app.
+
+**How big is it?** The engine bundles the renderer, physics and chart code into one file; the gzipped ESM build is roughly 750 kB.
+
+## Related packages
+
+- [exodeui](https://www.npmjs.com/package/exodeui) — React runtime and Vite plugin
+- [exodeui-vue](https://www.npmjs.com/package/exodeui-vue) — Vue 3 runtime
+- [exodeui-svelte](https://www.npmjs.com/package/exodeui-svelte) — Svelte 5 runtime
+- [exodeui-solid](https://www.npmjs.com/package/exodeui-solid) — SolidJS runtime
+- [exodeui-angular](https://www.npmjs.com/package/exodeui-angular) — Angular 17+ runtime
+
+## Learn more
+
+- [Documentation](https://exodeui.com/docs?utm_source=npm&utm_medium=readme&utm_campaign=exodeui-vanilla)
+- [Examples and templates](https://exodeui.com/examples?utm_source=npm&utm_medium=readme&utm_campaign=exodeui-vanilla)
+- [Component gallery](https://exodeui.com/components?utm_source=npm&utm_medium=readme&utm_campaign=exodeui-vanilla)
+- [Motion UI use cases](https://exodeui.com/motion-ui?utm_source=npm&utm_medium=readme&utm_campaign=exodeui-vanilla)
+- [Glossary of motion terms](https://exodeui.com/glossary?utm_source=npm&utm_medium=readme&utm_campaign=exodeui-vanilla)
+
+## License
+
+MIT © ExodeUI