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

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@px-petals/roku.motion-web",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "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",
+  "main": "motion.js",
+  "exports": {
+    ".": "./motion.js",
+    "./*/.tests": null,
+    "./*.test.js": null,
+    "./*.js": "./*.js"
+  },
+  "files": [
+    "**/*",
+    "!**/.tests",
+    "!**/*.test.js",
+    "!jsconfig*.json",
+    "!legacy",
+    "!.artifacts"
+  ],
+  "sideEffects": false,
+  "browserslist": [
+    "chrome >= 32",
+    "safari >= 7.1",
+    "ios_saf >= 8",
+    "firefox >= 29",
+    "android >= 4.4.3",
+    "samsung >= 4",
+    "edge >= 18"
+  ],
+  "scripts": {
+    "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\" \"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",
+    "url": "git+https://github.com/px-petals/motion.git",
+    "directory": "src/runtime/web"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/player/overlay/overlay.js

@@ -0,0 +1,325 @@
+/**
+ * Text overlays: the text layers lottie-roku lifts out of an animation,
+ * drawn on the canvas each frame along their tracks. A track's keys are
+ * linear per frame (lottie-roku samples the Lottie's easing), so drawing at
+ * a frame is a linear blend between two keys. A live input replaces the
+ * text it fills: the first run's, when the text has several.
+ *
+ * A text is one or more styled runs. They flow together through lines that
+ * wrap at the box width (`wrap`), align across it (`align`) and sit in its
+ * height (`valign`); see overlay.layout.js.
+ */
+
+import { fontOf, layoutRuns } from './overlay.layout.js'
+
+/** @import { Matrix } from '../../lottie/lottie.paths.js' */
+/** @import { Line, Run } from './overlay.layout.js' */
+
+/** Where a font's baseline sits below the top of its em box, as a fraction of its size */
+const ASCENT = 0.8
+
+/**
+ * @param {CanvasRenderingContext2D} ctx
+ * @param {any[]}                    texts    an animation's `texts`
+ * @param {number}                   frame    from the animation's start
+ * @param {Record<string, any>}      values   live inputs
+ * @param {Record<string, string>}   families bundle font name → registered family
+ * @param {Matrix}                   matrix   the animation's space onto the canvas
+ * @param {Record<string, string>}   inputOf  overlay slot id → the input that fills it
+ */
+export function drawOverlays(ctx, texts, frame, values, families, matrix, inputOf) {
+  for (let n = 0; n < (texts || []).length; n++) {
+    const text = texts[n]
+    const track = text.track
+    const isVisible = frame >= track.visible[0] && frame < track.visible[1]
+    if (!isVisible) continue
+
+    const opacity = keyAt(track.opacity, frame)[0] / 100
+    if (opacity <= 0) continue
+
+    const input = text.sid ? inputOf[text.sid] : undefined
+    const live = input !== undefined && values[input] !== undefined && values[input] !== null ? String(values[input]) : null
+    const position = keyAt(track.position, frame)
+    const scale = keyAt(track.scale, frame)
+    const rotation = (keyAt(track.rotation, frame)[0] * Math.PI) / 180
+
+    ctx.save()
+    ctx.setTransform(matrix[0], matrix[1], matrix[2], matrix[3], matrix[4], matrix[5])
+    ctx.translate(position[0], position[1])
+    ctx.rotate(rotation)
+    ctx.scale(scale[0] / 100, scale[1] / 100)
+    ctx.globalAlpha = Math.min(1, opacity)
+    ctx.textAlign = 'left'
+    drawText(ctx, text, runsOf(text, live), families)
+    ctx.restore()
+  }
+}
+
+/**
+ * A text layer drawn where the renderer is: a Lottie text document, which a
+ * nested artboard's text stays as inside its precomp, drawn at a matrix to
+ * the canvas as an overlay is, with the live words in place of the document's.
+ *
+ * @param {CanvasRenderingContext2D} ctx
+ * @param {any}                      doc      the layer's text document
+ * @param {string | null}            live     the words a data bind sets
+ * @param {Record<string, string>}   families bundle font name → registered family
+ * @param {Matrix}                   matrix   the layer's space onto the canvas
+ */
+export function drawDocument(ctx, doc, live, families, matrix) {
+  const text = overlayOf(doc)
+  ctx.save()
+  ctx.setTransform(matrix[0], matrix[1], matrix[2], matrix[3], matrix[4], matrix[5])
+  ctx.textAlign = 'left'
+  drawText(ctx, text, runsOf(text, live), families)
+  ctx.restore()
+}
+
+/**
+ * The overlay lottie-roku makes of a text document, without its track.
+ *
+ * @param   {any} doc
+ * @returns {any}
+ */
+function overlayOf(doc) {
+  const size = doc.s || 12
+  const spacing = (/** @type {number} */ tracking) => Math.round(((tracking || 0) / 1000) * size * 100) / 100
+  const color = (/** @type {number[] | undefined} */ fc) => {
+    const channels = (fc || [ 0, 0, 0 ]).map((/** @type {number} */ channel) => Math.round(Math.min(1, Math.max(0, channel)) * 255))
+    return '0x' + channels.map((/** @type {number} */ n) => (n < 16 ? '0' : '') + n.toString(16)).join('') + 'ff'
+  }
+  const runs = Array.isArray(doc.rs) && doc.rs.length > 1 ? doc.rs.map((/** @type {any} */ run) => {
+    const own = run.s || size
+    return { text: String(run.t || '').replace(/\r/g, '\n'), font: run.f || doc.f || '', size: own, color: color(run.fc || doc.fc), lineHeight: run.lh || own * 1.2, letterSpacing: Math.round(((run.tr || 0) / 1000) * own * 100) / 100 }
+  }) : null
+  return {
+    text: String(doc.t || '').replace(/\r/g, '\n'),
+    font: doc.f || '',
+    size,
+    color: color(doc.fc),
+    align: [ 'left', 'right', 'center' ][doc.j] || 'left',
+    lineHeight: doc.lh || size * 1.2,
+    letterSpacing: spacing(doc.tr),
+    runs,
+    wrap: !doc.nw,
+    valign: doc.va === 'middle' || doc.va === 'bottom' ? doc.va : 'top',
+    box: doc.sz ? [ doc.sz[0], doc.sz[1] ] : null,
+    boxOrigin: doc.ps ? [ doc.ps[0], doc.ps[1] ] : [ 0, 0 ],
+  }
+}
+
+/**
+ * A track's value at a frame: before the first key, its value; between two,
+ * their linear blend; after the last, its value.
+ *
+ * @param   {{ t: number, v: number[] }[]} keys
+ * @param   {number}                       frame
+ * @returns {number[]}
+ */
+export function keyAt(keys, frame) {
+  if (!keys.length) return [ 0, 0 ]
+  if (frame <= keys[0].t) return keys[0].v
+  for (let n = 1; n < keys.length; n++) {
+    const next = keys[n]
+    if (frame > next.t) continue
+    const previous = keys[n - 1]
+    const span = next.t - previous.t
+    const t = span > 0 ? (frame - previous.t) / span : 1
+    return previous.v.map((value, d) => value + (next.v[d] - value) * t)
+  }
+  return keys[keys.length - 1].v
+}
+
+/** The channels of a text's track, and how many values each key holds */
+const CHANNELS = [ 'position', 'scale', 'rotation', 'opacity' ]
+
+/**
+ * What several animations playing at once show of their texts: each text of
+ * the first, with every channel of its track mixed as Rive mixes the
+ * animations that key it, in order, each lerping toward its own value by its
+ * weight. A channel an animation does not move (one key) is left alone by it.
+ * A text shows when it shows in the animation with the most weight.
+ *
+ * The texts of every animation are the same list, in the same order. The
+ * result is for `drawOverlays` at frame 0.
+ *
+ * @param   {{ texts: any[], frame: number, weight: number }[]} poses in the order they apply
+ * @returns {any[]}
+ */
+export function mixOverlays(poses) {
+  const first = poses.length ? poses[0].texts || [] : []
+  /** @type {any[]} */
+  const mixed = []
+  for (let n = 0; n < first.length; n++) {
+    let heaviest = poses[0]
+    for (let p = 1; p < poses.length; p++) if (poses[p].weight >= heaviest.weight) heaviest = poses[p]
+    const lead = (heaviest.texts || [])[n]
+    if (!lead) continue
+    const isVisible = heaviest.frame >= lead.track.visible[0] && heaviest.frame < lead.track.visible[1]
+    if (!isVisible) continue
+
+    /** @type {Record<string, any>} */
+    const track = { frames: lead.track.frames, fps: lead.track.fps, visible: [ 0, 1 ] }
+    for (let c = 0; c < CHANNELS.length; c++) {
+      const channel = CHANNELS[c]
+      // what no animation moves: the static value, from the one that is heaviest
+      let value = keyAt(lead.track[channel], heaviest.frame)
+      for (let p = 0; p < poses.length; p++) {
+        const other = (poses[p].texts || [])[n]
+        if (other && other.track[channel].length < 2) value = keyAt(other.track[channel], 0)
+      }
+      for (let p = 0; p < poses.length; p++) {
+        const other = (poses[p].texts || [])[n]
+        if (!other || other.track[channel].length < 2) continue
+        const sample = keyAt(other.track[channel], poses[p].frame)
+        const weight = Math.min(1, Math.max(0, poses[p].weight))
+        value = value.map((v, d) => v + (sample[d] - v) * weight)
+      }
+      track[channel] = [ { t: 0, v: value } ]
+    }
+    mixed.push({ ...lead, track })
+  }
+  return mixed
+}
+
+/**
+ * The runs a text draws: its own, or one in the text's style, with a live
+ * value in place of the first run's words.
+ *
+ * @param   {any}           text
+ * @param   {string | null} live
+ * @returns {Run[]}
+ */
+function runsOf(text, live) {
+  const spacing = text.letterSpacing || 0
+  const hasRuns = text.runs && text.runs.length
+  if (!hasRuns) {
+    return [ { text: live === null ? text.text : live, font: text.font, size: text.size, color: text.color, lineHeight: text.lineHeight || text.size * 1.2, letterSpacing: spacing } ]
+  }
+
+  const runs = []
+  for (let n = 0; n < text.runs.length; n++) {
+    const run = text.runs[n]
+    runs.push({ text: n === 0 && live !== null ? live : run.text, font: run.font, size: run.size, color: run.color, lineHeight: run.lineHeight || run.size * 1.2, letterSpacing: run.letterSpacing || 0 })
+  }
+  return runs
+}
+
+/**
+ * Box text wraps at the box's width and sits in its height from its
+ * top-left; point text hangs from its origin, the first baseline on it.
+ *
+ * @param {CanvasRenderingContext2D} ctx
+ * @param {any}                      text
+ * @param {Run[]}                    runs
+ * @param {Record<string, string>}   families
+ */
+function drawText(ctx, text, runs, families) {
+  const [ x, y ] = text.boxOrigin
+  const box = text.box
+  const lines = layoutRuns(ctx, runs, box ? box[0] : null, text.wrap !== false, families)
+
+  let top = y
+  if (box) {
+    let total = 0
+    for (let n = 0; n < lines.length; n++) total += lines[n].height
+    if (text.valign === 'middle') top += (box[1] - total) / 2
+    else if (text.valign === 'bottom') top += box[1] - total
+  } else if (lines.length) {
+    // the first baseline sits on the origin
+    top -= lines[0].height
+  }
+
+  for (let n = 0; n < lines.length; n++) {
+    const line = lines[n]
+    const left = lineLeft(text.align, line.width, x, box)
+    drawLine(ctx, line, left, box ? top : top + line.height, !!box, families)
+    top += line.height
+  }
+}
+
+/**
+ * @param   {string}          align
+ * @param   {number}          width the line's
+ * @param   {number}          x     the box's left, or point text's origin
+ * @param   {number[] | null} box
+ * @returns {number}                where the line starts
+ */
+function lineLeft(align, width, x, box) {
+  const room = box ? box[0] - width : -width
+  if (align === 'center') return x + room / 2
+  if (align === 'right') return x + room
+  return x
+}
+
+/**
+ * Draws a line's pieces side by side. In a box a line hangs from its top
+ * and a smaller run is dropped to share the line's baseline; point text
+ * stands on its baseline.
+ *
+ * @param {CanvasRenderingContext2D} ctx
+ * @param {Line}                     line
+ * @param {number}                   left
+ * @param {number}                   y        the line's top in a box, its baseline otherwise
+ * @param {boolean}                  isBoxed
+ * @param {Record<string, string>}   families
+ */
+function drawLine(ctx, line, left, y, isBoxed, families) {
+  let x = left
+  for (let n = 0; n < line.pieces.length; n++) {
+    const piece = line.pieces[n]
+    const run = piece.run
+    ctx.font = fontOf(run, families)
+    ctx.fillStyle = cssColor(run.color)
+    // a line in a box hangs from its top: the font's own ascent above the baseline, as Rive sets it, where the browser measures it
+    const ascent = isBoxed ? ascentOf(ctx) : null
+    ctx.textBaseline = isBoxed && ascent === null ? 'top' : 'alphabetic'
+    const at = isBoxed ? y + (line.size - run.size) * ASCENT + (ascent === null ? 0 : ascent) : y
+    if (run.letterSpacing) drawSpaced(ctx, piece.text, x, at, run.letterSpacing)
+    else ctx.fillText(piece.text, x, at)
+    x += piece.width
+  }
+}
+
+/**
+ * How far above its baseline a font's line reaches, where the browser
+ * measures it (an old one does not: its text hangs from the em box's top).
+ *
+ * @param   {CanvasRenderingContext2D} ctx the context, with the run's font set
+ * @returns {number | null}
+ */
+function ascentOf(ctx) {
+  const ascent = /** @type {any} */ (ctx.measureText('Hg')).fontBoundingBoxAscent
+  return typeof ascent === 'number' && ascent > 0 ? ascent : null
+}
+
+/**
+ * Canvas text has no letter spacing in older browsers, so each character is
+ * placed on its own.
+ *
+ * @param {CanvasRenderingContext2D} ctx
+ * @param {string}                   text
+ * @param {number}                   x
+ * @param {number}                   y
+ * @param {number}                   spacing px after each character
+ */
+function drawSpaced(ctx, text, x, y, spacing) {
+  let pen = x
+  for (let n = 0; n < text.length; n++) {
+    const char = text.charAt(n)
+    ctx.fillText(char, pen, y)
+    pen += ctx.measureText(char).width + spacing
+  }
+}
+
+/**
+ * lottie-roku's `0xRRGGBBAA` as CSS.
+ *
+ * @param {string} value
+ */
+function cssColor(value) {
+  const hex = String(value).replace(/^0x|^#/i, '')
+  const byte = (/** @type {number} */ at) => parseInt(hex.slice(at, at + 2), 16)
+  const alpha = hex.length >= 8 ? byte(6) / 255 : 1
+  return 'rgba(' + byte(0) + ',' + byte(2) + ',' + byte(4) + ',' + alpha + ')'
+}

package/player/overlay/overlay.layout.js

@@ -0,0 +1,208 @@
+/**
+ * Lays styled runs out in lines with `measureText`: words wrap at the box
+ * width, a word wider than the box breaks between characters, and each line
+ * records the pieces to draw, its width and its height.
+ */
+
+/**
+ * One run's style, as an overlay carries it.
+ *
+ * @typedef {object} Run
+ * @property {string} text
+ * @property {string} font          bundle font name
+ * @property {number} size          px
+ * @property {string} color         0xRRGGBBAA
+ * @property {number} lineHeight    px
+ * @property {number} letterSpacing px after each character
+ */
+
+/**
+ * A stretch of one run on one line.
+ *
+ * @typedef {object} Piece
+ * @property {Run}    run
+ * @property {string} text
+ * @property {number} width
+ */
+
+/**
+ * @typedef {object} Line
+ * @property {Piece[]} pieces
+ * @property {number}  width  without trailing spaces
+ * @property {number}  height the tallest run's line height
+ * @property {number}  size   the largest run's font size
+ */
+
+/**
+ * @param   {Run}                    run
+ * @param   {Record<string, string>} families bundle font name → registered family
+ * @returns {string}                          a canvas font
+ */
+export function fontOf(run, families) {
+  return run.size + 'px "' + (families[run.font] || run.font) + '", sans-serif'
+}
+
+/**
+ * @param   {CanvasRenderingContext2D} ctx
+ * @param   {Run[]}                    runs
+ * @param   {number | null}            width     the box's width; null for point text, which never wraps
+ * @param   {boolean}                  isWrapped
+ * @param   {Record<string, string>}   families
+ * @returns {Line[]}
+ */
+export function layoutRuns(ctx, runs, width, isWrapped, families) {
+  const limit = isWrapped && width !== null ? width : Infinity
+  const lines = [ newLine(runs[0]) ]
+
+  const words = wordsOf(ctx, runs, families)
+  for (let n = 0; n < words.length; n++) {
+    const word = words[n]
+    if (word.isBreak) {
+      lines.push(newLine(word.run))
+    } else if (word.isSpace) {
+      // a space never starts a wrapped line, and trailing ones don't count
+      const line = lines[lines.length - 1]
+      if (line.pieces.length) addPiece(line, word.pieces[0])
+    } else {
+      placeWord(ctx, lines, word, limit, families)
+    }
+  }
+  for (let n = 0; n < lines.length; n++) trim(lines[n])
+  return lines
+}
+
+/**
+ * @param   {Run}  [run] the run the line starts in, for the height of an empty one
+ * @returns {Line}
+ */
+function newLine(run) {
+  return { pieces: [], width: 0, height: run ? run.lineHeight : 0, size: run ? run.size : 0 }
+}
+
+/**
+ * @param {Line}  line
+ * @param {Piece} piece added to the end of the line
+ */
+function addPiece(line, piece) {
+  line.pieces.push(piece)
+  line.height = Math.max(line.height, piece.run.lineHeight)
+  line.size = Math.max(line.size, piece.run.size)
+  line.width += piece.width
+}
+
+/**
+ * Words, spaces and line breaks of the runs, in order. A word is the
+ * stretch between spaces and may cross runs, which only changes its pieces'
+ * style.
+ *
+ * @param   {CanvasRenderingContext2D}                                                                ctx
+ * @param   {Run[]}                                                                                   runs
+ * @param   {Record<string, string>}                                                                  families
+ * @returns {Array<{ pieces: Piece[], width: number, isSpace: boolean, isBreak: boolean, run: Run }>}
+ */
+function wordsOf(ctx, runs, families) {
+  const out = []
+  /** @type {{ pieces: Piece[], width: number, isSpace: boolean, isBreak: boolean, run: Run } | null} */
+  let word = null
+  const flush = () => {
+    if (word) out.push(word)
+    word = null
+  }
+
+  for (let r = 0; r < runs.length; r++) {
+    const run = runs[r]
+    const text = String(run.text).replace(/\r\n|\r/g, '\n')
+    let start = 0
+    for (let n = 0; n <= text.length; n++) {
+      const char = n < text.length ? text.charAt(n) : ''
+      const isEdge = char === ' ' || char === '\n' || n === text.length
+      if (!isEdge) continue
+
+      if (n > start) {
+        const piece = pieceOf(ctx, run, text.slice(start, n), families)
+        word = word || { pieces: [], width: 0, isSpace: false, isBreak: false, run }
+        word.pieces.push(piece)
+        word.width += piece.width
+      }
+      start = n + 1
+      // a word ends at a space or a break; at the end of a run it may go on
+      if (char === ' ') {
+        flush()
+        out.push({ pieces: [ pieceOf(ctx, run, ' ', families) ], width: 0, isSpace: true, isBreak: false, run })
+      } else if (char === '\n') {
+        flush()
+        out.push({ pieces: [], width: 0, isSpace: false, isBreak: true, run })
+      }
+    }
+  }
+  flush()
+  return out
+}
+
+/**
+ * @param   {CanvasRenderingContext2D} ctx
+ * @param   {Run}                      run
+ * @param   {string}                   text
+ * @param   {Record<string, string>}   families
+ * @returns {Piece}
+ */
+function pieceOf(ctx, run, text, families) {
+  ctx.font = fontOf(run, families)
+  return { run, text, width: ctx.measureText(text).width + run.letterSpacing * text.length }
+}
+
+/**
+ * Puts a word on the current line, or the next when it doesn't fit, or
+ * across several when it is wider than a line of its own.
+ *
+ * @param {CanvasRenderingContext2D}                     ctx
+ * @param {Line[]}                                       lines
+ * @param {{ pieces: Piece[], width: number, run: Run }} word
+ * @param {number}                                       limit
+ * @param {Record<string, string>}                       families
+ */
+function placeWord(ctx, lines, word, limit, families) {
+  let line = lines[lines.length - 1]
+  if (line.pieces.length && line.width + word.width > limit) {
+    trim(line)
+    line = newLine(word.run)
+    lines.push(line)
+  }
+
+  const isTooWide = word.width > limit
+  if (!isTooWide) {
+    for (let n = 0; n < word.pieces.length; n++) addPiece(line, word.pieces[n])
+    return
+  }
+
+  // a word wider than the line breaks between characters
+  for (let n = 0; n < word.pieces.length; n++) {
+    const piece = word.pieces[n]
+    const text = piece.text
+    for (let c = 0; c < text.length; c++) {
+      let chars = text.charAt(c)
+      // keep a surrogate pair together
+      const code = chars.charCodeAt(0)
+      if (code >= 0xd800 && code < 0xdc00 && c + 1 < text.length) chars += text.charAt(++c)
+      const one = pieceOf(ctx, piece.run, chars, families)
+      if (line.pieces.length && line.width + one.width > limit) {
+        trim(line)
+        line = newLine(piece.run)
+        lines.push(line)
+      }
+      addPiece(line, one)
+    }
+  }
+}
+
+/**
+ * Drops a line's trailing spaces, so they neither count towards its width
+ * nor push centred or right-aligned text off balance.
+ *
+ * @param {Line} line
+ */
+function trim(line) {
+  while (line.pieces.length && line.pieces[line.pieces.length - 1].text === ' ') {
+    line.width -= /** @type {Piece} */ (line.pieces.pop()).width
+  }
+}

package/player/player.fit.js

@@ -0,0 +1,101 @@
+/**
+ * Where an animation goes in its canvas: Rive's fit and alignment, and which
+ * of a responsive artboard's layout bands the canvas is wide enough for.
+ *
+ * Fit is how the artboard scales into the canvas (`contain`, `cover`,
+ * `fill`, `fitWidth`, `fitHeight`, `scaleDown`, `none`, `layout`); alignment
+ * is where the rest of the canvas goes, from -1 (left, top) to 1 (right,
+ * bottom) on each axis. A fit that does not fill the canvas leaves the
+ * remainder to the alignment, and one that overflows it is cut by the canvas.
+ *
+ * `none` and `scaleDown` count in CSS pixels, so an animation keeps its size
+ * on a high-density screen. `layout` plays the layout band for the canvas's
+ * width, then fits it as `contain` does.
+ */
+
+/** @import { Matrix } from '../lottie/lottie.paths.js' */
+
+/** Rive's alignment names, as [x, y] */
+const ALIGNMENTS = {
+  topLeft: [ -1, -1 ],
+  topCenter: [ 0, -1 ],
+  topRight: [ 1, -1 ],
+  centerLeft: [ -1, 0 ],
+  center: [ 0, 0 ],
+  centerRight: [ 1, 0 ],
+  bottomLeft: [ -1, 1 ],
+  bottomCenter: [ 0, 1 ],
+  bottomRight: [ 1, 1 ],
+}
+
+const FITS = [ 'contain', 'cover', 'fill', 'fitWidth', 'fitHeight', 'scaleDown', 'none', 'layout' ]
+
+/**
+ * @param   {any}    fit one of Rive's fits; anything else is `contain`
+ * @returns {string}
+ */
+export function fitName(fit) {
+  return FITS.indexOf(fit) >= 0 ? fit : 'contain'
+}
+
+/**
+ * @param   {any}              alignment a Rive alignment name, or `[x, y]` from -1 to 1
+ * @returns {[number, number]}           centre for anything unrecognised
+ */
+export function alignmentOf(alignment) {
+  if (typeof alignment === 'string' && ALIGNMENTS[/** @type {keyof typeof ALIGNMENTS} */ (alignment)]) return /** @type {[number, number]} */ (ALIGNMENTS[/** @type {keyof typeof ALIGNMENTS} */ (alignment)])
+  const isPair = alignment && alignment.length === 2 && typeof alignment[0] === 'number' && typeof alignment[1] === 'number'
+  return isPair ? [ clamp(alignment[0]), clamp(alignment[1]) ] : [ 0, 0 ]
+}
+
+/** @param {number} value */
+function clamp(value) {
+  return Math.max(-1, Math.min(1, value))
+}
+
+/**
+ * The matrix taking the animation's space onto the canvas's.
+ *
+ * @param   {string}           fit
+ * @param   {[number, number]} alignment
+ * @param   {number}           width        the animation's own width
+ * @param   {number}           height
+ * @param   {number}           canvasWidth  in canvas pixels
+ * @param   {number}           canvasHeight
+ * @param   {number}           [ratio]      canvas pixels per CSS pixel; default 1
+ * @returns {Matrix}
+ */
+export function fitMatrix(fit, alignment, width, height, canvasWidth, canvasHeight, ratio) {
+  const scaleX = canvasWidth / width
+  const scaleY = canvasHeight / height
+  const contain = Math.min(scaleX, scaleY)
+  const unit = ratio || 1
+
+  let sx = contain
+  let sy = contain
+  if (fit === 'cover') sx = sy = Math.max(scaleX, scaleY)
+  else if (fit === 'fill') {
+    sx = scaleX
+    sy = scaleY
+  } else if (fit === 'fitWidth') sx = sy = scaleX
+  else if (fit === 'fitHeight') sx = sy = scaleY
+  else if (fit === 'none') sx = sy = unit
+  else if (fit === 'scaleDown') sx = sy = Math.min(unit, contain)
+
+  return [ sx, 0, 0, sy, ((canvasWidth - width * sx) / 2) * (1 + alignment[0]), ((canvasHeight - height * sy) / 2) * (1 + alignment[1]) ]
+}
+
+/**
+ * The layout band a canvas is wide enough for: the widest that fits, else the
+ * narrowest, which then scales down.
+ *
+ * @param   {any[] | undefined} bands a bundle's `bands`, narrowest first
+ * @param   {number}            width the canvas's width in CSS pixels
+ * @returns {any | null}              null without bands
+ */
+export function pickBand(bands, width) {
+  if (!bands || !bands.length) return null
+  let picked = bands[0]
+  for (let n = 1; n < bands.length; n++) if (bands[n].width <= width) picked = bands[n]
+  return picked
+}