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

package/bands/bands.js

@@ -329,8 +329,10 @@ function visit(node, found) {
     return
   }
   if (typeof node.rid === 'string' && 'k' in node) found(node)
+  // a property's `k` holds its values; a gradient's `g.k` is a property itself
+  const isProperty = 'a' in node || typeof node.rid === 'string'
   for (const key in node) {
-    if (key === 'k' || key === 'rid') continue
+    if ((key === 'k' && isProperty) || key === 'rid') continue
     visit(node[key], found)
   }
 }

package/bundle/bundle.js

@@ -61,6 +61,25 @@ export function loadJson(url) {
   })
 }
 
+/**
+ * @param   {string}                  url
+ * @returns {Promise<Uint8Array>}
+ */
+export function loadBytes(url) {
+  return new Promise((resolve, reject) => {
+    const request = new XMLHttpRequest()
+    request.open('GET', url, true)
+    request.responseType = 'arraybuffer'
+    request.onload = () => {
+      const isOk = request.status >= 200 && request.status < 300
+      if (isOk) resolve(new Uint8Array(request.response))
+      else reject(new Error('cannot load ' + url + ' (HTTP ' + request.status + ')'))
+    }
+    request.onerror = () => reject(new Error('cannot load ' + url))
+    request.send()
+  })
+}
+
 /**
  * @param   {string}                    url
  * @returns {Promise<HTMLImageElement>}
@@ -73,3 +92,40 @@ export function loadImage(url) {
     image.src = url
   })
 }
+
+/**
+ * What the page gives Motion to run scripts with: `script/script.js`, or a
+ * function returning it (or a promise of it), so the page fetches it only
+ * when a bundle needs it: `() => import('.../script/script.js')`.
+ *
+ * @typedef {{ createScripts: Function } | (() => any)} ScriptProvider
+ */
+
+/**
+ * Loads the script runtime and the bundle's bytecode.
+ *
+ * @param   {any}                                   manifest   a bundle's motion.json
+ * @param   {ScriptProvider | undefined}            provider
+ * @param   {(file: string) => Promise<Uint8Array>} fetchBytes a file of the bundle, as bytes
+ * @param   {(message: string) => void}             report
+ * @returns {Promise<import('../script/play/play.js').Scripts | null>} null for a bundle with no scripts, or with no way to run them
+ */
+export function loadScripts(manifest, provider, fetchBytes, report) {
+  const files = manifest.scripts
+  if (!files) return Promise.resolve(null)
+  if (!provider) {
+    report('this bundle has scripts, which run only when the scripts option gives Motion the script host; its script conditions do not pass, and its script converters pass values through')
+    return Promise.resolve(null)
+  }
+
+  const ids = Object.keys(files)
+  const loading = Promise.resolve(typeof provider === 'function' ? provider() : provider)
+  return Promise.all([ loading, Promise.all(ids.map((id) => fetchBytes(files[id]))) ]).then((loaded) => {
+    /** @type {Record<string, Uint8Array>} */
+    const bytes = {}
+    ids.forEach((id, n) => {
+      bytes[id] = loaded[1][n]
+    })
+    return loaded[0].createScripts(manifest, bytes, report)
+  })
+}

package/list/list.js

@@ -21,7 +21,7 @@
 import { createAnimation } from '../lottie/lottie.js'
 import { multiply } from '../lottie/lottie.paths.js'
 import { createNested, extend } from '../motion/motion.nested.js'
-import { slotValues } from '../motion/motion.values.js'
+import { slotValues, sourceValue } from '../motion/motion.values.js'
 import { layoutRows } from './list.flex.js'
 import { itemValues, rowNameOf, signature } from './list.items.js'
 
@@ -54,6 +54,7 @@ function scopeOf(id, sid) {
  * @property {() => number}                                    band       the width of the layout band showing, 0 for the file's own size
  * @property {() => number}                                    [blended]  between two bands that blend, the canvas's width, else 0: the box is then the mix of the two bands'
  * @property {() => (import('../bands/bands.js').Cell | null)} [cell]     where the canvas falls in the layout grid, while the fit is layout: the box is then the (bilinear) mix of the cell's corners'; it replaces `band` and `blended`
+ * @property {((list: any[]) => ReturnType<typeof import('../skin/skin.js').createSkins>) | null} [skins] makes the skins of a row's `data.skins`; null when the bundle has none, so the skin code is never loaded
  * @property {(message: string) => void}                       error
  * @property {(action: any, scope: string) => void}            focus      a row's machine ran a focus action: FocusTarget with the machine's own rid, FocusMove or FocusClear; `scope` is the machine (`row.<id>`, or `row.<id>/<sid>` for a nested artboard in the row)
  */
@@ -99,6 +100,15 @@ export function createLists(entries, lotties, options) {
     const values = itemValues(item, entry.data)
     const table = slotValues(entry.data, values, options.error)
     for (const sid in table) anim.slots[sid] = table[sid]
+    // the skinned paths the row's binds move, deformed for this item: its animation is its file's name
+    const rowSkins = options.skins && entry.data && entry.data.skins ? options.skins(entry.data.skins) : null
+    const animationId = String(entry.lottie).replace(/\.json$/, '')
+    const deformRow = (/** @type {Record<string, any>} */ current) => {
+      if (!rowSkins) return
+      const deformed = rowSkins.evaluate((source) => sourceValue(source, current, entry.data, options.error), animationId)
+      for (const sid in deformed) anim.slots[sid] = deformed[sid]
+    }
+    deformRow(values)
 
     // the row's own machine, and the machines of the nested artboards in it: each runs on the row's clock
     const machines = entry.machine ? [ { sid: 'row', fps: entry.machine.fps, machine: entry.machine.machine, animations: entry.machine.animations, inputs: {}, remoteKeys: entry.remoteKeys } ] : []
@@ -115,6 +125,7 @@ export function createLists(entries, lotties, options) {
           if (sid !== 'row') return
           const table = slotValues(entry.data, extend(values, changed), options.error)
           for (const slot in table) anim.slots[slot] = table[slot]
+          deformRow(extend(values, changed))
         },
       })
       runner.takeInputs(values)

package/lottie/lottie.layers.js

@@ -9,7 +9,7 @@
  */
 
 import { drawDocument } from '../player/overlay/overlay.js'
-import { drawOperations } from './lottie.paint.js'
+import { clipToOperations, drawOperations } from './lottie.paint.js'
 import { fromLottie, IDENTITY, multiply, trace, transformPath } from './lottie.paths.js'
 import { evaluator } from './lottie.props.js'
 import { compileItems, compileTransform, runGroup, scalar } from './lottie.shapes.js'
@@ -307,9 +307,10 @@ function clipToMasks(ctx, masks, local, matrix) {
 }
 
 /**
- * A layer through its track matte: both drawn on scratch canvases the size
- * of the target, the content kept where the matte is opaque (alpha) or
- * clear (inverted). Luma mattes are read as alpha mattes.
+ * A layer through its track matte. An alpha matte that is one opaque fill
+ * clips the layer to its path; any other is drawn with the layer on scratch
+ * canvases the size of the target, the content kept where the matte is
+ * opaque (alpha) or clear (inverted). Luma mattes are read as alpha mattes.
  *
  * @param {CanvasRenderingContext2D} ctx
  * @param {any}                      layer
@@ -321,10 +322,16 @@ function clipToMasks(ctx, masks, local, matrix) {
  * @param {number}                   opacity
  */
 function drawMatted(ctx, layer, matte, context, frame, matrix, matteMatrix, opacity) {
+  if (clipsByPath(ctx, layer, matte, frame, matteMatrix)) {
+    drawLayer(ctx, layer, context, frame, matrix, opacity)
+    ctx.restore()
+    return
+  }
+
   const width = ctx.canvas.width
   const height = ctx.canvas.height
-  const content = scratch(width, height)
-  const mask = scratch(width, height)
+  const content = takeScratch(width, height)
+  const mask = takeScratch(width, height)
   if (!content || !mask) {
     drawLayer(ctx, layer, context, frame, matrix, opacity)
     return
@@ -340,18 +347,64 @@ function drawMatted(ctx, layer, matte, context, frame, matrix, matteMatrix, opac
   ctx.setTransform(1, 0, 0, 1, 0, 0)
   ctx.drawImage(content.canvas, 0, 0)
   ctx.restore()
+  giveScratch(mask)
+  giveScratch(content)
 }
 
 /**
+ * Clips to the matte's path when an alpha matte is one opaque fill, leaving
+ * the clip saved for the caller to restore.
+ *
+ * @param   {CanvasRenderingContext2D} ctx
+ * @param   {any}                      layer
+ * @param   {any}                      matte
+ * @param   {number}                   frame
+ * @param   {Matrix}                   matteMatrix
+ * @returns {boolean}                              whether it clipped
+ */
+function clipsByPath(ctx, layer, matte, frame, matteMatrix) {
+  const isPlainShapes = layer.matte === 1 && matte.shapes && !matte.masks.length && matte.blend === 'source-over'
+  if (!isPlainShapes) return false
+
+  const local = frame - matte.st
+  const run = runGroup(matte.shapes, local, IDENTITY, 1, null)
+  ctx.save()
+  if (clipToOperations(ctx, run.operations, matteMatrix, local)) return true
+  ctx.restore()
+  return false
+}
+
+/** scratch canvases free for a matte to draw on; a matte inside a matte takes others */
+const SCRATCH = /** @type {CanvasRenderingContext2D[]} */ ([])
+
+/**
+ * A cleared scratch canvas of the size, reused across frames: a matte drawn
+ * every frame would otherwise make two canvases a frame.
+ *
  * @param   {number}                          width
  * @param   {number}                          height
  * @returns {CanvasRenderingContext2D | null}
  */
-function scratch(width, height) {
-  const canvas = document.createElement('canvas')
-  canvas.width = width
-  canvas.height = height
-  return canvas.getContext('2d')
+function takeScratch(width, height) {
+  const ctx = SCRATCH.pop() || document.createElement('canvas').getContext('2d')
+  if (!ctx) return null
+  const canvas = ctx.canvas
+  // setting the size clears it; a canvas already that size is cleared by hand
+  if (canvas.width !== width || canvas.height !== height) {
+    canvas.width = width
+    canvas.height = height
+  } else {
+    ctx.setTransform(1, 0, 0, 1, 0, 0)
+    ctx.globalCompositeOperation = 'source-over'
+    ctx.globalAlpha = 1
+    ctx.clearRect(0, 0, width, height)
+  }
+  return ctx
+}
+
+/** @param {CanvasRenderingContext2D} ctx */
+function giveScratch(ctx) {
+  SCRATCH.push(ctx)
 }
 
 /**

package/lottie/lottie.paint.js

@@ -35,6 +35,36 @@ export function drawOperations(ctx, operations, layer, opacity, frame) {
   }
 }
 
+/**
+ * Clips to what a layer's operations cover, when that is exactly one opaque
+ * solid fill: an alpha matte of it keeps the same pixels as a clip to its
+ * path, at none of a matte's offscreen cost. Anything else (strokes,
+ * gradients, transparency, several paints, merged paths) returns false and
+ * clips nothing.
+ *
+ * @param   {CanvasRenderingContext2D} ctx
+ * @param   {Operation[]}              operations as runGroup returns them
+ * @param   {Matrix}                   layer      the layer's space onto the canvas
+ * @param   {number}                   frame
+ * @returns {boolean}                             whether it clipped
+ */
+export function clipToOperations(ctx, operations, layer, frame) {
+  if (operations.length !== 1) return false
+  const operation = operations[0]
+  const style = operation.paint
+  const isOpaque = operation.opacity >= 1 && scalar(style.opacity(frame)) >= 100
+  const isSolidFill = !style.isStroke && !style.isGradient && (style.color(frame).length < 4 || style.color(frame)[3] >= 1)
+  if (!isOpaque || !isSolidFill || !operation.entries.length) return false
+  for (let n = 0; n < operation.entries.length; n++) if (operation.entries[n].holder.merge) return false
+
+  const m = multiply(layer, operation.matrix)
+  ctx.setTransform(m[0], m[1], m[2], m[3], m[4], m[5])
+  ctx.beginPath()
+  for (let n = 0; n < operation.entries.length; n++) traceEntry(ctx, operation.entries[n])
+  ctx.clip(style.rule)
+  return true
+}
+
 /**
  * @param {CanvasRenderingContext2D} ctx
  * @param {Operation}                operation

package/lottie/lottie.paths.js

@@ -98,16 +98,31 @@ export function trace(ctx, path) {
   if (!points.length) return
 
   ctx.moveTo(points[0].x, points[0].y)
-  for (let k = 1; k < points.length; k++) {
-    ctx.bezierCurveTo(cOut[k - 1].x, cOut[k - 1].y, cIn[k].x, cIn[k].y, points[k].x, points[k].y)
-  }
+  for (let k = 1; k < points.length; k++) segment(ctx, points[k - 1], cOut[k - 1], cIn[k], points[k])
   if (path.closed) {
     const last = points.length - 1
-    ctx.bezierCurveTo(cOut[last].x, cOut[last].y, cIn[0].x, cIn[0].y, points[0].x, points[0].y)
+    segment(ctx, points[last], cOut[last], cIn[0], points[0])
     ctx.closePath()
   }
 }
 
+/**
+ * One segment: a line where both handles sit on their points, as most of a
+ * Lottie's do, else the cubic. A line is far cheaper for the canvas to fill
+ * and stroke than a curve, and draws the same.
+ *
+ * @param {CanvasRenderingContext2D} ctx
+ * @param {Point}                    from
+ * @param {Point}                    out  from's out handle
+ * @param {Point}                    into to's in handle
+ * @param {Point}                    to
+ */
+function segment(ctx, from, out, into, to) {
+  const isStraight = out.x === from.x && out.y === from.y && into.x === to.x && into.y === to.y
+  if (isStraight) ctx.lineTo(to.x, to.y)
+  else ctx.bezierCurveTo(out.x, out.y, into.x, into.y, to.x, to.y)
+}
+
 // Shapes
 // ■■■■■■
 

package/lottie/lottie.props.js

@@ -9,14 +9,14 @@
  * where a keyframe carries its own end value in `e`.
  */
 
-import { mixValues } from '../mixer/mixer.mix.js'
+import { mixValues, settledWeight } from '../mixer/mixer.mix.js'
 
 /**
  * @typedef {(frame: number) => any} Evaluator
  */
 
 /**
- * Live slot values, by slot id; `undefined` leaves a property to its keyframes.
+ * Live slot values, by slot id; `undefined` leaves a property to its keyframes, and a function gives the value at a frame.
  * @typedef {Record<string, any>} Slots
  */
 
@@ -33,8 +33,12 @@ export function evaluator(property, slots, fallback) {
   const sid = property.sid
   if (typeof sid !== 'string') return keyed
 
+  // a nested machine that mixes several animations names where its poses are
+  const poseKey = property.pz ? 'pz:' + property.pz.n : ''
   return (frame) => {
     const live = slots[sid]
+    // a live value can depend on the frame: a skin the animation keys is asked for its path, in the poses of the machine it is drawn in
+    if (typeof live === 'function') return live(frame, poseKey ? slots[poseKey] : null)
     return live === undefined ? keyed(frame) : live
   }
 }
@@ -43,10 +47,12 @@ export function evaluator(property, slots, fallback) {
  * A property of a nested machine that plays several animations at once. The
  * machine says which it plays, as `{ start, frame, weight }` in the slot
  * `pz:<id>`: the first frame of the animation's segment on the stitched
- * timeline, how far in it is, and its weight. The value is the property's at
- * the frame the machine's time remap gives, with each pose that keys it
- * mixed in by its weight, in order, as Rive applies animations; one that
- * does not key it leaves it alone. Without poses it is the keyframes.
+ * timeline, how far in it is, and its weight. Rive applies the poses in
+ * order, each mixing the value toward its own by its weight, onto what the
+ * last frame left: held, that settles where each pose that keys the property
+ * counts by its weight times what the poses after it leave (`settledWeight`),
+ * and the setup value no longer shows. One that does not key it leaves it
+ * alone; with none keying it, it is the keyframes at the time remap's frame.
  *
  * @param   {any}       property `pz` is `{ n, k }`: the machine's id, and the segments that key the property
  * @param   {Evaluator} keyed
@@ -62,10 +68,14 @@ function posedEvaluator(property, keyed, slots) {
     if (!poses) return value
 
     let mixed = value
+    let total = 0
     for (let n = 0; n < poses.length; n++) {
       const pose = poses[n]
-      if (keying.indexOf(pose.start) < 0) continue
-      mixed = mixValues(mixed, keyed(pose.start + pose.frame), pose.weight)
+      const weight = keying.indexOf(pose.start) < 0 ? 0 : settledWeight(poses, n, keying)
+      if (weight <= 0) continue
+      // a running weighted average: each pose's share of what has been counted so far
+      total += weight
+      mixed = mixValues(mixed, keyed(pose.start + pose.frame), weight / total)
     }
     return mixed
   }

package/lottie/lottie.shapes.js

@@ -205,7 +205,8 @@ export function runGroup(items, frame, matrix, opacity, sink) {
     } else if (item.kind === 'group') {
       const local = item.transform(frame)
       const inner = runGroup(item.items, frame, multiply(matrix, local.matrix), opacity * local.opacity, sink)
-      if (sink && item.rid) {
+      // a group that draws nothing (a Solo's hidden child, or anything faded out) is not a place a pointer can hit
+      if (sink && item.rid && opacity * local.opacity > 0) {
         const rid = sink.prefix + item.rid
         if (sink.hits.wants(rid)) sink.hits.add(rid, inner.entries, multiply(sink.matrix, multiply(matrix, local.matrix)))
       }

package/mixer/mixer.js

@@ -35,11 +35,14 @@ import { mixValues } from './mixer.mix.js'
  * @property {number} weight    0 to 1
  */
 
-/** What an animation does to one property: its value at a frame, whether it keys the property, and, for a pair of axes with one keyed, which */
-/** @typedef {{ at: Evaluator, keyed: boolean, axes: number[] | null }} Source */
+/** What an animation does to one property: its value at a frame, whether it keys the property, and, for a pair of axes with one keyed, which; `picks` for a Solo option's visibility, which an animation sets whole, never blends */
+/** @typedef {{ at: Evaluator, keyed: boolean, axes: number[] | null, picks: boolean }} Source */
+
+/** The `rid` of a Solo option's visibility: `<object id>.solo` */
+const SOLO = /\.solo$/
 
 /** A pose, prepared for the evaluators: where its animation's sources are, and how far its frame is from the drawn one */
-/** @typedef {{ sources: Record<string, Source>, offset: number, weight: number }} Prepared */
+/** @typedef {{ animation: string, sources: Record<string, Source>, offset: number, weight: number }} Prepared */
 
 /**
  * What the mixing evaluators share: the poses of the draw, and each property's value after the previous frame.
@@ -59,6 +62,7 @@ const NO_SLOTS = {}
  * @property {Animation}                                                                                               animation the mixed picture; its `slots` are live
  * @property {string}                                                                                                  carrier   the animation whose structure it has
  * @property {(ctx: CanvasRenderingContext2D, poses: Pose[], matrix: Matrix, frame?: number, passes?: number) => void} draw      `frame` counts the stage's steps: drawing the same frame again leaves each property where it was; `passes` applies the poses that many times, for a stage that has stopped but must settle
+ * @property {(read: (animation: string) => any, base: any) => Evaluator}                                          mixed     a value each animation gives on its own (a slot the player fills, such as a skin's path), mixed over the poses being drawn: each pose whose animation gives one lerps toward it by its weight
  */
 
 /**
@@ -92,6 +96,18 @@ export function createMixer(lotties, options) {
       }
       animation.draw(ctx, prepare(lotties, sources, poses, current, carrier), matrix)
     },
+    mixed(read, base) {
+      return (frame) => {
+        let value = typeof base === 'function' ? base(frame) : base
+        for (let n = 0; n < current.poses.length; n++) {
+          const pose = current.poses[n]
+          const own = read(pose.animation)
+          if (own === undefined) continue
+          value = mixValues(value, typeof own === 'function' ? own(frame + pose.offset) : own, pose.weight)
+        }
+        return value
+      }
+    },
   }
 }
 
@@ -126,7 +142,7 @@ function collect(lottie) {
   const found = {}
   visit(lottie, (property) => {
     if (found[property.rid]) return
-    found[property.rid] = { at: evaluator(property, NO_SLOTS), keyed: property.ky === 1, axes: Array.isArray(property.kc) ? property.kc : null }
+    found[property.rid] = { at: evaluator(property, NO_SLOTS), keyed: property.ky === 1, axes: Array.isArray(property.kc) ? property.kc : null, picks: SOLO.test(property.rid) }
   })
   return found
 }
@@ -144,8 +160,10 @@ function visit(node, found) {
     return
   }
   if (typeof node.rid === 'string' && 'k' in node) found(node)
+  // a property's `k` holds its values; a gradient's `g.k` is a property itself
+  const isProperty = 'a' in node || typeof node.rid === 'string'
   for (const key in node) {
-    if (key === 'k' || key === 'rid') continue
+    if ((key === 'k' && isProperty) || key === 'rid') continue
     visit(node[key], found)
   }
 }
@@ -191,7 +209,10 @@ function baseOf(rid, sources, carrier, lottie) {
     const source = sources[id][rid]
     if (source && !source.keyed) return source.at(0)
   }
-  const first = sources[carrier][rid].at(lottie.ip || 0)
+  // a property the carrier does not tag starts from the first animation that does
+  let own = sources[carrier][rid]
+  for (const id in sources) if (!own) own = sources[id][rid]
+  const first = own.at(lottie.ip || 0)
   if (!Array.isArray(first)) return first
 
   const result = first.slice()
@@ -242,7 +263,9 @@ function mixing(rid, base, current) {
         if (!source || !source.keyed) continue
 
         const sample = source.at(frame + pose.offset)
-        value = source.axes ? mixAxes(value, sample, pose.weight, source.axes) : mixValues(value, sample, pose.weight)
+        // a Solo's choice is an id, which Rive sets from any animation applying it, the last one winning
+        if (source.picks) value = pose.weight > 0 ? sample : value
+        else value = source.axes ? mixAxes(value, sample, pose.weight, source.axes) : mixValues(value, sample, pose.weight)
       }
     }
     current.next[rid] = value
@@ -278,7 +301,7 @@ function prepare(lotties, sources, poses, current, carrier) {
       isFirst = false
     }
     const frame = (lottie.ip || 0) + pose.time * (lottie.fr || 30)
-    current.poses.push({ sources: sources[pose.animation], offset: frame - drawn, weight: pose.weight })
+    current.poses.push({ animation: pose.animation, sources: sources[pose.animation], offset: frame - drawn, weight: pose.weight })
   }
   return drawn
 }

package/mixer/mixer.mix.js

@@ -88,3 +88,20 @@ function mixPoints(a, b, t) {
   for (let n = 0; n < a.length; n++) points.push(mixVectors(a[n], b[n], t))
   return points
 }
+
+/**
+ * How much a pose counts in the value the poses settle on: its weight, times
+ * what each pose after it that keys the value too leaves of it.
+ *
+ * @param   {Array<{ start: number, weight: number }>} poses
+ * @param   {number}                                  at     the pose's index
+ * @param   {number[]}                                keying the segments that key the value
+ * @returns {number}
+ */
+export function settledWeight(poses, at, keying) {
+  let weight = poses[at].weight
+  for (let n = at + 1; n < poses.length && weight > 0; n++) {
+    if (keying.indexOf(poses[n].start) >= 0) weight *= 1 - Math.min(1, poses[n].weight)
+  }
+  return weight
+}

package/motion/motion.convert.js

@@ -14,6 +14,9 @@
  * @property {(path: string) => any}     [read]  a view-model property's value, by dotted path
  * @property {string[]}                  [names] the names of an enum the value indexes
  * @property {(message: string) => void} [warn]
+ * @property {import('../script/play/play.js').Scripts} [scripts]  runs the bundle's script converters
+ * @property {string}                     [type]   the bound property's type, so a script is given a colour as one
+ * @property {Record<string, any>}         [values] every live value, which a script can read
  */
 
 /**
@@ -126,13 +129,20 @@ export function applyConverter(descriptor, value, context) {
       return enumIndex(value, ctx.names)
     case 'listLength':
       return Array.isArray(value) ? value.length : 0
+    case 'solo':
+      return soloVisibility(descriptor, value)
     case 'group': {
       let result = value
       const items = descriptor.items || []
       // only the first link sees the enum names
-      for (let n = 0; n < items.length; n++) result = applyConverter(items[n], result, n === 0 ? ctx : { read: ctx.read, warn: ctx.warn })
+      for (let n = 0; n < items.length; n++) result = applyConverter(items[n], result, n === 0 ? ctx : { read: ctx.read, warn: ctx.warn, scripts: ctx.scripts, values: ctx.values })
       return result
     }
+    case 'script':
+      // run by the bundle's script host; without one the value passes through
+      if (ctx.scripts) return ctx.scripts.convert(descriptor, value, false, ctx.type === 'color' ? 'color' : undefined, ctx.values)
+      warnUnknown(descriptor, ctx)
+      return value
     default:
       warnUnknown(descriptor, ctx)
       return value
@@ -171,6 +181,8 @@ export function reverseConverter(descriptor, value, context) {
       for (let n = items.length - 1; n >= 0; n--) result = reverseConverter(items[n], result, ctx)
       return result
     }
+    case 'script':
+      return ctx.scripts ? ctx.scripts.convert(descriptor, value, true) : value
     default:
       return value
   }
@@ -358,6 +370,25 @@ function pad(d, text) {
   return d.atEnd ? result.slice(0, wanted) : result.slice(result.length - wanted)
 }
 
+/**
+ * A Solo option's visibility, in percent: 100 when the bound value names it,
+ * 0 otherwise. A number names an option by its place among the Solo's options
+ * (`index`), an enum or a string by name (`names`, the ones that pick the
+ * option; an enum's value is its index, which `ids` lists). A descriptor with
+ * neither is an option no value reaches.
+ *
+ * @param {any}            d
+ * @param {any}            value
+ */
+function soloVisibility(d, value) {
+  if (Array.isArray(d.names)) {
+    if (typeof value === 'string') return d.names.indexOf(value) >= 0 ? 100 : 0
+    return Array.isArray(d.ids) && typeof value === 'number' && d.ids.indexOf(value) >= 0 ? 100 : 0
+  }
+  if (typeof d.index === 'number') return Math.round(numeric(value)) === d.index ? 100 : 0
+  return 0
+}
+
 /**
  * An enum value as its index, from an index or a name.
  *

package/motion/motion.flow.js

@@ -31,6 +31,7 @@ const MAX_SETTLE = 16
  * @property {(action: any) => void}                                                [focus]       a focus action (FocusTarget, FocusMove, FocusClear) ran
  * @property {(layer: number, state: any, fadeMs: number, ease?: number[]) => void} [layer]       a layer entered a state, fading in along `ease`'s curve; replaces `play`
  * @property {(layer: number) => number}                                            [elapsed]     ms the layer's current state has played, unwrapped
+ * @property {import('../script/play/play.js').Scripts | null}                      [scripts]     the scripts the bundle runs, read when a guard or action needs them
  */
 
 /**
@@ -54,6 +55,8 @@ export function createFlow(manifest, hooks) {
   let transitions = {}
   /** Entry actions and listeners that run while a state is being entered must not settle the machine under it */
   let busy = 0
+  /** the interaction whose actions are running, which a script's pointer event is of */
+  let trigger = ''
 
   /**
    * The defaults, with the caller's inputs over them; then the first state.
@@ -182,7 +185,7 @@ export function createFlow(manifest, hooks) {
     for (let n = 0; n < MAX_SETTLE; n++) {
       /** @type {any[]} */
       const taken = []
-      for (let layer = 0; layer < graphs.length; layer++) taken.push(takeTransition(graphs[layer], currents[layer], values, events, clockOf(layer)))
+      for (let layer = 0; layer < graphs.length; layer++) taken.push(takeTransition(graphs[layer], currents[layer], values, events, clockOf(layer), hooks.scripts || null))
       if (!taken.some(Boolean)) break
       // an event that moved the machine is spent
       events = {}
@@ -270,6 +273,16 @@ export function createFlow(manifest, hooks) {
     settle()
   }
 
+  /**
+   * Values were written straight into `values` (by the bundle's scripted
+   * objects, which the next ones read at once): the player redraws and the
+   * machine settles, as for `takeInputs`.
+   */
+  function changed() {
+    if (graph) settle()
+    else hooks.valuesChanged(values)
+  }
+
   /**
    * @param   {Record<string, any>} inputs
    * @returns {boolean}                    whether anything changed or fired
@@ -325,7 +338,9 @@ export function createFlow(manifest, hooks) {
    */
   function click(isUntargeted) {
     if (!graph) return
+    trigger = 'Click'
     run(interactionActions(graph, 'Click', '', isUntargeted ? '' : undefined))
+    trigger = ''
     settle()
   }
 
@@ -337,7 +352,9 @@ export function createFlow(manifest, hooks) {
    */
   function pointer(type, target) {
     if (!graph) return
+    trigger = type
     run(interactionActions(graph, type, '', target))
+    trigger = ''
     settle()
   }
 
@@ -370,7 +387,7 @@ export function createFlow(manifest, hooks) {
   /** @param {any[]} actions */
   function run(actions) {
     if (!graph || !actions || !actions.length) return
-    const effects = perform(actions, graph, values, events)
+    const effects = perform(actions, graph, values, events, hooks.scripts || null, trigger)
     for (let n = 0; n < effects.events.length; n++) hooks.event(effects.events[n])
     if (effects.changed) hooks.valuesChanged(values)
     if (hooks.focus) for (let n = 0; n < effects.focus.length; n++) hooks.focus(effects.focus[n])
@@ -380,6 +397,7 @@ export function createFlow(manifest, hooks) {
     start,
     jumpTo,
     takeInputs,
+    changed,
     act,
     focusEvent,
     click,