@px-petals/roku.motion-web 1.0.0 → 1.1.0

package/motion/motion.machine.js

@@ -11,6 +11,7 @@
  * @typedef {Record<string, boolean>} Events  pending events, name → true
  * @typedef {{ changed: boolean, events: string[], focus: any[] }} Effects  `focus`: the focus actions (FocusTarget, FocusMove, FocusClear) to run once the values are set
  * @typedef {{ elapsed: number, length: number }} Clock  how long the current state has played, and how long its timeline is, in ms
+ * @typedef {import('../script/play/play.js').Scripts} Scripts  the scripts a bundle runs; without them a Script guard fails and a RunScript action does nothing
  */
 
 /**
@@ -80,10 +81,11 @@ export function isEvent(graph, name) {
  * @param   {Values}       values
  * @param   {Events}       events
  * @param   {Clock | null} [clock] the current state's time, for exit times; without it exit times are not checked
+ * @param   {Scripts | null} [scripts]
  * @returns {string}               the next state, or ""
  */
-export function nextState(graph, current, values, events, clock) {
-  const transition = takeTransition(graph, current, values, events, clock || null)
+export function nextState(graph, current, values, events, clock, scripts) {
+  const transition = takeTransition(graph, current, values, events, clock || null, scripts || null)
   return transition ? transition.toState : ''
 }
 
@@ -96,18 +98,19 @@ export function nextState(graph, current, values, events, clock) {
  * @param   {Values}       values
  * @param   {Events}       events
  * @param   {Clock | null} clock
+ * @param   {Scripts | null} [scripts]
  * @returns {any}                  the transition, or null
  */
-export function takeTransition(graph, current, values, events, clock) {
+export function takeTransition(graph, current, values, events, clock, scripts) {
   for (let n = 0; n < graph.states.length; n++) {
     const state = graph.states[n]
     if (state.type !== 'GlobalState') continue
-    const transition = firstPassing(state.transitions, values, events, current, clock)
+    const transition = firstPassing(state.transitions, values, events, current, clock, scripts || null)
     if (transition) return transition
   }
 
   const state = find(graph, current)
-  return state ? firstPassing(state.transitions, values, events, '', clock) : null
+  return state ? firstPassing(state.transitions, values, events, '', clock, scripts || null) : null
 }
 
 /**
@@ -148,8 +151,9 @@ export function nextExit(state, length, after) {
  * @param {Events}       events
  * @param {string}       skip        a target to pass over, or ""
  * @param {Clock | null} clock
+ * @param {Scripts | null} scripts
  */
-function firstPassing(transitions, values, events, skip, clock) {
+function firstPassing(transitions, values, events, skip, clock, scripts) {
   const list = transitions || []
   for (let n = 0; n < list.length; n++) {
     const transition = list[n]
@@ -158,7 +162,7 @@ function firstPassing(transitions, values, events, skip, clock) {
     // with a clock, an exit time is checked exactly and replaces the guard that waits for the whole timeline
     const isTimed = !!clock && !!transition.exitTime
     if (isTimed && clock.elapsed < exitMs(transition, clock.length)) continue
-    if (guardsPass(transition.guards, values, events, isTimed)) return transition
+    if (guardsPass(transition.guards, values, events, isTimed, scripts)) return transition
   }
   return null
 }
@@ -168,12 +172,13 @@ function firstPassing(transitions, values, events, skip, clock) {
  * @param {Values}  values
  * @param {Events}  events
  * @param {boolean} isTimed the transition's exit time is checked apart; its `exit` guard is skipped
+ * @param {Scripts | null} scripts
  */
-function guardsPass(guards, values, events, isTimed) {
+function guardsPass(guards, values, events, isTimed, scripts) {
   const list = guards || []
   for (let n = 0; n < list.length; n++) {
     if (isTimed && list[n].exit === true) continue
-    if (!guardPasses(list[n], values, events)) return false
+    if (!guardPasses(list[n], values, events, scripts)) return false
   }
   return true
 }
@@ -184,9 +189,12 @@ function guardsPass(guards, values, events, isTimed) {
  * @param {any}    guard
  * @param {Values} values
  * @param {Events} events
+ * @param {Scripts | null} scripts
  */
-function guardPasses(guard, values, events) {
+function guardPasses(guard, values, events, scripts) {
   if (guard.type === 'Event') return events[guard.inputName] === true
+  // a scripted condition: the script says; with no way to run it, it does not pass
+  if (guard.type === 'Script') return !!scripts && scripts.evaluate(guard, values)
 
   const value = values[guard.inputName]
   const expected = resolve(guard.compareTo, values)
@@ -229,13 +237,15 @@ function compare(a, condition, b) {
  * @param   {Graph}   graph
  * @param   {Values}  values  updated in place
  * @param   {Events}  events  updated in place: Fire adds a pending event
+ * @param   {Scripts | null} [scripts]  runs a RunScript action
+ * @param   {string}  [trigger] the interaction the actions run for, which a script's pointer event is of
  * @returns {Effects}
  */
-export function perform(actions, graph, values, events) {
+export function perform(actions, graph, values, events, scripts, trigger) {
   /** @type {Effects} */
   const effects = { changed: false, events: [], focus: [] }
   const list = actions || []
-  for (let n = 0; n < list.length; n++) runOne(list[n], graph, values, events, effects)
+  for (let n = 0; n < list.length; n++) runOne(list[n], graph, values, events, effects, scripts || null, trigger || '')
   return effects
 }
 
@@ -245,8 +255,10 @@ export function perform(actions, graph, values, events) {
  * @param {Values}  values
  * @param {Events}  events
  * @param {Effects} effects
+ * @param {Scripts | null} scripts
+ * @param {string}  trigger
  */
-function runOne(action, graph, values, events, effects) {
+function runOne(action, graph, values, events, effects, scripts, trigger) {
   const name = action.inputName
   const current = values[name]
   switch (action.type) {
@@ -264,6 +276,9 @@ function runOne(action, graph, values, events, effects) {
     case 'OpenUrl':
       effects.events.push('openUrl:' + action.url)
       break
+    case 'RunScript':
+      if (scripts && scripts.perform(action, trigger, values, events)) effects.changed = true
+      break
     case 'Toggle':
       if (typeof current === 'boolean') setValue(values, name, !current, effects)
       break

package/motion/motion.values.js

@@ -88,15 +88,16 @@ function assetId(value, property) {
  * @param   {Data}                      data
  * @param   {Record<string, any>}       values
  * @param   {(message: string) => void} [warn] a converter this player does not know
+ * @param   {import('../script/play/play.js').Scripts | null} [scripts] runs the bundle's script converters
  * @returns {Record<string, any>}
  */
-export function slotValues(data, values, warn) {
+export function slotValues(data, values, warn, scripts) {
   /** @type {Record<string, any>} */
   const table = {}
   const slots = (data && data.slots) || []
   for (let n = 0; n < slots.length; n++) {
     const slot = slots[n]
-    const value = slotValue(slot, values, data, warn)
+    const value = slotValue(slot, values, data, warn, scripts)
     if (value !== undefined) table[slot.sid] = value
   }
   return table
@@ -122,12 +123,13 @@ export function propertyOf(data, path) {
  * @param {Record<string, any>}       values
  * @param {Data}                      data
  * @param {(message: string) => void} [warn]
+ * @param {import('../script/play/play.js').Scripts | null} [scripts]
  */
-function sourceValue(source, values, data, warn) {
+export function sourceValue(source, values, data, warn, scripts) {
   const raw = values[source.path]
   if (raw === undefined || !source.converter) return raw
   const property = propertyOf(data, source.path)
-  return applyConverter(source.converter, raw, { read: (path) => values[path], names: property && property.values, warn })
+  return applyConverter(source.converter, raw, { read: (path) => values[path], names: property && property.values, warn, scripts: scripts || undefined, values, type: property ? property.type : undefined })
 }
 
 /**
@@ -135,21 +137,22 @@ function sourceValue(source, values, data, warn) {
  * @param {Record<string, any>}       values
  * @param {Data}                      data
  * @param {(message: string) => void} [warn]
+ * @param {import('../script/play/play.js').Scripts | null} [scripts]
  */
-function slotValue(slot, values, data, warn) {
+function slotValue(slot, values, data, warn, scripts) {
   const sources = slot.sources || []
   if (!sources.length) return undefined
 
   const isPair = slot.type === 'Position' || slot.type === 'Vector'
   if (!isPair) {
-    const raw = sourceValue(sources[0], values, data, warn)
+    const raw = sourceValue(sources[0], values, data, warn, scripts)
     return raw === undefined ? undefined : convert(raw, slot.conversion, propertyOf(data, sources[0].path))
   }
 
   const pair = Array.isArray(slot.base) ? slot.base.slice() : [ 0, 0 ]
   let found = false
   for (let n = 0; n < sources.length; n++) {
-    const raw = sourceValue(sources[n], values, data, warn)
+    const raw = sourceValue(sources[n], values, data, warn, scripts)
     if (raw === undefined) continue
     const converted = convert(raw, slot.conversion)
     if (converted === undefined) continue
@@ -222,8 +225,9 @@ export function publicValues(data, values) {
  * @param {any} write   a `data.writes` entry
  * @param {any} drawn   the Lottie property's value
  * @param {any} current the view-model value now, whose alpha a colour keeps
+ * @param {import('../script/play/play.js').Scripts | null} [scripts] reverses a script converter
  */
-export function writtenValue(write, drawn, current) {
+export function writtenValue(write, drawn, current, scripts) {
   const isPair = write.type === 'Position' || write.type === 'Vector'
   let value = isPair && Array.isArray(drawn) ? drawn[write.axis || 0] : drawn
   switch (write.conversion) {
@@ -246,7 +250,7 @@ export function writtenValue(write, drawn, current) {
       break
   }
   if (typeof value !== 'number' || !isFinite(value)) return undefined
-  return write.converter ? reverseConverter(write.converter, value) : value
+  return write.converter ? reverseConverter(write.converter, value, scripts ? { scripts } : undefined) : value
 }
 
 /**

package/motion.js

@@ -16,7 +16,7 @@
  */
 
 import { createAudio } from './audio/audio.js'
-import { loadBundle, loadJson, fileUrl } from './bundle/bundle.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'
@@ -28,13 +28,19 @@ 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, tintColors, writtenValue } from './motion/motion.values.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' */
 
@@ -47,8 +53,12 @@ import { createRaster } from './player/player.raster.js'
  * @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
  */
@@ -74,6 +84,10 @@ export function createMotion(canvas, options) {
   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
@@ -99,6 +113,19 @@ export function createMotion(canvas, options) {
   /** @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` */
@@ -119,16 +146,18 @@ export function createMotion(canvas, options) {
     overlay: () => ({ values: slotTable, families, inputOf }),
     onFrame: (item, frame) => writeBack(item, frame),
     placement,
-    artboardWidth: () => blended,
-    artboardHeight: () => blendedHeight,
+    // 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,
+    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
@@ -220,23 +249,29 @@ export function createMotion(canvas, options) {
     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) ]))
-      .then(([ loaded, loadedFamilies, prepared, rows ]) => {
+      .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, { base: loaded.base, families: () => families, band: bandWidth, blended: () => blended, cell: () => cell, error: (message) => emit('error', message), 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)
@@ -372,6 +407,25 @@ export function createMotion(canvas, options) {
     }
   }
 
+  /**
+   * 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.
    *
@@ -421,12 +475,19 @@ export function createMotion(canvas, options) {
       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())
-        player.render()
+        if (!isStepping) {
+          player.redraw()
+          if (objects && objects.live) player.nudge()
+        }
         emit('values', publicValues(bundle ? bundle.manifest.data : null, values))
       },
       stateChanged: (state) => emit('state', state),
@@ -480,7 +541,7 @@ export function createMotion(canvas, options) {
       const write = writes[n]
       const drawn = item.vector.probe(write.sid, frame)
       if (drawn === undefined) continue
-      const next = writtenValue(write, drawn, current[write.path])
+      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
@@ -639,18 +700,128 @@ export function createMotion(canvas, options) {
    */
   function applySlots(values) {
     if (!bundle) return
-    const table = slotValues(bundle.manifest.data, values, (message) => emit('error', message))
+    const table = slotValues(bundle.manifest.data, values, (message) => emit('error', message), scripts)
     slotTable = table
-    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) continue
-      for (const sid in vector.slots) delete vector.slots[sid]
-      for (const sid in table) vector.slots[sid] = table[sid]
+    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. */
@@ -868,6 +1039,11 @@ export function createMotion(canvas, options) {
       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: () => {} })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@px-petals/roku.motion-web",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Motion for the web: plays a lottie-roku bundle on a 2D canvas, vector from its Lottie or from its raster sheets, with its state machine, live data, keys and text, for browsers that can't run Rive's own runtime.",
   "license": "Apache-2.0",
   "type": "module",
@@ -12,20 +12,12 @@
     "./*.js": "./*.js"
   },
   "files": [
-    "motion.js",
-    "audio",
-    "bands",
-    "bundle",
-    "focus",
-    "hit",
-    "list",
-    "lottie",
-    "mixer",
-    "motion",
-    "player",
-    "pointer",
+    "**/*",
     "!**/.tests",
-    "!**/*.test.js"
+    "!**/*.test.js",
+    "!jsconfig*.json",
+    "!legacy",
+    "!.artifacts"
   ],
   "sideEffects": false,
   "browserslist": [
@@ -41,8 +33,10 @@
     "build:legacy": "node legacy/legacy.js",
     "legacy": "node .tests/legacy/legacy.js",
     "parity": "node .tests/parity/parity.js",
-    "test": "node --test \".tests/*.test.js\" \"audio/.tests/*.test.js\" \"bands/.tests/*.test.js\" \"hit/.tests/*.test.js\" \"focus/.tests/*.test.js\" \"player/.tests/*.test.js\" \"pointer/.tests/*.test.js\" \"lottie/.tests/*.test.js\" \"list/.tests/*.test.js\" \"mixer/.tests/*.test.js\" \"motion/.tests/*.test.js\" \".tests/browser/*.test.js\"",
-    "typecheck": "tsc -p jsconfig.json"
+    "test": "node --test \".tests/*.test.js\" \"audio/.tests/*.test.js\" \"bands/.tests/*.test.js\" \"hit/.tests/*.test.js\" \"focus/.tests/*.test.js\" \"player/.tests/*.test.js\" \"pointer/.tests/*.test.js\" \"lottie/.tests/*.test.js\" \"list/.tests/*.test.js\" \"mixer/.tests/*.test.js\" \"skin/.tests/*.test.js\" \"motion/.tests/*.test.js\" \"script/luau/.tests/*.test.js\" \"script/luau/.tests/reference/*.test.js\" \"script/rive/.tests/*.test.js\" \"script/play/.tests/*.test.js\" \".tests/browser/*.test.js\"",
+    "typecheck": "tsc -p jsconfig.json",
+    "luau:fetch": "node script/luau/.tests/reference/reference.fetch.js",
+    "luau:fixtures": "node script/luau/.tests/reference/reference.regen.js"
   },
   "repository": {
     "type": "git",

package/player/player.js

@@ -71,8 +71,8 @@ const SETTLE_PASSES = 8
  * @param {(layer: number) => void}                            options.onFinished
  * @param {() => Overlay}                                      options.overlay
  * @param {() => { fit: string, alignment: [number, number] }} [options.placement]      how the animation fits the canvas, read on every frame
- * @param {() => number}                                       [options.artboardWidth]  the artboard's width when it is not the media's own (a layout blended between two bands), else 0; read on every frame
- * @param {() => number}                                       [options.artboardHeight] the artboard's height when it is not the media's own (a layout sized to the canvas), else 0; read on every frame
+ * @param {(media: Media) => number}                          [options.artboardWidth]  the artboard's width when it is not the media's own (a layout blended between two bands), else 0; read on every frame
+ * @param {(media: Media) => number}                          [options.artboardHeight] the artboard's height when it is not the media's own (a layout sized to the canvas), else 0; read on every frame
  * @param {() => void}                                         [options.onTick]         time has passed on a mixed media
  * @param {() => boolean}                                      [options.isPinned]       the animation must stay vector: pointer listeners hit-test its drawn shapes
  * @param {(cue: Cue) => void}                                 options.onCue            an audio cue the timeline passed
@@ -287,13 +287,16 @@ export function createPlayer(canvas, options) {
   /** The animation's space onto the canvas's, as the bundle's fit and alignment say. */
   function fitMatrix() {
     // between two layout bands that blend the artboard is as big as the canvas, which only a vector picture can be drawn at
-    const blended = !useRaster && options.artboardWidth ? options.artboardWidth() : 0
-    const blendedHeight = !useRaster && options.artboardHeight ? options.artboardHeight() : 0
+    const shown = /** @type {Media} */ (media)
+    const blended = !useRaster && options.artboardWidth ? options.artboardWidth(shown) : 0
+    const blendedHeight = !useRaster && options.artboardHeight ? options.artboardHeight(shown) : 0
     const width = blended || (/** @type {Media} */ (media)).width || canvas.width
     const height = blendedHeight || (/** @type {Media} */ (media)).height || canvas.height
     const placement = options.placement ? options.placement() : { fit: 'contain', alignment: /** @type {[number, number]} */ ([ 0, 0 ]) }
     const ratio = canvas.clientWidth > 0 ? canvas.width / canvas.clientWidth : 1
-    return fitInto(placement.fit, placement.alignment, width, height, canvas.width, canvas.height, ratio)
+    // an artboard `layout` does not size to the canvas (it holds its own size) draws at the layout's scale, as Rive's does
+    const isHeld = placement.fit === 'layout' && !blended && !blendedHeight
+    return fitInto(isHeld ? 'none' : placement.fit, placement.alignment, width, height, canvas.width, canvas.height, ratio)
   }
 
   function render() {
@@ -371,7 +374,24 @@ export function createPlayer(canvas, options) {
     wake,
     setControl,
     render,
+    /** Shows changed values: on the frame already coming while it plays, else at once, so values set many times a frame draw once */
+    redraw() {
+      // a finished animation keeps drawing while something beside it runs (scripts, nested machines)
+      const isDrawing = playback === 'playing' || (playback === 'finished' && !!options.keepAlive && options.keepAlive())
+      const isFrameComing = !!frameHandle && isDrawing
+      if (!isFrameComing) render()
+    },
     resize,
+    /** Steps once more, though the animation has finished, for something beside it that has work (a script that reads a value that changed) */
+    nudge() {
+      if (!media || frameHandle || options.manual || playback !== 'finished') return
+      last = now()
+      frameHandle = raf(tick)
+    },
+    /** The frame of the vector animation showing: where its slots' properties are read */
+    get frame() {
+      return media && media.vector ? media.vector.inPoint + elapsed * media.fps : 0
+    },
     /** With `manual`, moves time on by these seconds and draws. */
     advance(/** @type {number} */ seconds) {
       if (options.manual) step(seconds)