exodeui-svelte 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,172 @@
-# Temporary Holding Version
+# ExodeUI Svelte
 
-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.
+**Svelte 5 runtime for the [ExodeUI](https://exodeui.com/?utm_source=npm&utm_medium=readme&utm_campaign=exodeui-svelte) motion engine.** Drop interactive, physics-driven animation designed in the ExodeUI motion design environment into any Svelte app — with runes-friendly props, callbacks and a store-style helper.
+
+[![npm version](https://img.shields.io/npm/v/exodeui-svelte.svg)](https://www.npmjs.com/package/exodeui-svelte)
+[![license](https://img.shields.io/npm/l/exodeui-svelte.svg)](https://www.npmjs.com/package/exodeui-svelte)
+[![website](https://img.shields.io/badge/docs-exodeui.com-0f172a)](https://exodeui.com/docs?utm_source=npm&utm_medium=readme&utm_campaign=exodeui-svelte)
+
+ExodeUI is an AI-native **motion development environment (MDE)** for interactive vector UI: one canvas for design, a timeline for motion, Rapier physics for feel, and a state machine for logic. Artboards export as portable `.exode` data and play here through the same Canvas 2D engine used by every other ExodeUI runtime.
+
+---
+
+## Highlights
+
+- **Runes-native component.** `<ExodeUICanvas>` uses `$props`, `$state` and `$effect`, so reactive updates go straight into the engine with no extra plumbing.
+- **Interactive, not linear.** Triggers, toggles, drag, hover states, joysticks, keyboard and gamepad bindings all work out of the box.
+- **Virtual D-pads included.** Joysticks configured for keyboard input render on-canvas touch pads automatically for mobile.
+- **Consistent across frameworks.** Behaviour matches the [React](https://www.npmjs.com/package/exodeui), [Vue](https://www.npmjs.com/package/exodeui-vue), [Solid](https://www.npmjs.com/package/exodeui-solid), [Angular](https://www.npmjs.com/package/exodeui-angular) and [vanilla](https://www.npmjs.com/package/exodeui-vanilla) runtimes.
+- **Clean teardown.** Loops, observers and global listeners are removed on destroy.
+
+## Installation
+
+```bash
+npm install exodeui-svelte
+# or
+pnpm add exodeui-svelte
+# or
+yarn add exodeui-svelte
+```
+
+Requires Svelte `>= 4` (Svelte 5 recommended).
+
+## Quick start
+
+```svelte
+<script lang="ts">
+  import { ExodeUICanvas, createExodeUI } from 'exodeui-svelte';
+  import artboard from './hero.exode?raw';
+
+  const exo = createExodeUI();
+
+  function onReady(engine: any) {
+    exo.setEngine(engine);
+    exo.setInputBool('isPlaying', true);
+  }
+</script>
+
+<div style="width: 800px; height: 600px">
+  <ExodeUICanvas
+    artboard={JSON.parse(artboard)}
+    fit="Contain"
+    alignment="Center"
+    onready={onReady}
+    ontrigger={(name, anim) => console.log('trigger', name, anim)}
+    onnavigation={({ type, value }) => {
+      if (type === 'url') window.location.href = value;
+    }}
+  />
+</div>
+```
+
+### Control it from your own markup
+
+```svelte
+<script lang="ts">
+  import { ExodeUICanvas } from 'exodeui-svelte';
+
+  let canvas: any;
+  let activeTab = 0;
+
+  function selectTab(index: number) {
+    activeTab = index;
+    canvas.getEngine()?.updateInput('activeTab', index);
+    canvas.fireTrigger('TabChange');
+  }
+</script>
+
+<ExodeUICanvas bind:this={canvas} src="/animations/tabs.exode" />
+<button onclick={() => selectTab(0)}>Overview</button>
+<button onclick={() => selectTab(1)}>Motion</button>
+<button onclick={() => selectTab(2)}>Physics</button>
+```
+
+### Scrubbing a fixed frame
+
+```svelte
+<ExodeUICanvas {artboard} autoPlay={false} currentTime={1.25} />
+```
+
+## 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 | ✅ |
+| Glow, light trails, pattern grids, masks | ✅ |
+| Custom effect scripts with `update(env, dt)` hooks | ✅ |
+
+## API
+
+### `<ExodeUICanvas>` props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `artboard` | `Artboard` | — | 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'` | Fit mode |
+| `alignment` | `Alignment` | `'Center'` | Alignment |
+| `layoutScaleFactor` | `number` | — | Extra scale for `Fit: 'Layout'` |
+| `autoPlay` | `boolean` | `true` | Auto-start the loop |
+| `interactive` | `boolean` | `true` | Enable input handling |
+| `preventScroll` | `boolean` | `true` | Block page scroll on wheel/touch |
+| `highRefreshRate` | `boolean` | `true` | Sub-frame pacing on 120Hz displays |
+| `currentTime` | `number` | — | Render a fixed time when `autoPlay` is false |
+| `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 |
+
+### Callback props
+
+`onready`, `ontrigger`, `oninputupdate`, `oncomponentchange`, `ontoggle`, `oninputchange`, `oninputfocus`, `oninputblur`, `onbuttonclick`, `onnavigation`, `ongraphpointclick`, `onlog`, `onlogicupdate`, `onfpsupdate`
+
+### Exported component functions
+
+`getEngine()`, `play()`, `pause()`, `seek(time)`, `resize()`, `setOptions(options)`
+
+### `createExodeUI()`
+
+Returns a store with `engine`, `setEngine`, `updateInput`, `setInputBool`, `setInputNumber`, `setInputText`, `setInputNumberArray`, `setInputStringArray`, `fireTrigger`, `updateObjectOptions`, `updateConstraint`, `updateGraphData`, `updateBarChartData`, `updatePieChartData`, `setDropdownOptions` and `getInputValue`.
+
+## FAQ
+
+**Does it work in SvelteKit with SSR?** Yes — the canvas is created on mount, so nothing touches the DOM during server rendering.
+
+**Can I import `.exode` files directly?** Yes, with `?raw` (or the Exode Vite plugin in the React package) — or fetch the file from `src`.
+
+**Is ExodeUI a Rive or Lottie alternative?** It is built for interactive UI rather than linear playback. See the [comparison](https://exodeui.com/alternatives/rive/?utm_source=npm&utm_medium=readme&utm_campaign=exodeui-svelte).
+
+**Will it hurt my Lighthouse score?** The engine renders to a canvas and only redraws while the loop is running; use `autoPlay={false}` with `currentTime` for static hero artboards.
+
+**What is the ExodeUI MDE?** A single-surface motion development environment where design, animation and logic converge. Learn more in the [motion development environment guide](https://exodeui.com/mde?utm_source=npm&utm_medium=readme&utm_campaign=exodeui-svelte).
+
+## Related packages
+
+- [exodeui](https://www.npmjs.com/package/exodeui) — React runtime and Vite plugin
+- [exodeui-vanilla](https://www.npmjs.com/package/exodeui-vanilla) — framework-free runtime
+- [exodeui-vue](https://www.npmjs.com/package/exodeui-vue) — Vue 3 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-svelte)
+- [Examples and templates](https://exodeui.com/examples?utm_source=npm&utm_medium=readme&utm_campaign=exodeui-svelte)
+- [Component gallery](https://exodeui.com/components?utm_source=npm&utm_medium=readme&utm_campaign=exodeui-svelte)
+- [Motion UI use cases](https://exodeui.com/motion-ui?utm_source=npm&utm_medium=readme&utm_campaign=exodeui-svelte)
+- [Academy](https://exodeui.com/academy?utm_source=npm&utm_medium=readme&utm_campaign=exodeui-svelte)
+
+## License
+
+MIT © ExodeUI