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

package/readme.md

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

package/script/luau/lib/base/base.js

@@ -0,0 +1,202 @@
+/**
+ * The base library: `assert`, `error`, `pcall`, `type`, `tostring`,
+ * `ipairs`, `pairs`, `select`, `setmetatable`, `print` and the rest of the
+ * globals that are not in a table.
+ */
+
+import { EMPTY, LuaTable, LuaThrow, NativeFunction, Vector, fail, typeName } from '../../vm/vm.value.js'
+import { equals, rawSet, toNumber, tostring } from '../../vm/vm.meta.js'
+import { numberToString, stringToNumberBase } from '../../vm/vm.num.js'
+import { argError, checkAny, checkInt, checkTable, optInt, register } from '../lib.args.js'
+
+/**
+ * @param   {any} e  something caught
+ * @returns {{ value: any } | null} the Lua error value, or null when e is not a Lua error
+ */
+function caught(e) {
+  if (e instanceof LuaThrow) return { value: e.value }
+  if (e instanceof RangeError) return { value: 'stack overflow' }
+  return null
+}
+
+/**
+ * @param   {import('../../vm/vm.js').VM} vm
+ * @param   {LuaTable} G  the globals
+ */
+export function installBase(vm, G) {
+  register(G, {
+    assert(vm, args) {
+      if (args[0] === undefined || args[0] === false) throw fail(args.length > 1 ? args[1] : 'assertion failed!', args.length > 1 && typeof args[1] !== 'string' ? 0 : 1)
+      return args
+    },
+
+    error(vm, args) {
+      const level = optInt(args, 1, 'error', 1)
+      const value = args[0]
+      // a number message is made a string when a position may be added, as lua_concat does
+      const wants = (typeof value === 'string' || typeof value === 'number') && level > 0
+      throw new LuaThrow(wants && typeof value === 'number' ? numberToString(value) : value, wants ? level : 0)
+    },
+
+    pcall(vm, args) {
+      checkAny(args, 0)
+      try {
+        return [ true ].concat(vm.call(args[0], args.slice(1)))
+      } catch (e) {
+        const c = caught(e)
+        if (c === null) throw e
+        return [ false, c.value ]
+      }
+    },
+
+    xpcall(vm, args) {
+      checkAny(args, 0)
+      try {
+        return [ true ].concat(vm.call(args[0], args.slice(2)))
+      } catch (e) {
+        const c = caught(e)
+        if (c === null) throw e
+        return [ false ].concat(vm.call(args[1], [ c.value ]))
+      }
+    },
+
+    type(vm, args) {
+      checkAny(args, 0)
+      return typeName(args[0])
+    },
+
+    typeof(vm, args) {
+      checkAny(args, 0)
+      return typeName(args[0])
+    },
+
+    tostring(vm, args) {
+      checkAny(args, 0)
+      return tostring(vm, args[0])
+    },
+
+    tonumber(vm, args) {
+      const base = args[1]
+      if (base === undefined) {
+        checkAny(args, 0)
+        return toNumber(args[0])
+      }
+      const b = checkInt(args, 1, 'tonumber')
+      if (b < 2 || b > 36) throw argError(2, 'tonumber', 'base out of range')
+      if (typeof args[0] !== 'string') throw argError(1, 'tonumber', 'string expected, got ' + typeName(args[0]))
+      return stringToNumberBase(args[0], b)
+    },
+
+    ipairs(vm, args) {
+      checkTable(args, 0, 'ipairs')
+      return [ vm.inext, args[0], 0 ]
+    },
+
+    pairs(vm, args) {
+      checkTable(args, 0, 'pairs')
+      return [ vm.next, args[0], undefined ]
+    },
+
+    next(vm, args) {
+      const t = checkTable(args, 0, 'next')
+      const pos = t.after(args[1])
+      if (pos === undefined) throw fail("invalid key to 'next'")
+      const nextPos = t.advance(pos)
+      return nextPos === null ? undefined : [ t.ck, t.cv ]
+    },
+
+    select(vm, args) {
+      const n = args[0]
+      if (n === '#') return args.length - 1
+      let i = checkInt(args, 0, 'select')
+      if (i < 0) i = args.length + i
+      else if (i > args.length - 1) return EMPTY
+      if (i < 1) throw argError(1, 'select', 'index out of range')
+      return args.slice(i)
+    },
+
+    rawget(vm, args) {
+      return checkTable(args, 0, 'rawget').get(args[1])
+    },
+
+    rawset(vm, args) {
+      const t = checkTable(args, 0, 'rawset')
+      rawSet(t, args[1], args[2])
+      return t
+    },
+
+    rawequal(vm, args) {
+      checkAny(args, 1)
+      const a = args[0]
+      const b = args[1]
+      return a === b || (a instanceof Vector && b instanceof Vector && equals(vm, a, b))
+    },
+
+    rawlen(vm, args) {
+      const v = args[0]
+      if (v instanceof LuaTable) return v.length()
+      if (typeof v === 'string') return v.length
+      throw argError(1, 'rawlen', 'table or string expected')
+    },
+
+    setmetatable(vm, args) {
+      const t = checkTable(args, 0, 'setmetatable')
+      const mt = args[1]
+      if (mt !== undefined && !(mt instanceof LuaTable)) throw argError(2, 'setmetatable', 'nil or table expected')
+      if (t.frozen) throw fail('Attempt to modify a readonly table')
+      if (t.meta !== undefined && t.meta.getStr('__metatable') !== undefined) throw fail('cannot change a protected metatable')
+      t.meta = mt
+      return t
+    },
+
+    getmetatable(vm, args) {
+      checkAny(args, 0)
+      const v = args[0]
+      const mt = v instanceof LuaTable ? v.meta : typeof v === 'string' ? vm.stringMeta : undefined
+      if (mt === undefined) return undefined
+      const guard = mt.getStr('__metatable')
+      return guard !== undefined ? guard : mt
+    },
+
+    unpack(vm, args) {
+      return unpack(checkTable(args, 0, 'unpack'), args[1], args[2])
+    },
+
+    print(vm, args) {
+      const parts = []
+      for (let i = 0; i < args.length; i++) parts.push(tostring(vm, args[i]))
+      vm.print(parts.join('\t'))
+      return EMPTY
+    },
+
+    collectgarbage(vm, args) {
+      return args[0] === 'count' ? 0 : 0
+    },
+  })
+
+  G.set('_G', G)
+  G.set('_VERSION', 'Luau')
+
+  vm.next = /** @type {NativeFunction} */ (G.getStr('next'))
+  vm.inext = new NativeFunction('inext', function (vm2, args) {
+    const t = checkTable(args, 0, 'ipairs')
+    const i = checkInt(args, 1, 'ipairs') + 1
+    const v = t.get(i)
+    return v === undefined ? undefined : [ i, v ]
+  })
+}
+
+/**
+ * @param   {LuaTable} t
+ * @param   {any}      first  key to start at, default 1
+ * @param   {any}      last   key to end at, default #t
+ * @returns {any[]}
+ */
+export function unpack(t, first, last) {
+  const i = first === undefined ? 1 : /** @type {number} */ (toNumber(first))
+  const j = last === undefined ? t.length() : /** @type {number} */ (toNumber(last))
+  if (j - i >= 1e6) throw fail('too many results to unpack')
+  const out = []
+  for (let n = i; n <= j; n++) out.push(t.get(n))
+  return out
+}