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

package/motion.js

@@ -0,0 +1,1155 @@
+/**
+ * Motion for the web: plays a lottie-roku bundle on a 2D canvas, for
+ * browsers that can't run Rive's own runtime (no WebGL2 or WebAssembly).
+ * Each animation draws as vector from its Lottie, or from its raster sheets
+ * where vector is too slow or asked against; a bundle's state machine,
+ * live data, keys and text work as on Roku (runtime/roku).
+ *
+ * const motion = createMotion(canvas)
+ * motion.on('event', (name) => …)
+ * await motion.load('https://…/bundle/motion.json', { inputs: { score: 3 } })
+ * motion.setInputs({ score: 4 })
+ * motion.key('enter')
+ *
+ * A bundle whose machine has layers, blend states, cross-fades or exit times
+ * plays through the pose mixer (mixer/) instead of one animation at a time.
+ */
+
+import { createAudio } from './audio/audio.js'
+import { loadBundle, loadBytes, loadJson, loadScripts, fileUrl } from './bundle/bundle.js'
+import { loadFonts } from './bundle/bundle.fonts.js'
+import { createAnimation } from './lottie/lottie.js'
+import { createLists } from './list/list.js'
+import { createMixer } from './mixer/mixer.js'
+import { createStage } from './mixer/mixer.stage.js'
+import { createFocus, PHASES } from './focus/focus.js'
+import { createDom } from './focus/focus.dom.js'
+import { createFlow } from './motion/motion.flow.js'
+import { exists, layersOf } from './motion/motion.machine.js'
+import { isClick, keyFromEvent, keyNames, modifiersFromEvent, parseKey } from './motion/motion.keys.js'
+import { createNested } from './motion/motion.nested.js'
+import { flattenInputs, fromPairs, publicValues, slotValues, sourceValue, tintColors, writtenValue } from './motion/motion.values.js'
+import { cellOf, gridOf, hasBlend, linkBands, variantIds } from './bands/bands.js'
+import { alignmentOf, fitName } from './player/player.fit.js'
+import { createPlayer } from './player/player.js'
+import { createPointer } from './pointer/pointer.js'
+import { createRaster } from './player/player.raster.js'
+
+/**
+ * What a bundle without skins holds: nothing, and no skin code loaded.
+ * @type {import('./skin/skin.js').Skins}
+ */
+const noSkins = { count: 0, update() {}, table: () => ({}), keyedBy: () => undefined, evaluate: () => ({}) }
+
+/** @import { Bundle } from './bundle/bundle.js' */
+/** @import { Media } from './player/player.js' */
+
+/**
+ * @typedef {object} MotionOptions
+ * @property {'auto' | 'vector' | 'raster'} [renderer]  `auto` (default) draws vector, moving a slow animation to its sheets
+ * @property {boolean}                      [clicks]    a tap or click on the canvas clicks the animation, and on a listener's target clicks it; default true. Other pointer listeners always answer
+ * @property {boolean}                      [muted]     play no sound; `setMuted` changes it later. Default false
+ * @property {string}                       [fit]       how the animation fits the canvas, over the bundle's: contain, cover, fill, fitWidth, fitHeight, scaleDown, none or layout
+ * @property {string | number[]}            [alignment] where it sits in the canvas, over the bundle's: a Rive alignment name such as `topLeft`, or `[x, y]` from -1 to 1
+ * @property {'auto' | 'manual'}            [keys]      `auto` (default): the canvas can be given DOM focus (Tab, a click, `canvas.focus()`) and, while it has it, its keys go to the bundle's focus and keyboard listeners. `manual`: the canvas listens to no keys and the host routes them with `key`, `keyUp`, `focus`, `blur` and `click`
+ * @property {boolean}                      [manual]    a test hook: no clock of its own, time moves only by `advance`. Default false
+ * @property {import('./bundle/bundle.js').ScriptProvider} [scripts]  `script/script.js` (the Luau VM and Rive host), or a function that returns it or a promise of it, for a bundle that has scripts to run: `() => import('.../script/script.js')`. A bundle without scripts never asks for it; without it, a bundle's script conditions do not pass and its script converters pass values through
+ */
+
+/** The values of a Motion with no bundle playing */
+const NO_VALUES = {}
+
+/**
+ * @typedef {'loaded' | 'state' | 'playback' | 'finished' | 'values' | 'event' | 'audio' | 'focus' | 'error'} MotionEvent
+ */
+
+/**
+ * @param {HTMLCanvasElement} canvas
+ * @param {MotionOptions}     [options]
+ */
+export function createMotion(canvas, options) {
+  const settings = { renderer: (options && options.renderer) || 'auto', clicks: !options || options.clicks !== false, muted: !!(options && options.muted), keys: options && options.keys === 'manual' ? 'manual' : 'auto', manual: !!(options && options.manual) }
+  /** @type {Record<string, Function[]>} */
+  const listeners = {}
+
+  /** @type {Bundle | null} */
+  let bundle = null
+  /** @type {ReturnType<typeof createFlow> | null} */
+  let flow = null
+  /** @type {Record<string, Media>} */
+  let media = {}
+  /** @type {Record<string, string>} */
+  let families = {}
+  /** @type {Record<string, string>} */
+  let inputOf = {}
+  /** Slot id → value for the current values, which the text overlays read */
+  let slotTable = {}
+  /** The bundle's bound skins, deformed into their slots with the rest; the skin code is loaded only for a bundle that has some */
+  let skins = noSkins
+  /** @type {typeof import('./skin/skin.js').createSkins | null} */
+  let makeSkins = null
+  /** Whether a write-back is in progress, whose own redraw must not write again */
+  let writing = false
+  let loadCount = 0
+  /** @type {{ fit?: string, alignment?: any }} what the caller asked for, over the bundle's */
+  let asked = { fit: options && options.fit, alignment: options && options.alignment }
+  /** @type {any} the layout band playing */
+  let band = null
+  /** The weights toward the next, wider layout band (`t`) and the next, taller one (`v`), which every band that blends into them draws in; 0 outside a blending segment */
+  const live = { t: 0, v: 0 }
+  /** The artboard width a blending segment draws at, which is the canvas's; 0 when the band plays at its own */
+  let blended = 0
+  /** The artboard height likewise: the canvas's where the layout is exact for it, else 0 */
+  let blendedHeight = 0
+  /** @type {import('./bands/bands.js').Grid | null} the layout bands as a grid, when the artboard is responsive */
+  let grid = null
+  /** @type {import('./bands/bands.js').Cell | null} where the canvas falls in the grid, while the fit is layout */
+  let cell = null
+  let nested = createNested([])
+  /** The lists of the bundle: a row drawn for each item of a view-model list */
+  let lists = createLists([], {}, { base: '', band: bandWidth, error: (message) => emit('error', message), focus: focusAction })
+  /** The `version` of the lists' rows the focus tree was built for */
+  let listVersion = 0
+  /** @type {Media | null} the mixed media of a bundle that plays through the mixer */
+  let mixedMedia = null
+  let isMixedShown = false
+  /** @type {import('./script/play/play.js').Scripts | null} the bundle's scripts, once loaded */
+  let scripts = null
+  /** @type {import('./script/play/play.objects.js').Objects | null} the bundle's scripted nodes, drawables and path effects, which run every frame */
+  let objects = null
+  /** Whether the scripted objects are running a frame, whose own writes redraw once, with the frame */
+  let isStepping = false
+  /** What the objects wrote since they last handed it over, and the triggers they fired */
+  const wrote = /** @type {Record<string, any>} */ ({})
+  const fired = /** @type {Record<string, boolean>} */ ({})
+  let hasWrites = false
+  let hasFires = false
+  /** @type {any[] | null} every vector animation drawing, once the bundle is loaded */
+  let vectorList = null
+  let isPointerWatched = false
+  let hasFocusNodes = false
+  /** @type {Record<string, Media>} a layout band's mixed media, by the band's width and height (`320x180`); they share the stage with `mixedMedia` */
+  let mixedBands = {}
+
+  const player = createPlayer(canvas, {
+    adaptive: settings.renderer === 'auto',
+    manual: settings.manual,
+    onPlayback: (playback) => emit('playback', playback),
+    onFinished: (layer) => {
+      if (layer === 0) emit('finished')
+      if (flow) flow.finished(layer)
+    },
+    onTick: () => {
+      if (flow) flow.tick()
+    },
+    isPinned: () => isPointerWatched || hasFocusNodes || lists.count > 0,
+    overlay: () => ({ values: slotTable, families, inputOf }),
+    onFrame: (item, frame) => writeBack(item, frame),
+    placement,
+    // an animation that holds its own artboard size (a state keying it) is not sized to the canvas, as in Rive
+    artboardWidth: (shown) => (holdsSize(shown) ? 0 : blended),
+    artboardHeight: (shown) => (holdsSize(shown) ? 0 : blendedHeight),
+    tick: (seconds) => {
+      if (objects) objects.step(seconds)
+      nested.tick(seconds)
+      lists.tick(seconds)
+    },
+    prepare: (shown) => {
+      if (nested.count && shown.vector) nested.apply(shown.vector.slots, shown.fps)
+    },
+    keepAlive: () => nested.count > 0 || lists.isAnimated || (!!objects && (objects.clocked || objects.live)),
+    onCue: (cue) => {
+      audio.play(cue.sound)
+      // a keyed event reaches the host as a fired one does
+      emit('event', cue.event)
+    },
+  })
+  const audio = createAudio({
+    muted: settings.muted,
+    onError: (message) => emit('error', message),
+    onPlay: (sound) => emit('audio', sound),
+  })
+
+  // Rive's focus: which target of the graphic the keys belong to. It is not DOM focus, which Motion never takes
+  // A node of a nested artboard is `<sid>/<rid>`, a list row's `row.<id>/<rid>`: the machine that owns it runs its listeners and actions
+  const focusing = createFocus({
+    fire: (type, rid) => {
+      const at = rid.lastIndexOf('/')
+      if (at < 0) {
+        if (flow) flow.focusEvent(type, rid)
+      } else if (rid.indexOf('row.') === 0) {
+        lists.focusEvent(type, rid.slice(0, at), rid.slice(at + 1))
+      } else {
+        nested.focusEvent(type, rid.slice(0, at), rid.slice(at + 1))
+      }
+    },
+    run: (actions, scope) => {
+      if (!scope) {
+        if (flow) flow.act(actions)
+      } else if (scope.indexOf('row.') === 0) {
+        lists.act(scope, actions)
+      } else {
+        nested.act(scope, actions)
+      }
+    },
+    centerOf: (rid) => {
+      if (rid.indexOf('row.') === 0) return lists.center(rid)
+      const hits = player.hits
+      return hits ? hits.center(rid) : null
+    },
+    changed: (rid) => emit('focus', rid),
+  })
+  const dom = createDom(canvas, { focus: focusing })
+
+  /**
+   * @param {MotionEvent} name
+   * @param {any}         [detail]
+   */
+  function emit(name, detail) {
+    const list = (listeners[name] || []).slice()
+    for (let n = 0; n < list.length; n++) list[n](detail)
+  }
+
+  // a click on the canvas is the listeners with no target of their own; the ones with a target hear the pointer (pointer/)
+  const onClick = () => {
+    if (flow) flow.click(true)
+  }
+  if (settings.clicks) canvas.addEventListener('click', onClick)
+  // the shapes the host's listeners and those of its list rows watch: a row's are named `<row>|<target>`
+  const hitsOf = {
+    test: (/** @type {string} */ name, /** @type {number} */ x, /** @type {number} */ y) => {
+      if (name.indexOf('|') > 0) return lists.hit(name, x, y)
+      const hits = player.hits
+      return !!hits && hits.test(name, x, y)
+    },
+  }
+  const pointer = createPointer(canvas, {
+    hits: () => /** @type {any} */ (hitsOf),
+    fire: (type, target) => {
+      if (type !== 'Click' || settings.clicks) {
+        if (!nested.pointer(type, target) && !lists.pointer(type, target) && flow) flow.pointer(type, target)
+      }
+    },
+    clicks: settings.clicks,
+  })
+
+  /**
+   * Loads a bundle and starts it.
+   *
+   * @param   {string}                 url                 motion.json
+   * @param   {object}                 [start]
+   * @param   {Record<string, any>}    [start.inputs]      values to start with, over the view model's defaults
+   * @param   {string}                 [start.state]       a state to start in instead of the machine's own
+   * @param   {Record<string, string>} [start.transitions] without a machine, the animation each one's end plays next
+   * @param   {string}                 [start.fit]         how the animation fits the canvas, over the bundle's
+   * @param   {string | number[]}      [start.alignment]   where it sits in the canvas, over the bundle's
+   * @returns {Promise<void>}
+   */
+  function load(url, start) {
+    const attempt = ++loadCount
+    if (start && (start.fit !== undefined || start.alignment !== undefined)) asked = { fit: start.fit !== undefined ? start.fit : asked.fit, alignment: start.alignment !== undefined ? start.alignment : asked.alignment }
+    return loadBundle(url)
+      .then((loaded) => Promise.all([ loaded, loadFonts(loaded), prepareAll(loaded), loadRows(loaded), loadScripts(loaded.manifest, options && options.scripts, (file) => loadBytes(fileUrl(loaded, file)), (message) => emit('error', message)), loadSkins(loaded) ]))
+      .then(([ loaded, loadedFamilies, prepared, rows, loadedScripts, skinModule ]) => {
+        // a later load won
+        if (attempt !== loadCount) return
+        bundle = loaded
+        scripts = loadedScripts
+        if (objects) objects.destroy()
+        makeSkins = skinModule ? skinModule.createSkins : null
+        skins = makeSkins && loaded.manifest.data && loaded.manifest.data.skins ? makeSkins(loaded.manifest.data.skins) : noSkins
+        families = loadedFamilies
+        media = prepared.media
+        mixedMedia = prepared.mixed
+        mixedBands = prepared.bands
+        vectorList = null
+        isMixedShown = false
+        inputOf = inputsOfSlots(loaded.manifest)
+        nested = createNested(loaded.manifest.nested, { write: nestedWrote, focus: focusAction })
+        lists = createLists(loaded.manifest.lists, rows, { skins: makeSkins, base: loaded.base, families: () => families, band: bandWidth, blended: () => blended, cell: () => cell, error: (message) => emit('error', message), focus: focusAction })
+        listVersion = lists.version
+        grid = gridOf(loaded.manifest)
+        band = chooseBand()
+        audio.load(loaded.manifest.audio, (uri) => fileUrl(loaded, uri))
+        objects = startObjects(loaded)
+        flow = createFlow(loaded.manifest, hooks())
+        const tree = focusTree()
+        focusing.setup(tree.nodes, tree.keys)
+        hasFocusNodes = focusing.hasNodes
+        dom.listen(settings.keys === 'auto' && (focusing.hasNodes || tree.keys.length > 0))
+        watchPointer(flow.pointerTargets())
+        flow.start(flattenInputs((start && start.inputs) || {}), start && start.state, start && start.transitions)
+        // what the nested machines focused as they started, now there is a tree
+        nested.flushFocus()
+        if (start && start.inputs) nested.takeInputs(start.inputs)
+        emit('loaded')
+      })
+      .catch((error) => {
+        emit('error', error.message)
+        throw error
+      })
+  }
+
+  /**
+   * Every animation, ready to draw: its Lottie for vector, its sheets for
+   * raster, as the renderer setting needs them.
+   *
+   * @param   {Bundle}                                                                                       loaded
+   * @returns {Promise<{ media: Record<string, Media>, mixed: Media | null, bands: Record<string, Media> }>}
+   */
+  function prepareAll(loaded) {
+    const manifest = loaded.manifest
+    const isMixed = settings.renderer !== 'raster' && usesMixer(manifest)
+    // bands that blend are linked before anything draws, so their Lotties are read first and compiled after
+    const isBlended = settings.renderer !== 'raster' && hasBlend(manifest)
+    /** @type {Record<string, Media>} */
+    const prepared = {}
+    /** @type {Record<string, any>} */
+    const lotties = {}
+    const pending = []
+    for (const id in manifest.animations) {
+      const entry = manifest.animations[id]
+      const wantsVector = settings.renderer !== 'raster'
+      const wantsRaster = settings.renderer !== 'vector' && !!entry.raster
+      /** @type {Media} */
+      const item = {
+        vector: null,
+        raster: wantsRaster ? createRaster(entry, loaded) : null,
+        width: entry.width,
+        height: entry.height,
+        fps: entry.fps,
+        frames: entry.frames,
+        texts: entry.texts || [],
+        cues: (manifest.audio && manifest.audio.cues && manifest.audio.cues[id]) || [],
+        tints: () => (entry.raster && flow ? tintColors(entry.raster.tints, manifest.data, flow.values) : []),
+      }
+      prepared[id] = item
+      if (item.raster) pending.push(item.raster.ready)
+      if (isMixed || isBlended) {
+        // the mixer draws every animation from one of their structures; each is read, not compiled
+        pending.push(loadJson(fileUrl(loaded, entry.lottie)).then((lottie) => {
+          lotties[id] = lottie
+        }))
+      } else if (wantsVector) {
+        pending.push(loadJson(fileUrl(loaded, entry.lottie)).then((lottie) => {
+          item.vector = drawsRows(createAnimation(lottie, { base: loaded.base, families: () => families }))
+          return item.vector.ready
+        }))
+      }
+    }
+    return Promise.all(pending).then(() => {
+      if (isBlended) linkBands(manifest, lotties, live)
+      if (!isMixed && isBlended) {
+        const ready = []
+        for (const id in lotties) {
+          prepared[id].vector = drawsRows(createAnimation(lotties[id], { base: loaded.base, families: () => families }))
+          ready.push(/** @type {Promise<any>} */ (prepared[id].vector.ready))
+        }
+        return Promise.all(ready).then(() => ({ media: prepared, mixed: null, bands: {} }))
+      }
+      if (!isMixed) return { media: prepared, mixed: null, bands: {} }
+
+      // every layout band mixes its own variants of the animations, on the one stage, so a band moves in step with the layers
+      const stage = createStage(manifest.animations)
+      /** @type {Record<string, Media>} */
+      const bands = {}
+      const listed = gridOf(manifest)
+      const rows = listed ? listed.rows : []
+      for (let j = 0; j < rows.length; j++) {
+        for (let i = 0; i < rows[j].length; i++) {
+          const corner = rows[j][i]
+          if (corner.animations) bands[bandKey(corner)] = mixedOf(manifest, prepared, lotties, loaded.base, stage, corner.animations)
+        }
+      }
+      return { media: prepared, mixed: mixedOf(manifest, prepared, lotties, loaded.base, stage, null), bands }
+    })
+  }
+
+  /**
+   * The media a mixed bundle shows: one picture of the carrier's size, drawn by the mixer from what the stage says is playing.
+   *
+   * @param   {any}                            manifest
+   * @param   {Record<string, Media>}          items
+   * @param   {Record<string, any>}            lotties
+   * @param   {string}                         base
+   * @param   {ReturnType<typeof createStage>} stage
+   * @param   {Record<string, string> | null}  variants a layout band's variant of each animation; null for the file's own size
+   * @returns {Media}
+   */
+  function mixedOf(manifest, items, lotties, base, stage, variants) {
+    /** @param {string} id the animation a layer names, or its variant in the band */
+    const picked = (id) => (variants && variants[id] ? variants[id] : id)
+    /** @type {Record<string, any>} */
+    const own = {}
+    const isVariant = variantIds(manifest)
+    for (const id in lotties) if (!isVariant[id]) own[id] = lotties[picked(id)]
+    const mixer = createMixer(own, { base, families: () => families })
+    const carrier = items[picked(mixer.carrier)]
+    return {
+      vector: drawsRows(mixer.animation),
+      raster: null,
+      width: carrier.width,
+      height: carrier.height,
+      fps: carrier.fps,
+      frames: Infinity,
+      cues: [],
+      texts: [],
+      tints: () => [],
+      mixed: {
+        mixer,
+        stage,
+        values: () => (flow ? flow.values : {}),
+        texts: (id) => (items[picked(id)] ? items[picked(id)].texts : []),
+        fps: (id) => (items[picked(id)] ? items[picked(id)].fps : 30),
+        cues: (id) => (items[picked(id)] ? items[picked(id)].cues : []),
+        item: (id) => items[picked(id)] || null,
+      },
+    }
+  }
+
+  /**
+   * The skin code, when the bundle has skins to deform, its lists' rows' too: a module of its own, fetched only then.
+   *
+   * @param   {Bundle} loaded
+   * @returns {Promise<typeof import('./skin/skin.js') | null>}
+   */
+  function loadSkins(loaded) {
+    const data = loaded.manifest.data
+    let has = !!(data && data.skins && data.skins.length)
+    const listed = loaded.manifest.lists || []
+    for (let n = 0; n < listed.length && !has; n++) {
+      for (const name in listed[n].rows) {
+        const rowData = listed[n].rows[name].data
+        if (rowData && rowData.skins && rowData.skins.length) has = true
+      }
+    }
+    return has ? import('./skin/skin.js') : Promise.resolve(null)
+  }
+
+  /**
+   * The Lottie of every row artboard the bundle's lists draw.
+   *
+   * @param   {Bundle}                       loaded
+   * @returns {Promise<Record<string, any>>}        by file name
+   */
+  function loadRows(loaded) {
+    /** @type {Record<string, any>} */
+    const found = {}
+    const pending = []
+    const listed = loaded.manifest.lists || []
+    for (let n = 0; n < listed.length; n++) {
+      for (const name in listed[n].rows) {
+        const file = listed[n].rows[name].lottie
+        pending.push(loadJson(fileUrl(loaded, file)).then((lottie) => {
+          found[file] = lottie
+        }))
+      }
+    }
+    return Promise.all(pending).then(() => found)
+  }
+
+  /**
+   * Has an animation draw the lists' rows after its own layers.
+   *
+   * @param   {import('./lottie/lottie.js').Animation} animation
+   * @returns {import('./lottie/lottie.js').Animation}
+   */
+  function drawsRows(animation) {
+    const draw = animation.draw
+    animation.draw = (ctx, frame, matrix) => {
+      draw(ctx, frame, matrix)
+      if (lists.count) lists.draw(ctx, matrix)
+    }
+    return animation
+  }
+
+  /** The width of the layout band showing, 0 for the file's own size. */
+  function bandWidth() {
+    return band ? band.width : 0
+  }
+
+  /** What the flow calls back with. */
+  function hooks() {
+    /** @type {import('./motion/motion.flow.js').Hooks} */
+    const result = {
+      play(id, loops) {
+        player.show(media[variantOf(id)], loops, settings.renderer === 'raster')
+      },
+      get scripts() {
+        return scripts
+      },
+      valuesChanged(values) {
+        if (scripts) scripts.changed(values)
+        applySlots(values)
+        lists.update(values)
+        if (lists.version !== listVersion) refocus()
+        if (lists.isPointerStale && flow) watchPointer(flow.pointerTargets())
+        if (!isStepping) {
+          player.redraw()
+          if (objects && objects.live) player.nudge()
+        }
+        emit('values', publicValues(bundle ? bundle.manifest.data : null, values))
+      },
+      stateChanged: (state) => emit('state', state),
+      event: (name) => {
+        audio.fire(name)
+        emit('event', name)
+      },
+      error: (message) => emit('error', message),
+      focus: (action) => focusAction(action, ''),
+    }
+
+    const stage = mixedMedia && mixedMedia.mixed ? mixedMedia.mixed.stage : null
+    if (!stage || !mixedMedia) return result
+
+    // a bundle that plays through the mixer: the flow tells the stage what every layer enters
+    result.layer = (layer, state, fadeMs, ease) => {
+      const missing = unknownAnimation(state, media)
+      if (missing) {
+        emit('error', "unknown animation '" + missing + "'")
+        return
+      }
+      stage.enter(layer, state, fadeMs, ease)
+      if (isMixedShown) {
+        player.wake()
+        return
+      }
+      isMixedShown = true
+      player.show(mixedFor(), false, false)
+    }
+    result.elapsed = (layer) => stage.elapsedMs(layer)
+    return result
+  }
+
+  /**
+   * Binds that write an animated property back into the view model: the
+   * property as drawn at this frame, in the view model's units, becomes its
+   * value when it has moved.
+   *
+   * @param {Media}  item
+   * @param {number} frame
+   */
+  function writeBack(item, frame) {
+    const writes = bundle && bundle.manifest.data && bundle.manifest.data.writes
+    if (!writes || !writes.length || !flow || writing || !item.vector) return
+
+    const current = flow.values
+    /** @type {Record<string, any>} */
+    const changed = {}
+    let any = false
+    for (let n = 0; n < writes.length; n++) {
+      const write = writes[n]
+      const drawn = item.vector.probe(write.sid, frame)
+      if (drawn === undefined) continue
+      const next = writtenValue(write, drawn, current[write.path], scripts)
+      if (next === undefined) continue
+      const previous = current[write.path]
+      const moved = typeof next === 'number' && typeof previous === 'number' ? Math.abs(next - previous) > 0.0001 * Math.max(1, Math.abs(previous)) : next !== previous
+      if (moved) {
+        changed[write.path] = next
+        any = true
+      }
+    }
+    if (!any) return
+
+    writing = true
+    try {
+      flow.takeInputs(changed)
+    } finally {
+      writing = false
+    }
+
+  }
+
+  /**
+   * A nested artboard's machine set properties of the host's view model: the
+   * host takes them as it takes a bind's write-back, and the other nested
+   * artboards bound to them follow.
+   *
+   * @param {Record<string, any>} changes
+   */
+  function nestedWrote(changes) {
+    if (!flow || writing) return
+    writing = true
+    try {
+      flow.takeInputs(changes)
+      nested.takeInputs(changes)
+    } finally {
+      writing = false
+    }
+  }
+
+  /**
+   * A focus action a machine ran. Its FocusTarget names a node of the
+   * machine's own artboard, which `scope` (the machine's id, "" for the
+   * bundle's own) puts in the host's tree; a move or a clear is the tree's.
+   *
+   * @param {any}    action
+   * @param {string} scope
+   */
+  function focusAction(action, scope) {
+    if (action.type === 'FocusTarget') focusing.focus(scope ? scope + '/' + action.rid : action.rid)
+    else if (action.type === 'FocusMove') focusing.move(action.direction)
+    else focusing.clear()
+  }
+
+  /**
+   * The focus tree of the bundle as it is now: the host's nodes, a nested
+   * artboard's among them, and the rows' of each list where its place is,
+   * with every key binding that names one.
+   *
+   * @returns {{ nodes: any[], keys: any[] }}
+   */
+  function focusTree() {
+    const manifest = bundle ? bundle.manifest : {}
+    const host = manifest.machine && manifest.machine.focus ? manifest.machine.focus.nodes : []
+    /** @type {any[]} */
+    const nodes = []
+    for (let n = 0; n < host.length; n++) {
+      nodes.push(host[n])
+      if (host[n].list) {
+        const rows = lists.nodes(host[n].list, host[n].rid)
+        for (let k = 0; k < rows.length; k++) nodes.push(rows[k])
+      }
+    }
+    return { nodes, keys: (manifest.remoteKeys || []).concat(nested.bindings(), lists.bindings()) }
+  }
+
+  /** Rows came or went: the tree takes their nodes, and what their machines focused as they started. */
+  function refocus() {
+    listVersion = lists.version
+    const tree = focusTree()
+    focusing.retree(tree.nodes, tree.keys)
+    hasFocusNodes = focusing.hasNodes
+    lists.flushFocus()
+  }
+
+  /**
+   * A press and release on a target, as the pointer makes them.
+   *
+   * @param {string} target a `rid`, `<sid>/<rid>` in a nested artboard, `row.<id>/<rid>` in a list's row
+   */
+  function tap(target) {
+    const types = [ 'PointerDown', 'PointerUp', 'Click' ]
+    // a row's targets are named `<row>|<rid>` by its list
+    const rowAt = target.indexOf('row.') === 0 ? target.indexOf('/') : -1
+    const row = rowAt < 0 ? target : target.slice(4, rowAt) + '|' + target.slice(rowAt + 1)
+    for (let n = 0; n < types.length; n++) {
+      if (nested.pointer(types[n], target) || lists.pointer(types[n], row)) continue
+      if (flow) flow.pointer(types[n], target)
+    }
+  }
+
+  /**
+   * @param   {string | KeyboardEvent} key
+   * @param   {boolean}                isUp
+   * @returns {boolean}                     whether the bundle used it
+   */
+  function sendKey(key, isUp) {
+    if (!flow) return false
+    const name = typeof key === 'string' ? '' : keyFromEvent(key)
+    const parsed = typeof key === 'string' ? parseKey(key) : { names: keyNames(name), mods: modifiersFromEvent(key), key: name }
+    if (!parsed.key) return false
+    const repeat = typeof key !== 'string' && key.repeat
+    const used = focusing.press({ names: parsed.names, mods: parsed.mods, phase: isUp ? PHASES.up : repeat ? PHASES.repeat : PHASES.down })
+    if (!isUp && isClick(parsed.key)) {
+      if (!focusing.hasNodes) flow.click()
+      else if (focusing.current !== null) tap(focusing.current)
+    }
+    return used
+  }
+
+  /**
+   * The shapes and groups pointer listeners target: every vector animation
+   * records their geometry as it draws, and the pointer answers on the canvas.
+   *
+   * @param {Record<string, string[]>} own the machine's `pointerTargets`
+   */
+  function watchPointer(own) {
+    // the nested machines' shapes are named `<sid>/<rid>`, beside the bundle's own
+    /** @type {Record<string, string[]>} */
+    const targets = {}
+    for (const rid in own) targets[rid] = own[rid]
+    const inside = nested.pointerTargets()
+    for (const rid in inside) targets[rid] = inside[rid]
+    const rows = lists.pointerTargets()
+    for (const name in rows) targets[name] = rows[name]
+    const rids = []
+    for (const rid in targets) if (rid !== '' && rid.indexOf('|') < 0) rids.push(rid)
+    isPointerWatched = rids.length > 0
+    // the focus tree's nodes are watched too: the arrows move focus by where they were drawn
+    const nodes = focusing.nodes
+    // (a list row's are watched as the row draws)
+    for (let n = 0; n < nodes.length; n++) if (nodes[n].rid !== '' && nodes[n].rid.indexOf('row.') !== 0 && rids.indexOf(nodes[n].rid) < 0) rids.push(nodes[n].rid)
+
+    const drawn = []
+    for (const id in media) drawn.push(media[id].vector)
+    if (mixedMedia) drawn.push(mixedMedia.vector)
+    for (const width in mixedBands) drawn.push(mixedBands[width].vector)
+    for (let n = 0; n < drawn.length; n++) {
+      const vector = drawn[n]
+      if (vector) vector.hits.watch(rids)
+    }
+    pointer.listen(targets)
+  }
+
+  /**
+   * Live values into every vector animation's slots.
+   *
+   * @param {Record<string, any>} values
+   */
+  function applySlots(values) {
+    if (!bundle) return
+    const table = slotValues(bundle.manifest.data, values, (message) => emit('error', message), scripts)
+    slotTable = table
+    const data = bundle.manifest.data
+    const warn = (/** @type {string} */ message) => emit('error', message)
+    if (skins.count) skins.update((source) => sourceValue(source, values, data, warn, scripts))
+    for (const id in media) writeSlots(media[id].vector, table, id)
+    if (mixedMedia) writeSlots(mixedMedia.vector, table, '', mixedMedia)
+    for (const width in mixedBands) writeSlots(mixedBands[width].vector, table, '', mixedBands[width])
+  }
+
+  /**
+   * One vector animation's slots: the slot table, and the skins' paths for the animation.
+   *
+   * @param {any}                 vector
+   * @param {Record<string, any>} table
+   * @param {string}              id     the animation's id, which says what it keys in a skin
+   * @param {Media}               [mixed] mixed media, whose skins take what each pose's animation keys in them
+   */
+  function writeSlots(vector, table, id, mixed) {
+    if (!vector) return
+    for (const sid in vector.slots) delete vector.slots[sid]
+    for (const sid in table) vector.slots[sid] = table[sid]
+    if (skins.count) {
+      const deformed = skins.table(id)
+      const mixer = mixed && mixed.mixed ? mixed.mixed.mixer : null
+      for (const sid in deformed) vector.slots[sid] = mixer ? mixer.mixed((animation) => skins.keyedBy(sid, animation), deformed[sid]) : deformed[sid]
+    }
+    if (objects) putOutputs(vector.slots)
+  }
+
+  /** Every vector animation the bundle draws, listed once. */
+  function vectorsOf() {
+    if (vectorList) return vectorList
+    const list = []
+    for (const id in media) if (media[id].vector) list.push(media[id].vector)
+    if (mixedMedia && mixedMedia.vector) list.push(mixedMedia.vector)
+    for (const width in mixedBands) if (mixedBands[width].vector) list.push(mixedBands[width].vector)
+    vectorList = list
+    return list
+  }
+
+  /**
+   * What the scripted objects drew, into a slot table.
+   *
+   * @param {Record<string, any>} slots
+   */
+  function putOutputs(slots) {
+    const made = /** @type {NonNullable<typeof objects>} */ (objects)
+    for (let n = 0; n < made.sids.length; n++) {
+      const value = made.outputs[made.sids[n]]
+      if (value !== undefined) slots[made.sids[n]] = value
+    }
+  }
+
+  /**
+   * Starts the bundle's scripted nodes, drawables and path effects, when the
+   * script engine came with it. What they write lands in the flow's values at
+   * once, for the script after them, and reaches the machine, the nested
+   * artboards and the slots together, once a frame.
+   *
+   * @param   {Bundle} loaded
+   * @returns {import('./script/play/play.objects.js').Objects | null}
+   */
+  function startObjects(loaded) {
+    const list = loaded.manifest.scriptObjects
+    if (!scripts || !list || !list.length) return null
+    return scripts.objects(list, {
+      data: loaded.manifest.data,
+      values: () => (flow ? flow.values : NO_VALUES),
+      write: (path, value) => {
+        if (!flow) return
+        flow.values[path] = value
+        wrote[path] = value
+        hasWrites = true
+      },
+      fire: (path) => {
+        fired[path] = true
+        hasFires = true
+      },
+      commit: () => {
+        if (!flow || (!hasWrites && !hasFires)) return false
+        const isWritten = hasWrites
+        const isFired = hasFires
+        hasWrites = false
+        hasFires = false
+        isStepping = true
+        try {
+          if (isWritten) {
+            nested.takeInputs(wrote)
+            flow.changed()
+          }
+          if (isFired) {
+            nested.takeInputs(fired)
+            flow.takeInputs(fired)
+          }
+        } finally {
+          isStepping = false
+          for (const name in wrote) delete wrote[name]
+          for (const name in fired) delete fired[name]
+        }
+        return true
+      },
+      publish: () => {
+        const drawn = vectorsOf()
+        for (let n = 0; n < drawn.length; n++) putOutputs(drawn[n].slots)
+      },
+      probe: (sid) => {
+        const item = flow ? media[variantOf(flow.animation)] : null
+        return item && item.vector ? item.vector.probe(sid, player.frame) : undefined
+      },
+      families,
+    })
+  }
+
+  /**
+   * Whether media drawn in a layout band is not the band's size: the
+   * converter laid its animation out at the artboard size the animation holds.
+   *
+   * @param {Media} shown
+   */
+  function holdsSize(shown) {
+    return !!(band && shown && shown.width && shown.width !== band.width)
+  }
+
+  /** How the animation fits the canvas: what the caller asked for, else the bundle's, else contain and centred. */
+  function placement() {
+    const manifest = bundle ? bundle.manifest : {}
+    return {
+      fit: fitName(asked.fit !== undefined ? asked.fit : manifest.fit),
+      alignment: alignmentOf(asked.alignment !== undefined ? asked.alignment : manifest.alignment),
+    }
+  }
+
+  /**
+   * The layout band for the canvas's size, when the artboard is responsive
+   * and fits as `layout`; otherwise the file's own size. Sets what a cell
+   * that blends draws: the weights toward the neighbouring bands, and the
+   * artboard size (the canvas's, as Rive's `layout` fit resizes the artboard
+   * to it).
+   */
+  function chooseBand() {
+    live.t = 0
+    live.v = 0
+    blended = 0
+    blendedHeight = 0
+    cell = null
+    if (!bundle || !grid || placement().fit !== 'layout') return null
+    const ratio = window.devicePixelRatio || 1
+    const width = canvas.clientWidth > 0 ? canvas.clientWidth : canvas.width / ratio
+    const height = canvas.clientHeight > 0 ? canvas.clientHeight : canvas.height / ratio
+    cell = cellOf(grid, width, height)
+    live.t = cell.u
+    live.v = cell.v
+    blended = cell.width
+    blendedHeight = cell.height
+    return cell.corner
+  }
+
+  /**
+   * The animation that plays an animation's part in the layout band showing.
+   *
+   * @param {string} id
+   */
+  function variantOf(id) {
+    const variant = band && band.animations ? band.animations[id] : null
+    return variant && media[variant] ? variant : id
+  }
+
+  /** The media a mixed bundle shows: the layout band's, else the file's own size. */
+  function mixedFor() {
+    const own = /** @type {Media} */ (mixedMedia)
+    return band && band.animations && mixedBands[bandKey(band)] ? mixedBands[bandKey(band)] : own
+  }
+
+  /** Moves to the layout band the canvas now calls for, keeping the animation's time. */
+  function updateBand() {
+    const before = [ live.t, live.v, blended, blendedHeight ]
+    const next = chooseBand()
+    if (next === band) {
+      // inside a blending cell the picture moves with the size, and so does an artboard sized to the canvas
+      const isMoved = live.t !== before[0] || live.v !== before[1] || blended !== before[2] || blendedHeight !== before[3]
+      if (isMoved || live.t > 0 || live.v > 0) player.render()
+      return
+    }
+    band = next
+    if (isMixedShown) {
+      // the stage is shared, so layers, fades and blends carry on in the other band
+      player.replace(mixedFor())
+      return
+    }
+    if (flow && flow.animation && media[variantOf(flow.animation)]) player.replace(media[variantOf(flow.animation)])
+  }
+
+  return {
+    load,
+
+    /** @param {Record<string, any>} inputs view-model values; an Event input set to true fires */
+    setInputs(inputs) {
+      nested.takeInputs(inputs)
+      if (flow) flow.takeInputs(flattenInputs(inputs))
+    },
+
+    /**
+     * Values as `{ key, value }` strings, typed by the bundle's view model,
+     * as maestro-web-sdk's bindable properties arrive.
+     *
+     * @param {{ key: string, value: string }[]} pairs
+     */
+    setProperties(pairs) {
+      if (!flow || !bundle) return
+      const inputs = fromPairs(bundle.manifest.data, pairs)
+      nested.takeInputs(inputs)
+      flow.takeInputs(inputs)
+    },
+
+    /** @param {string} name a machine state */
+    setState(name) {
+      if (flow) flow.jumpTo(name)
+    },
+
+    /**
+     * A key press for the bundle: a Rive key name (`enter`, `up`, `tab`), a
+     * Roku remote name (`OK`, `back`), either with modifiers in front
+     * (`shift+tab`), or a DOM keyboard event. It goes to the focused target's
+     * keyboard listeners and those above it; Tab and the arrows move focus.
+     * Enter and OK also click. This is how a host that routes the remote itself
+     * drives focus (`keys: 'manual'`); it works with `auto` too.
+     *
+     * @param   {string | KeyboardEvent} key
+     * @returns {boolean}                    whether the bundle used it: false for a Tab off the end of the focus tree, say, so the host can move on
+     */
+    key(key) {
+      return sendKey(key, false)
+    },
+
+    /**
+     * The release of a key, for keyboard listeners that answer it.
+     *
+     * @param {string | KeyboardEvent} key
+     */
+    keyUp(key) {
+      sendKey(key, true)
+    },
+
+    /**
+     * Moves Rive's focus: to a target by its `rid` or name (`motion.focused`
+     * reports them), or `'next'`, `'previous'`, `'up'`, `'down'`, `'left'` or
+     * `'right'`. It does not touch DOM focus.
+     *
+     * @param   {string}  target
+     * @returns {boolean}        whether focus moved
+     */
+    focus(target) {
+      if (target === 'next' || target === 'previous' || target === 'up' || target === 'down' || target === 'left' || target === 'right') return focusing.move(target)
+      return focusing.focus(target)
+    },
+
+    /** Takes Rive's focus off every target; the Blur listeners run. */
+    blur() {
+      focusing.clear()
+    },
+
+    /** The `rid` of the target that has Rive's focus, or null */
+    get focused() {
+      return focusing.current
+    },
+
+    /**
+     * A click from the host: without a target, every Click listener answers, as
+     * for OK; with one (its `rid` or name), a press and release on it.
+     *
+     * @param {string} [target]
+     */
+    click(target) {
+      if (!flow) return
+      if (target === undefined) {
+        flow.click()
+        return
+      }
+      const rid = focusing.resolve(target)
+      tap(rid === null ? target : rid)
+    },
+
+    /** @param {'play' | 'loop' | 'pause' | 'stop'} command */
+    control(command) {
+      player.setControl(command)
+      if (command === 'pause') audio.pause()
+      else if (command === 'stop') audio.stop()
+      else audio.resume()
+    },
+
+    /** @param {boolean} flag silences what is playing, and plays nothing until unmuted */
+    setMuted(flag) {
+      audio.setMuted(!!flag)
+    },
+
+    /** With the `manual` option, moves time on by these seconds and draws. */
+    advance(/** @type {number} */ seconds) {
+      player.advance(seconds)
+    },
+
+    /**
+     * Changes how the animation fits the canvas, over the bundle's.
+     *
+     * @param {{ fit?: string, alignment?: string | number[] }} where
+     */
+    place(where) {
+      asked = { fit: where.fit !== undefined ? where.fit : asked.fit, alignment: where.alignment !== undefined ? where.alignment : asked.alignment }
+      updateBand()
+      player.resize()
+    },
+
+    /** Call when the canvas's displayed size changes. */
+    resize() {
+      player.resize()
+      updateBand()
+    },
+
+    /**
+     * @param   {MotionEvent} name
+     * @param   {Function}    listener
+     * @returns {() => void}           removes the listener
+     */
+    on(name, listener) {
+      listeners[name] = (listeners[name] || []).concat([ listener ])
+      return () => {
+        listeners[name] = (listeners[name] || []).filter((one) => one !== listener)
+      }
+    },
+
+    destroy() {
+      player.destroy()
+      audio.destroy()
+      canvas.removeEventListener('click', onClick)
+      pointer.destroy()
+      dom.destroy()
+      focusing.setup([], [])
+      flow = null
+      bundle = null
+      skins = noSkins
+      makeSkins = null
+      if (objects) objects.destroy()
+      objects = null
+      vectorList = null
+      media = {}
+      nested = createNested([])
+      lists = createLists([], {}, { base: '', band: bandWidth, error: () => {}, focus: () => {} })
+      listVersion = 0
+      mixedMedia = null
+      mixedBands = {}
+      grid = null
+      cell = null
+    },
+
+    get state() {
+      return flow ? flow.state : ''
+    },
+    get values() {
+      return flow ? publicValues(bundle ? bundle.manifest.data : null, flow.values) : {}
+    },
+    get playback() {
+      return player.playback
+    },
+    get muted() {
+      return audio.muted
+    },
+    get renderer() {
+      return player.renderer
+    },
+    /** The width of the layout band showing, or 0 when the artboard is not responsive or does not fit as `layout` */
+    get band() {
+      return band ? band.width : 0
+    },
+    /**
+     * The artboard's size when it is the canvas's (Rive's `layout` fit sizes
+     * it to the canvas, within what the converter solved), else 0 for the
+     * picture's own, and the weights toward the neighbouring layout bands.
+     */
+    get artboard() {
+      return { width: blended, height: blendedHeight, u: live.t, v: live.v }
+    },
+    /** How the animation fits the canvas now: `{ fit, alignment }` */
+    get placement() {
+      return placement()
+    },
+  }
+}
+
+/**
+ * Whether a bundle needs the mixer: its machine has layers, a blend state, a
+ * cross-fading transition, one that waits for an exact exit time, a state that plays backwards or bounces or at another speed, or animations
+ * that key different properties (`holds`), so one leaves what another set.
+ *
+ * @param   {any}     manifest
+ * @returns {boolean}
+ */
+export function usesMixer(manifest) {
+  if (!exists(manifest.machine)) return false
+  if (manifest.machine.holds === true) return true
+  const layers = layersOf(manifest.machine)
+  if (layers.length > 1) return true
+
+  const states = layers[0].states
+  for (let n = 0; n < states.length; n++) {
+    if (states[n].blend || states[n].mode || (states[n].speed && states[n].speed !== 1)) return true
+    const list = states[n].transitions || []
+    for (let k = 0; k < list.length; k++) if (list[k].durationMs > 0 || list[k].exitTime) return true
+  }
+  return false
+}
+
+/**
+ * What a layout band's mixed media is kept under.
+ *
+ * @param   {{ width: number, height: number }} corner
+ * @returns {string}
+ */
+function bandKey(corner) {
+  return corner.width + 'x' + corner.height
+}
+
+/**
+ * The first animation a state names that the bundle lacks.
+ *
+ * @param   {any}                   state
+ * @param   {Record<string, Media>} items
+ * @returns {string}                      "" when it has them all
+ */
+function unknownAnimation(state, items) {
+  const ids = []
+  if (state.blend) for (let n = 0; n < state.blend.animations.length; n++) ids.push(state.blend.animations[n].animation)
+  else ids.push(state.animation)
+  for (let n = 0; n < ids.length; n++) if (!items[ids[n]]) return ids[n]
+  return ''
+}
+
+/**
+ * Each slot that fills a text overlay → the input it reads, as Roku's
+ * Motion.Task resolves them (bundle.bs resolveTexts).
+ *
+ * @param {any} manifest
+ */
+function inputsOfSlots(manifest) {
+  /** @type {Record<string, string>} */
+  const result = {}
+  const slots = (manifest.data && manifest.data.slots) || []
+  for (let n = 0; n < slots.length; n++) {
+    const slot = slots[n]
+    // the overlay reads the slot's converted value, so a converter shows in the text
+    if (slot.sources && slot.sources.length) result[slot.sid] = slot.sid
+  }
+  return result
+}