@px-petals/roku.motion-web 0.0.0-stage → 1.0.0

package/pointer/pointer.js

@@ -0,0 +1,292 @@
+/**
+ * The pointer on the canvas: mouse, touch and pen events become the pointer
+ * interactions a bundle's listeners answer (down, up, enter, exit, move,
+ * click), each hit-tested against the shape or group the listener targets.
+ *
+ * - A target is hovered while the pointer is inside its geometry in the last
+ * drawn frame (`hit/`), so enter and exit follow a moving shape as well as
+ * a moving pointer.
+ * - A listener with no target watches the whole canvas: it enters when the
+ * pointer comes onto the canvas and exits when it leaves.
+ * - A click is a down and an up on the same target. Clicks on the canvas
+ * itself (the `click` event) belong to the listeners with no target, which
+ * motion.js forwards.
+ *
+ * Events: `pointer*` where the browser has them (they cover mouse, touch and
+ * pen); otherwise `mouse*` and `touch*`, ignoring the mouse events a touch
+ * makes up afterwards.
+ */
+
+/** @import { Hits } from '../hit/hit.js' */
+
+/** A mouse event this soon after a touch is the browser's own imitation of it */
+const TOUCH_MOUSE_MS = 800
+
+/**
+ * @typedef {object} PointerOptions
+ * @property {() => Hits | null}                      hits   the geometry the last frame drew; null while it is not vector
+ * @property {(type: string, target: string) => void} fire   runs a pointer interaction; target "" for the listeners without one
+ * @property {boolean}                                clicks whether a click fires Click interactions
+ */
+
+/**
+ * @param {HTMLCanvasElement} canvas
+ * @param {PointerOptions}    options
+ */
+export function createPointer(canvas, options) {
+  /** @type {Record<string, string[]>} target → interaction types, as the machine lists them */
+  let targets = {}
+  /** @type {Record<string, boolean>} */
+  let inside = {}
+  /** @type {Record<string, boolean>} */
+  let pressed = {}
+  let lastTouch = 0
+  let isBound = false
+  /** @type {{ name: string, listener: (event: any) => void }[]} */
+  const bound = []
+
+  /**
+   * @param   {string}  target
+   * @param   {string}  type
+   * @returns {boolean}
+   */
+  const listensTo = (target, type) => !!targets[target] && targets[target].indexOf(type) >= 0
+
+  /**
+   * @param   {string[]} types
+   * @returns {boolean}        whether any target listens to one of these
+   */
+  const hasAny = (types) => {
+    for (const target in targets) for (let n = 0; n < types.length; n++) if (listensTo(target, types[n])) return true
+    return false
+  }
+
+  /**
+   * @param   {string}  target
+   * @param   {number}  x
+   * @param   {number}  y
+   * @returns {boolean}        whether the pointer is on the target
+   */
+  function isOn(target, x, y) {
+    if (target === '') return true
+    const hits = options.hits()
+    return !!hits && hits.test(target, x, y)
+  }
+
+  /**
+   * Takes the interactions each target listens to and starts watching for the pointer, or stops.
+   *
+   * @param {Record<string, string[]>} next the machine's `pointerTargets`
+   */
+  function listen(next) {
+    // what is watched again keeps where the pointer is on it: rows that come and go do not end a press on the others
+    /** @type {Record<string, boolean>} */
+    const keptInside = {}
+    /** @type {Record<string, boolean>} */
+    const keptPressed = {}
+    for (const name in next) {
+      if (!targets[name]) continue
+      keptInside[name] = inside[name]
+      keptPressed[name] = pressed[name]
+    }
+    targets = next
+    inside = keptInside
+    pressed = keptPressed
+    const wanted = hasAny([ 'PointerDown', 'PointerUp', 'PointerEnter', 'PointerExit', 'PointerMove' ]) || (options.clicks && hasAnyTargeted('Click'))
+    if (wanted && !isBound) bind()
+    else if (!wanted && isBound) unbind()
+  }
+
+  /**
+   * @param   {string}  type
+   * @returns {boolean}      whether a listener on a target (not the whole artboard) has it
+   */
+  function hasAnyTargeted(type) {
+    for (const target in targets) if (target !== '' && listensTo(target, type)) return true
+    return false
+  }
+
+  /** @returns {string[]} the targets that have a pointer interaction */
+  function names() {
+    const list = []
+    for (const target in targets) list.push(target)
+    return list
+  }
+
+  /**
+   * The pointer is at a canvas pixel: targets it entered or left fire, and
+   * every one it is on fires a move.
+   *
+   * @param {number} x
+   * @param {number} y
+   */
+  function moved(x, y) {
+    const list = names()
+    for (let n = 0; n < list.length; n++) {
+      const target = list[n]
+      const isNow = isOn(target, x, y)
+      if (isNow && !inside[target]) {
+        inside[target] = true
+        if (listensTo(target, 'PointerEnter')) options.fire('PointerEnter', target)
+      } else if (!isNow && inside[target]) {
+        inside[target] = false
+        pressed[target] = false
+        if (listensTo(target, 'PointerExit')) options.fire('PointerExit', target)
+      }
+      if (isNow && listensTo(target, 'PointerMove')) options.fire('PointerMove', target)
+    }
+  }
+
+  /**
+   * @param {number} x
+   * @param {number} y
+   */
+  function pressedAt(x, y) {
+    moved(x, y)
+    const list = names()
+    for (let n = 0; n < list.length; n++) {
+      const target = list[n]
+      if (!isOn(target, x, y)) continue
+      pressed[target] = true
+      if (listensTo(target, 'PointerDown')) options.fire('PointerDown', target)
+    }
+  }
+
+  /**
+   * @param {number} x
+   * @param {number} y
+   */
+  function releasedAt(x, y) {
+    const list = names()
+    for (let n = 0; n < list.length; n++) {
+      const target = list[n]
+      const wasPressed = pressed[target]
+      pressed[target] = false
+      if (!isOn(target, x, y)) continue
+      if (listensTo(target, 'PointerUp')) options.fire('PointerUp', target)
+      // a click on the whole canvas is the canvas's own `click` event
+      if (wasPressed && target !== '' && options.clicks && listensTo(target, 'Click')) options.fire('Click', target)
+    }
+  }
+
+  /** The pointer left the canvas, or its touch ended: every target it was on is exited. */
+  function left() {
+    const list = names()
+    for (let n = 0; n < list.length; n++) {
+      const target = list[n]
+      pressed[target] = false
+      if (!inside[target]) continue
+      inside[target] = false
+      if (listensTo(target, 'PointerExit')) options.fire('PointerExit', target)
+    }
+  }
+
+  /**
+   * A client position as canvas pixels, which the hit geometry is in.
+   *
+   * @param   {{ clientX: number, clientY: number }} point
+   * @returns {{ x: number, y: number } | null}            null while the canvas has no size
+   */
+  function place(point) {
+    const box = canvas.getBoundingClientRect()
+    if (!box.width || !box.height) return null
+    return { x: ((point.clientX - box.left) * canvas.width) / box.width, y: ((point.clientY - box.top) * canvas.height) / box.height }
+  }
+
+  /**
+   * @param {(x: number, y: number) => void}                   then
+   * @param {{ clientX: number, clientY: number } | undefined} point
+   */
+  function at(then, point) {
+    const where = point ? place(point) : null
+    if (where) then(where.x, where.y)
+  }
+
+  /** @param {any} event */
+  const isMouseAfterTouch = (event) => event.type.indexOf('mouse') === 0 && Date.now() - lastTouch < TOUCH_MOUSE_MS
+
+  /** @param {any} event */
+  const firstTouch = (event) => (event.changedTouches && event.changedTouches[0]) || (event.touches && event.touches[0])
+
+  /** @type {Record<string, (event: any) => void>} */
+  const handlers = {
+    // pen, touch and mouse together
+    pointerdown: (event) => {
+      if (event.button) return
+      at(pressedAt, event)
+    },
+    pointermove: (event) => at(moved, event),
+    pointerup: (event) => {
+      if (event.button) return
+      at(releasedAt, event)
+      // a finger has no hover: lifting it leaves
+      if (event.pointerType && event.pointerType !== 'mouse') left()
+    },
+    pointercancel: () => left(),
+    pointerleave: () => left(),
+
+    // the browsers before pointer events
+    mousedown: (event) => {
+      if (isMouseAfterTouch(event) || event.button) return
+      at(pressedAt, event)
+    },
+    mousemove: (event) => {
+      if (!isMouseAfterTouch(event)) at(moved, event)
+    },
+    mouseup: (event) => {
+      if (isMouseAfterTouch(event) || event.button) return
+      at(releasedAt, event)
+    },
+    mouseleave: (event) => {
+      if (!isMouseAfterTouch(event)) left()
+    },
+    touchstart: (event) => {
+      lastTouch = Date.now()
+      at(pressedAt, firstTouch(event))
+    },
+    touchmove: (event) => {
+      lastTouch = Date.now()
+      at(moved, firstTouch(event))
+    },
+    touchend: (event) => {
+      lastTouch = Date.now()
+      at(releasedAt, firstTouch(event))
+      left()
+    },
+    touchcancel: () => {
+      lastTouch = Date.now()
+      left()
+    },
+  }
+
+  function bind() {
+    const events = window.PointerEvent
+      ? [ 'pointerdown', 'pointermove', 'pointerup', 'pointercancel', 'pointerleave' ]
+      : [ 'mousedown', 'mousemove', 'mouseup', 'mouseleave', 'touchstart', 'touchmove', 'touchend', 'touchcancel' ]
+    for (let n = 0; n < events.length; n++) {
+      bound.push({ name: events[n], listener: handlers[events[n]] })
+      canvas.addEventListener(events[n], handlers[events[n]], false)
+    }
+    isBound = true
+  }
+
+  function unbind() {
+    for (let n = 0; n < bound.length; n++) canvas.removeEventListener(bound[n].name, bound[n].listener, false)
+    bound.length = 0
+    isBound = false
+  }
+
+  return {
+    listen,
+    destroy() {
+      unbind()
+      targets = {}
+    },
+    /** The targets the pointer is on now, for tests and hosts */
+    get hovering() {
+      const list = []
+      for (const target in inside) if (inside[target] && target !== '') list.push(target)
+      return list
+    },
+  }
+}

package/readme.md

@@ -0,0 +1,270 @@
+# motion web
+
+Plays a Motion bundle on a 2D canvas, for browsers that can't run Rive's own runtimes: those need WebAssembly (Chrome 57 and Safari 11 onward, both 2017), and the WebGL2 one also needs WebGL2, which Safari only gained in iOS 15. It's the web counterpart of [runtime/roku](../roku/readme.md): the same bundles, state machine, live data, keys and text.
+
+- **No dependencies:** 50 KB minified, 18.7 KB gzipped, bundled for ES2015. The pose mixer added 8.8 KB and 3.1 KB gzipped to the 32 KB and 12.5 KB before it; fit, layout bands and nested machines 1.1 KB gzipped.
+- **Draws vector** from each animation's Lottie with its own canvas renderer, or from the bundle's raster sheets.
+- **Plays Rive's state machines whole:** layers, 1D and direct blend states, cross-fading transitions and exact exit times, by [mixing animations](#layers-blends-and-cross-fades).
+- **Older browsers:** only 2D canvas, Promise and XMLHttpRequest are needed. The source avoids built-ins older WebViews lack (`fetch`, `Map`, `Path2D`, `async`); `.tests/compat.test.js` holds it to that. A host's Babel lowers the syntax.
+
+## Usage
+
+```js
+import { createMotion } from '@px-petals/roku.motion-web'
+
+const motion = createMotion(canvas)
+motion.on('event', (name) => console.log('fired', name))
+await motion.load('https://<server>/b/<source>/<options>/bundle/motion.json', { inputs: { score: 3 } })
+
+motion.setInputs({ score: 4 })           // view-model values; an Event input set to true fires
+motion.setInputs({ 'player.score': 4 })  // a nested view model's property, by dotted path
+motion.setInputs({ player: { score: 4 } })  // the same, written as an object
+motion.setInputs({ mode: 'on', picture: 'stripes' })  // an enum by its value's name, an image by its asset's name
+motion.setProperties([ { key: 'fill', value: '4294901760' } ])  // { key, value } strings, typed by the bundle
+motion.key('enter')                      // or 'up', 'shift+tab', a Roku name ('OK', 'back'), or a KeyboardEvent; see Focus and keys
+motion.control('pause')                  // play, loop, pause, stop
+```
+
+A bundle is what [lottie-roku](../../bin/lib/lottie/readme.md) writes, and what the [server](../../server/readme.md)'s `bundle` output is. Size the canvas with CSS and call `motion.resize()` when its displayed size changes; the animation is fitted into it by its bundle's fit and alignment: `contain`, centred, unless the bundle says otherwise ([below](#fit-alignment-and-layout)).
+
+### Options
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `renderer` | `auto` | `auto` draws vector and moves an animation whose frames take over 20 ms to its raster sheets; `vector` and `raster` force one |
+| `clicks` | `true` | A tap or click on the canvas clicks the animation, as OK does on Roku: the Click listeners with no target hear a click anywhere on it, and those with a target hear a click on that target. `false` turns both off; the other pointer listeners answer either way |
+| `fit` | the bundle's, else `contain` | How the animation fits the canvas, over the bundle's: `contain`, `cover`, `fill`, `fitWidth`, `fitHeight`, `scaleDown`, `none` or `layout`; `load(url, { fit })` sets it too |
+| `alignment` | the bundle's, else centred | Where it sits in the canvas: a Rive alignment name (`topLeft`, `bottomCenter`, …) or `[x, y]` from -1 (left, top) to 1 (right, bottom) |
+| `keys` | `'auto'` | `auto`: the canvas can be given DOM focus (it gets a `tabIndex`) and, while it has it, its keys go to the bundle's [focus and keyboard listeners](#focus-and-keys). `manual`: it listens to no keys; the host routes them with `motion.key`, `focus`, `blur` and `click` |
+| `muted` | `false` | Play no sound. `motion.setMuted(flag)` changes it, `motion.muted` reads it |
+
+### Events
+
+| Event | Detail |
+| --- | --- |
+| `loaded` | The bundle is ready and its first state has started |
+| `state` | The state entered |
+| `playback` | `playing`, `paused`, `stopped`, `finished` |
+| `finished` | The state's animation played to its end |
+| `values` | Every input's value (an enum as its name), after the machine's own actions and any [write-back](#data-binding) from the animation |
+| `event` | A custom event the machine fired, or `openUrl:<url>` |
+| `focus` | Rive's focus moved: the detail is the focused target's `rid`, or null when none is |
+| `audio` | A sound started; the detail is its id in the bundle |
+| `error` | Why a load or a state failed, or why a sound did not play |
+
+`motion.state`, `motion.values`, `motion.playback` and `motion.renderer` read the same at any time, and so do `motion.placement` (`{ fit, alignment }`, as they stand) and `motion.band` (the layout band showing, by its width; 0 for none). `motion.artboard` is `{ width, height, u, v }`: the artboard's size where it is the canvas's (0 where the animation's own plays) and the weights toward the neighbouring layout bands.
+
+## Fit, alignment and layout
+
+[Rive's fits](../../bin/lib/rive/readme.md#fit-alignment-and-responsive-layouts) scale the artboard into the canvas, and the alignment puts what is left over (`player/player.fit.js`; its tests are in `player/.tests`):
+
+| Fit | Scale |
+| --- | --- |
+| `contain` | The tighter side, so it all shows |
+| `cover` | The looser side, so the canvas is full and the canvas cuts the rest |
+| `fill` | Each axis on its own, stretching it |
+| `fitWidth`, `fitHeight` | That side's ratio on both |
+| `none` | 1 artboard unit to a CSS pixel |
+| `scaleDown` | `contain`, never above 1 CSS pixel to a unit |
+| `layout` | The layout band for the canvas (blended with the next where the converter says it can be), then `contain` |
+
+- **A responsive artboard** (`fit: "layout"` in its bundle, with `bands`) plays the widest of its layout bands that the canvas's CSS width has room for, or the narrowest when none does, and scales it to the canvas; when the layout depends on the height (`grid`), the band is also the tallest row the canvas's CSS height has room for (`bands/`: the canvas falls in a **cell** of the grid, between four corners). **`motion.resize()` picks again** and swaps in the other band's variant of the animation that is playing, at the same moment, without restarting it or touching the machine. The converter writes the bands and the grid, and says [what is approximate between them](../../bin/lib/rive/readme.md#fit-alignment-and-responsive-layouts).
+- **Between two bands that blend** (`lerp: true`, which the converter sets where nothing reflows between them), the canvas draws the layout of its own width: each band's variant is mixed with the next band's by `u = (w - w0) / (w1 - w0)` (`bands/`), and the artboard is as wide as the canvas, as Rive's `layout` fit makes it, so the picture fills the canvas width the way Rive's does. It is a property by property mix of the two Lotties by their `rid` tags, with one weight shared by every band (`bands/bands.js`), so it costs one extra evaluation per laid-out property and nothing else: a plain bundle draws it as one animation, a bundle with the mixer as the poses' sources, and it is the same on the manual clock (no animation frame is asked for when `manual` is set). A reflow is never blended: the converter puts a band either side of it. Pointer hits follow the blended picture.
+- **Between four corners of a cell** (`cell: true`, on a bundle whose layout depends on the height), the canvas draws the layout of its own width **and height**: the cell's four variants are mixed bilinearly, weighted `(1-u)(1-v)`, `u(1-v)`, `(1-u)v` and `uv`, `v = (h - h0) / (h1 - h0)`, through the same hook: each corner's property gets an evaluator that mixes the neighbours' values by the two live weights (`t` is `u`, and `v`), so it is still one animation, or the mixer's poses. Along a side of a cell that only blends one way (`lerp` or `rise`) it is the two corners of that side; where the converter did not mark the cell, the corner plays, scaled. The artboard is the canvas's size in each direction that blends, and a layout that does not depend on the height (no `grid`, but `heightRange`) is the canvas's height within the range the converter solved, so its content sits at the top as Rive's does rather than centred in the letterbox. A list's container box is the same bilinear mix of its corners' boxes, so the rows follow. **Limits:** text overlays take the lower band's box; the raster renderer plays the lower band's sheets; past the last band or row the edge cell scales (and below the first, the first), as Rive's layout would not be solved there.
+- **With the mixer,** each band has a mixer of its own variants of the animations, all on the one stage, so a band swap mid-fade or mid-blend carries on with the layers' times and weights (`mixed-nested` and `layout-mixed` in the browser tests). Nested machines advance in `onTick` beside the stage, and keep going once it has run out.
+- **Another fit plays the file's own size,** the bands not used, and `layout` on a bundle without bands is `contain`.
+- **Canvas pixels:** `none` and `scaleDown` count CSS pixels, so the animation keeps its size on a dense screen; Rive's own runtimes count the drawing buffer's.
+
+## Nested artboards
+
+A bundle's `nested` lists the nested artboards that run a state machine of their own (a `NestedStateMachine`, or a playing `NestedSimpleAnimation`, which is a machine of one state). Each runs through the same flow as the bundle's machine (`motion/motion.nested.js`), on the player's clock, and moves its precomp layer's time remap: the layer's `nid` names the slot the renderer reads it from. Its clock is its own, at the instance's `speed`: what the host's animation does (it loops, finishes, mixes with others, cross-fades) does not move it. A host whose Lottie is stretched to hold the nested animation (for a player without machines) loops and ends at the length of its own keys (`own`), which `bundle/` reads as the animation's `frames`.
+
+- **Inputs:** a nested machine starts with the values its `NestedBool` and `NestedNumber` set, and takes the inputs of the bundle that share its inputs' names (`setInputs`, `setProperties`).
+- **Bound to the host's view model.** A nested artboard whose placement names a property of the host's view model (`dataBindPathIds`) is driven by that instance: the slots inside it are the host's own (`gauge.level`, filled as any slot is, converters included), one nested artboard placed twice follows two instances, and its machine's view-model conditions, blends and listener actions read and set the host's properties by the same dotted names. What such a machine sets (`shared` in `nested`) is written into the host's values (`values` changes, and the event follows), as a write-back is, and the other nested artboards that share the property take it.
+- **Pointer listeners** inside a nested artboard are hit-tested like the host's: the renderer names the groups a nested layer draws `<nid>/<rid>` while it draws it, the pointer module watches those names, and a hit goes to that machine (`nested.pointer`). They follow the group that moves the artboard, its transform and the fit. Several levels deep, each machine's listeners are its own.
+- **In a list row,** a nested artboard runs as in the host: the row's machines are the row's `nested`, run beside the row's own on the row's clock and written into the row's slots, so a row's spinner keeps turning after the row's own animation ends. Its pointer listeners work too: each row records its own shapes as it draws, a target is named by the row (`<row>|nest.1/2`), a press goes to that row's machine, and rows that come and go keep a press on the others (`pointer.listen` keeps the state of a target it watches again).
+- **They keep running when the outer animation finishes,** so a bundle whose only motion is nested artboards stays alive; pausing or stopping pauses them too.
+- **Several layers** play at once, as the host's do: each nested machine with more than one layer keeps a stage of its own (`mixer/mixer.stage.js`), the time remap follows the first layer, and the poses of all go in the slot `pz:<id>`, which the properties that carry `pz` (the ones a segment keys) mix by weight (`lottie/lottie.props.js`). Cross-fades and blends between a nested machine's states work as the host's.
+- **Text and images** inside a nested artboard: a text layer the converter kept in the asset (the live ones) is drawn at its layer's matrix with the slot's words (`drawDocument` in `player/overlay/overlay.js`), in the bundle's fonts; a bound image picks the asset its layer names, as the host's does.
+- **Layouts:** a nested artboard laid out at the size of its place changes with the canvas as the host's boxes do: its clip (`wh`) and the properties inside it are tagged for the layout bands and the height grid's cells to mix.
+- **Draw order:** a nested artboard draws between its siblings, as the converter cut the host's layers; one that does not clip (`nc`) draws past its own edge.
+- **Not run:** `NestedBool` or `NestedNumber` values the outer timeline animates; a machine's view-model conditions, listeners and nested artboards under a placement that owns its instance (`isStateful`; what it sets is baked in or follows the host property its value names); a pointer listener on the whole nested artboard (Rive offers none).
+
+## Lists
+
+A bundle's `lists` (from a Rive `ArtboardComponentList`) says how to draw a view-model list property as one instance of a row artboard per item, each bound to its own view-model instance. `list/` does it; the format is in [the bundle's `lists`](../../bin/lib/lottie/readme.md#motionjson).
+
+- **Rows:** each item gets its own compiled copy of the row's Lottie, so its slots are its own: the item's instance (or its own values over the row view model's default instance) goes through the row's binds and converters into that copy's slots. A row is cut off at its own edge, as an artboard is, and drawn over the animation, after it.
+- **Layout:** no Yoga in the browser; `list/list.flex.js` places the rows, which are boxes of the row artboard's size, in the container's box (the band's, when the artboard is responsive) by the container's direction (either one reversed), gap, padding, wrap and main and cross alignment, and a container that hugs takes its rows' size. Rows that do not fit overflow, as in Rive when they cannot shrink.
+- **Host API:** `setInputs({ rows: [ ... ] })` or `setProperties([ { key: 'rows', value: '[ ... ]' } ])` (the value is JSON) replaces the items; rows come and go live, and `values` and the `values` event report the list. An item is `{ viewModel?, instance?, values? }`:
+  - `{ instance: 'Two' }` is a named instance of the row's view model, `'Two'` the same
+  - `{ values: { tint: '#FF66BB6A', size: 200 } }` is a blank instance (the default one's values) with these set; a property's name may stand in the item itself (`{ size: 200 }`)
+  - `viewModel` picks the row artboard when a list has several; it defaults to the first
+- **Rows are kept by position:** a row whose item is unchanged stays as it is, state machine included; an item that differs from what was at its place makes a new row, which starts from its first frame.
+- **Machines:** a row with a state machine runs it for each row, with the nested-machine runner (`motion/motion.nested.js`) on the player's clock; its inputs are the item's values by name. Rows keep the clock running, as nested machines do.
+- **Not done:** text inside a row that is not in a nested artboard (text layers are overlays, which only the animation has); the list's own transform and opacity; a list beside other layout children in its container (the rows are laid out as if alone in it; the converter warns); a row that fills its slot instead of having a fixed size; drawing rows under the `raster` renderer or over the raster fallback (`auto` keeps a bundle with lists on vector); changing one row's value by path (`rows.1.size`), which a host does by setting the list.
+
+## How it matches Roku
+
+| | Roku (`runtime/roku`) | Web |
+| --- | --- | --- |
+| Vector | `AnimatedImage` | `lottie/`: this package's canvas renderer |
+| Raster | Posters stepping through sheets | `player/player.raster.js`: `drawImage` per frame |
+| Live colour on sheets | Poster `blendColor` on white masks | `source-in` fills over the same masks |
+| Live data in vector | Motion.Task patches the Lottie's slots and reloads it | The renderer reads slot values every frame; nothing reloads |
+| Text | Labels moved by Animations | `player/overlay/`: canvas text along the same tracks. Runs flow together, wrapping at the box width with `measureText` (words, then characters for a word wider than the box), aligned across the box and down its height. Wrap points follow the browser's metrics, not Rive's shaping. Letter spacing draws character by character. A live value replaces the first run |
+| State machine | `motion/state`, `motion.flow.bs` | `motion/motion.machine.js`, `motion.flow.js`, ported line for line, and extended for layers and timed transitions |
+| Layers, blends, cross-fades | The first layer, a blend's first animation, instant switches ([the limit](../roku/readme.md#what-rive-does-that-roku-does-not)) | `mixer/`: the pose mixer |
+
+## Data binding
+
+Values are the bundle's view-model properties by name, each one's [converters](../../bin/lib/lottie/readme.md#data-converters) applied on the way to its slot. `setInputs`, `setProperties`, `start.inputs` and the `values` event all use the same names.
+
+- **Nested view models** are dotted paths: `player.score`. `setInputs` also takes the nested object (`{ player: { score: 4 } }`), which it flattens; `setProperties` takes the dotted key, typed by the property it names. A nested view model's default values come from its default instance.
+- **Converters** apply when a bound value changes: the range, round, operation, formula, string, enum and list converters of the manifest's descriptors (`motion/motion.convert.js`), and a descriptor type this player does not know passes the value through with one `error` event saying so. A text overlay shows its slot's converted text (a number through a `toString` converter reads `72.6`).
+- **Enums** are held as the index of their value, which the machine's guards compare. `setInputs` takes the name (`'on'`) or the index; `motion.values` and the `values` event give the name. A text slot bound to an enum shows its name.
+- **Images:** a bound image property picks the asset an image layer draws. `setInputs({ picture: 'stripes' })` takes the asset's name (or its Lottie id, `image_1`, or its index); the layer draws that image at its own size, about the same fraction of it as the authored one. Every image of the file is in each animation that has a bound image, loaded up front. Raster sheets show the default image.
+- **Lists** are drawn: see [Lists](#lists). A list property holds its items (`[ { viewModel: 'Row', instance: 'One' }, ... ]`) in `values` and in the `values` event, and `setInputs({ rows: [ ... ] })` sets them.
+- **Write-backs:** where a bind writes a property back into the view model (the toSource direction, or two-way), the player reads that property as drawn at each frame, undoes its converter, and sets the view-model value when it has moved: `values` changes, a `values` event follows, and a guard on it can fire. Only properties on the animation's own layers are read (not those inside a nested artboard's precomp); what a nested machine sets in the host's view model goes straight to the values. A listener or state action that sets a bound property already reflects in `values`.
+
+## Audio
+
+A bundle's [`audio`](../../bin/lib/lottie/readme.md#audio) block plays on `HTMLAudioElement`, present in every browser on the floor (Web Audio is not).
+
+- **Preloaded** when the bundle loads: each sound's element starts downloading then. A sound that fails to load is an `error`, not a failed load.
+- **Played** when the machine fires an event the bundle maps to a sound (a state starting, a listener), and when an animation passes a cue's frame, each cue once per pass, again on every loop. A keyed cue's event reaches `event` too, as a fired one does. The `audio` event follows each start.
+- **`control('pause')`** pauses what is sounding and `play` continues it; **`stop`** silences and rewinds it. **`muted`** plays nothing and silences what is sounding.
+- **Overlap:** a sound can sound up to four times at once; a fifth restarts the oldest.
+- **Autoplay:** browsers refuse sound until the page has been touched. The refusal is an `error` event (`sound "x" did not play: the browser plays sound only after the page has been touched`), never an exception; sound after any tap, click or key press plays. A sound due before that is not replayed.
+- **Formats:** whatever the browser decodes; Rive audio is WAV, MP3 or FLAC, and FLAC is not played in browsers before about 2017.
+
+## The renderer
+
+`lottie/` draws the subset of Lottie that rive2lottie and lottie-roku write: shape layers (groups, paths, rectangles, ellipses, stars and polygons, fills, strokes, linear and radial gradients, dashes, trim paths, merge paths), precomps with time remapping, solids, images, masks, track mattes and blend modes. Text layers are drawn as overlays instead, as on Roku.
+
+- **Slots are live:** a property with a slot id reads the slot table first, so `setInputs` costs nothing to draw.
+- **Checked against lottie-web:** `.tests/browser` draws every motion-stress fixture animation at its first, middle and last frames with both renderers and fails above 2% differing pixels; all are under 0.5%.
+
+## Pointer events
+
+Pointer listeners answer where the pointer is. A listener that watches a shape or group (`target.rid` in the [manifest](../../bin/lib/lottie/readme.md#the-machine)) is hit-tested against that object's geometry in the last frame drawn, so it follows the animation, the mixer's poses, the fit and the canvas's size.
+
+| Interaction | Runs when |
+| --- | --- |
+| `PointerEnter`, `PointerExit` | The pointer moves onto or off the target (or onto or off the canvas, for a listener with no target); also when the target moves under a still pointer, on the next pointer event, and when the pointer leaves the canvas or a touch ends |
+| `PointerMove` | The pointer moves while on the target |
+| `PointerDown`, `PointerUp` | A press or release with the pointer on the target |
+| `Click` | A release on the target that began on it. A click anywhere on the canvas (the DOM `click`) runs the Click listeners that have no target; `motion.click()` and OK run them all |
+
+- **Events:** `pointerdown`, `pointermove`, `pointerup`, `pointercancel` and `pointerleave` where the browser has `PointerEvent` (mouse, touch and pen together); otherwise `mousedown`, `mousemove`, `mouseup`, `mouseleave` and `touchstart`, `touchmove`, `touchend`, `touchcancel`, ignoring the mouse events a touch makes up for 800 ms after it. Only the primary button counts. A touch has no hover, so lifting a finger also exits what it was on. Nothing is attached to the canvas unless a bundle has a pointer listener to answer.
+- **Hit test:** while a vector frame draws, each group tagged with a watched `rid` hands the renderer's traced paths (after their trims and merges) and the matrix to canvas pixels to `hit/`. Nothing is flattened until a point is tested, so a watched target costs a few references per frame; a test flattens curves to line segments and applies the nonzero rule in JavaScript. `isPointInPath` would need the paths traced again on the context for every test, and its answer depends on the context's transform; keeping the paths also lets a test run without a canvas.
+- **Pointer to canvas pixels:** the client position is scaled by `canvas.width / its displayed width`, so CSS size, device pixel ratio and `resize()` need no handling.
+- **Limits:** raster frames have no geometry, so an `auto` renderer stays on vector while a bundle has targeted listeners (`raster` hits nothing). A hit tests the shape's geometry, not its fill or its opacity (an invisible shape still hits, and a stroke is not widened), and a shape inside a nested artboard is a target of that artboard's own machine only (see [Nested artboards](#nested-artboards)). Rive's click needs a down and up on the same target, as here; its multi-touch is not modelled (the first pointer counts).
+
+## Focus and keys
+
+Rive's focus model, as [the manifest](../../bin/lib/lottie/readme.md#focus) carries it: focusable targets in Tab order, Tab and the arrows, focus actions, Focus and Blur listeners, and keyboard listeners that hear a key through the focused target and the targets above it. `.tests/parity` measures it against `@rive-app/canvas` (`focus-tab`, `focus-action`, `focus-keys`, `click-focus`, each on its RML and its `.riv`).
+
+**Rive's focus is not DOM focus.** Rive's focus says which target of the graphic the keys belong to, and a focus action can move it at any time. DOM focus says whether the page's keys reach the canvas at all.
+
+- **Motion never takes DOM focus.** It does not call `focus()` on load, when a Rive focus action runs, or when the host calls `motion.focus`, and it adds no element that could take it. The user or the host gives focus (Tab, a click on the canvas, `canvas.focus()`). Making the canvas focusable with a `tabIndex` is all it does to let that happen, and only when the bundle has a focus tree or keyboard listeners; a click on the canvas gives it focus by the browser's default. Once the canvas has focus, Motion is free to use it, but it has no reason to move it.
+- **Rive's focus routes keys only while the canvas has DOM focus** (`keys: 'auto'`); a `FocusTarget` that runs while it does not still moves Rive's focus (Focus listeners run, the target draws as focused) and the keys wait for DOM focus.
+- **When the canvas loses DOM focus** to another element, Rive's focus is cleared, so Blur listeners run and the target stops drawing as focused, and keys stop being routed; when the window itself loses focus (another tab, another app) Rive's focus is kept for when it returns. This is `@rive-app/canvas`'s own rule.
+
+### Automatic (`keys: 'auto'`, the default)
+
+The canvas listens to `focus`, `blur`, `keydown` and `keyup` while the bundle has something to answer. Keys are named as Rive names them, from `event.code` (the physical key: `KeyA`, `Digit1`, `Numpad1`, `F1`), then `event.key` (`Enter`, `Esc`, `Up`, the short forms of old browsers), then `event.keyCode`; modifiers are read from the event and must match a listener's exactly.
+
+| Event | Does |
+| --- | --- |
+| DOM focus arrives by the keyboard | Rive's focus enters the tree: the first stop coming from before the canvas, the last coming from after (Shift+Tab). Where `:focus-visible` is unknown, a press on the canvas within 600 ms marks it as the pointer's |
+| DOM focus arrives by a click or touch | Rive's focus stays where it was; the next Tab enters the tree. A press focuses a target only through a listener that runs `FocusTarget`, as in Rive |
+| `keydown` (`keyup`) | Offered to the focused target's keyboard listeners, then those above it; Tab and Shift+Tab move focus; an arrow no listener took moves it by position |
+| Tab off the last stop | Left to the browser, which moves DOM focus on; keys are ignored until focus is given again |
+| DOM focus leaves | Rive's focus is cleared (Blur listeners run), unless the window itself lost focus |
+
+`preventDefault` is called only for a key Rive used: one a listener took, a Tab or arrow that moved focus, or a Tab held by a `stop` edge (and an arrow while anything is focused, so the page does not scroll). A key nothing used (Tab off the end, an unbound letter) is the page's.
+
+### Manual (`motion.key` and friends, always available)
+
+For hosts that route the remote themselves, such as a TV web app, with `keys: 'manual'` so the canvas listens to nothing. These work with `auto` too.
+
+| Call | Does |
+| --- | --- |
+| `motion.key(key)` | A key press: a Rive key name (`enter`, `up`, `tab`, `a`), a Roku remote name (`OK`, `back`), either with modifiers in front (`shift+tab`, `ctrl+a`), or a `KeyboardEvent`. Returns whether the bundle used it: false for a Tab off the end of the tree or a key nothing heard, so the host can move on. Enter and OK also click: the focused target, or, with no focus tree, every Click listener |
+| `motion.keyUp(key)` | The release, for listeners with the up phase |
+| `motion.focus(target)` | Moves Rive's focus to a target by `rid` or name, or `'next'`, `'previous'`, `'up'`, `'down'`, `'left'`, `'right'`. Returns whether it moved. Does not touch DOM focus |
+| `motion.blur()` | Clears Rive's focus; Blur listeners run |
+| `motion.focused` | The focused target's `rid`, or null |
+| `motion.click(target?)` | Without a target, every Click listener (as OK); with one, a press and release on it |
+
+With no host keys at all (`auto`), nothing else is needed: a bundle with no focus tree runs its keyboard listeners for the keys the canvas hears while it has DOM focus, with no focus rules, as before.
+
+**Visible focus.** Rive draws focus itself, through the focus listeners the file has (a state, a view-model colour); Motion draws no ring.
+
+**Nested artboards and lists.** The tree is one across them, as Rive's is. A nested artboard's targets are in the host's tree named `<sid>/<rid>` (the instance's id, then the object's index in the nested artboard; a nested artboard that owns a `FocusData` is `<sid>/`), where its placement sits in the hierarchy: Tab and the arrows cross into and out of it, and `motion.focus('<sid>/<rid>')` or `motion.focus('Pad/Button')` (the placement's name, then the node's) focuses one. A key goes to the focused node's listeners, then the nested artboard's nodes above it, then the host's nodes above the placement; each listener runs in the machine that owns it, as do the Focus and Blur listeners of every node whose subtree gains or loses focus. A focus action a nested machine runs (`FocusTarget` of a node of its own artboard, `FocusMove`, `FocusClear`) moves the host's one focus, including the one a nested state runs as it starts. A list's rows are in the tree in item order where the list sits, each item's nodes named `row.<id>/<rid>` (and `row.<id>/<sid>/<rid>` for a nested artboard in the row, `<id>` the row's own number, which stays with it while it is kept); the tree is rebuilt as rows come and go, and a row that loses its place while focused leaves focus on a node nothing hears until the next Tab, as `@rive-app/canvas` does. A row's own machine can now set properties of the row's view model (a listener, a state's action), and the row's slots follow.
+
+**Limits.** A directional move measures where the vector renderer last drew each target (a group by the centre of what it drew; Rive measures a group at its origin), so the `raster` renderer has nothing to measure and `auto` stays on vector while a bundle has a focus tree. The directional weights are fitted to `@rive-app/canvas`, not documented by Rive. `TransitionFocusCondition` and `SemanticData` are not read.
+
+## Layers, Blends and Cross-fades
+
+Rive plays several animations of one artboard at once and mixes what they do. A bundle's machine carries that ([the machine](../../bin/lib/lottie/readme.md#the-machine)), and the web player does it through a **pose mixer** (`mixer/`). A bundle that has a second layer, a blend state, a transition with a duration or one with an exact exit time, a state that plays backwards or at another speed, or animations that key different properties (the machine's `holds`) plays through it; any other bundle plays one animation at a time, as before, at the same cost.
+
+| Rive | Plays as |
+| --- | --- |
+| **Layers** | Each layer is in a state of its own, and its animation plays beside the others'. Layers apply in order, so a later layer overrides the properties it keys |
+| **1D blend** | The two animations either side of the input's value, weighted `1 - t` and `t` for how far `t` along it is; outside the range, the animation at that end alone. The input is a state machine input or a view model property |
+| **Direct blend** | Each animation weighted by its own input or view model property (0-100, clamped) or its fixed mix |
+| **Cross-fade** | A transition with `durationMs` mixes the incoming state in over that time while the outgoing one plays on, along the transition's `ease` curve when it has one. One interrupted by another continues from where it was |
+| **Exact exit time** | A transition with `exitTime` waits for that fraction or ms of its state's timeline (a looping one too), counted from entering the state; its other guards still apply |
+
+- **How a pose mixes.** A pose is an animation at a time with a weight. The mixer takes the artboard's longest animation as the picture's structure and gives each property that any animation keys (`ky`) an evaluator that reads it in every pose's animation, by `rid`, at the pose's time. The poses apply in order, each lerping the value so far toward its own by its weight, as Rive applies animations; a pose whose animation does not key the property leaves it alone. A pair of axes (position, scale, size) keyed on one axis only (`kc`) is mixed on that axis only.
+- **What the value so far is.** Rive's artboard keeps what it last applied, and the mixer does the same: each frame starts from what the property held after the previous one, not from its own value. A property no active animation keys stays where it was (`blend-hold`), and weights that do not add up to one settle over a few frames. A 1D blend half way between two animations lands a third of the way from the first, not half way (`blend-1d`; Rive's own result). A stage that has finished applies the poses several times per input change to settle as Rive's loop does, since nothing steps it. Drawing the same frame again (a resize) does not move it on.
+- **What mixes.** Numbers and vectors (positions, scales, rotations, opacity, sizes, colours) component by component, and paths vertex by vertex where they have the same vertices. A value that cannot blend takes the heavier of the two.
+- **What it relies on.** rive2lottie writes every animation of an artboard with the same layers and shape items and warns where they differ (`structureWarnings`). On every fixture and file in this repository they match.
+- **Time is the stage's.** `mixer/mixer.stage.js` holds each layer's runs and clocks. `finished` and the OnComplete interactions come from the layer that ran out; the `finished` event and `motion.state` follow the first layer.
+- **Cues and speed.** A mixed bundle plays the audio cues of every animation that has weight, each once per pass and again on every loop, from the stretch of its timeline the step passed (`sweeps` in `mixer/mixer.stage.js`). A state's `speed` scales its clock, and `Reverse` and `ReverseBounce` play its timeline from the end; `Bounce` needs nothing, as a ping-pong timeline is written out there and back.
+- **Text overlays** of several animations at once mix channel by channel as shapes do (`mixOverlays`): a channel that an animation moves (more than one key) lerps toward it by its weight, and one it holds still is left alone. Overlays do not keep the last value across frames.
+- **Limits.**
+  - Mixed bundles draw vector only: raster sheets and the adaptive move to them cannot mix, and `renderer: 'raster'` plays the first layer with instant switches.
+  - A nested artboard that no machine plays (its precomp time is not tagged) follows the first pose's time, and is not mixed; one a machine plays keeps its own clock.
+  - A cross-fade follows a cubic `ease`; an elastic or `hold` transition interpolation is linear here.
+  - The back leg of a ping-pong state plays about 3% of pixels off Rive's in the `state-modes` fixture, which therefore checks only the forward leg: the timeline is written out as a time-remapped precomp and Rive's reflection at the turn differs by a couple of frames.
+  - A view model property can only drive a blend through the input the converter makes from it (`amount`, `card.mix`): the instance's other bindings and converters on a blend's property are not applied.
+
+## Layout
+
+| Path | Holds |
+| --- | --- |
+| `motion.js` | `createMotion`: wires the parts below |
+| `audio/` | Sound on `HTMLAudioElement`: preloading, voices, cue timing |
+| `bundle/` | Loading motion.json and its files over XMLHttpRequest; registering its fonts |
+| `bands/` | Layout bands that blend: the grid of bands, where the canvas falls in it (the cell, with its corner weights), and the link that mixes a corner with its neighbours |
+| `focus/` | Rive's focus: the tree and traversal, directional moves, key routing, and the canvas's focus and key events |
+| `hit/` | Pointer hit testing: the paths each targeted group drew, and point-in-shape maths |
+| `list/` | Lists: a row artboard drawn for each item of a view-model list, and the small flex that places them |
+| `lottie/` | The canvas renderer: properties, paths, shapes, paint, layers |
+| `mixer/` | The pose mixer: mixing property values, the stage of what each layer plays, the mixed picture |
+| `motion/` | The state machine, the flow, keys, live values, data converters, nested artboards' machines |
+| `player/` | The clock and canvas, fit and alignment, raster sheets, `overlay/` (text overlays: drawing and run layout) |
+| `pointer/` | Mouse, touch and pen events → pointer interactions: hover per target, press, click |
+
+## Tests
+
+```sh
+npm run motion web test       # unit tests, the motion-stress scenarios, and the browser tests
+npm run motion web typecheck
+npm run motion web build:legacy   # .artifacts/dist/motion-web.legacy(.min).js, ES5 for the browserslist
+npm run motion web legacy test    # the legacy build in real old Chrome and Firefox, in Docker
+npm run motion web parity         # the parity scorecard against Rive's canvas runtime, to .artifacts/parity/report.md
+```
+
+- **Scenarios:** `motion/.tests/motion.scenarios.test.js` replays the motion-stress scenarios Roku runs on a device, on a simulated clock, against the same expectations; the oracle ones come from the Rive CLI. The fixtures are a snapshot; [.tests/fixtures/readme.md](.tests/fixtures/readme.md) says how to refresh it.
+- **Bands:** `bands/.tests` weigh a canvas between bands and mix a band with the next, and weigh a canvas in a cell of the grid and mix its four corners; the browser tests draw a canvas between two bands, plain and through the mixer, size the artboard to the canvas in both directions, and keep the manual clock free of animation frames; `layout-responsive` (square and not), `layout-wrap` and `layout-height` in the [parity scorecard](.tests/parity/readme.md) check every size against Rive's.
+- **Focus:** `focus/.tests` walk the tree (order, scopes, `closedLoop` and `stop`, what cannot focus), the focus and blur chain, key routing (spent keys, phases, exact modifiers, `any`, Tab and arrows) and directional scoring, and drive a fake canvas through `keys: 'auto'` (keyboard and pointer focus, leaving, the window losing focus, `preventDefault`, and that nothing calls `focus()`); `focus-tab`, `focus-action`, `focus-keys` and `click-focus` in the [parity scorecard](.tests/parity/readme.md#focus-and-keys) check it against Rive's.
+- **Mixer:** `mixer/.tests` mix values, plan the stage (cross-fades, blends, layers, finishing) and draw mixed poses on a recording context; `motion/.tests/motion.layers.test.js` runs the flow over layers, durations and exit times.
+- **Browser:** `.tests/browser/browser.test.js` builds bundles from the committed fixtures with `rive2lottie` and `lottie-roku`, then runs the renderer comparison and a whole Motion in headless Chromium, once on the modules and once on the legacy build. The pose mixer's tests there step a clock by hand to read a cross-fade halfway, a 1D and a direct blend, two layers and an exit time at exact times, on the converter's [mixer fixtures](../../bin/lib/rive/.tests/files/readme.md).
+- **Lists:** `list/.tests` place rows by a column, a row, wraps, reversals, padding and hugging, and drive a list through items from instances and from values of their own, rows added and removed, a row's machine, and a draw on a recording context; the parity fixtures `list-bind`, `list-wrap` and `list-machine` compare the rows, a host replacing the list, and the rows' machines with Rive's own.
+- **Pointer:** `hit/.tests` test the point-in-shape maths and what a drawn frame records; `pointer/.tests` drive a fake canvas through enter, exit, press, click, touch and the mouse events a touch imitates, and the machine's per-target interactions; the browser tests move a real mouse and dispatch touch pointer events over the `pointer` fixture's shape and group.
+- **Parity:** [.tests/parity/readme.md](.tests/parity/readme.md) plays one fixture per Rive feature in Rive's canvas runtime and in this one, and marks each ✅, ⚠️ or ❌. It is slow, so `npm test` leaves it out.
+- **Legacy browsers:** [.tests/legacy/readme.md](.tests/legacy/readme.md) runs the legacy build, and Rive's canvas runtime for comparison, in Chrome and Firefox from our floor up, and records what Rive needs to run there.

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-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.