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

package/readme.md

@@ -114,18 +114,19 @@ A bundle's `lists` (from a Rive `ArtboardComponentList`) says how to draw a view
 | 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, a blend's first animation, instant switches ([the limit](../roku/readme.md#what-rive-does-that-roku-does-not)) | `mixer/`: the pose mixer |
+| 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 text overlay shows its slot's converted text (a number through a `toString` converter reads `72.6`).
+- **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
 
@@ -159,7 +160,7 @@ Pointer listeners answer where the pointer is. A listener that watches a shape o
 - **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 or its opacity (an invisible shape still hits, and a stroke is not widened), 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).
+- **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
 
@@ -220,6 +221,7 @@ Rive plays several animations of one artboard at once and mixes what they do. A
 
 - **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.
@@ -248,6 +250,74 @@ Rive plays several animations of one artboard at once and mixes what they do. A
 | `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
 
@@ -257,6 +327,7 @@ 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.
@@ -264,7 +335,11 @@ npm run motion web parity         # the parity scorecard against Rive's canvas r
 - **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
+}

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

@@ -0,0 +1,189 @@
+/**
+ * The `table` library.
+ */
+
+import { LuaTable, fail, typeName } from '../../vm/vm.value.js'
+import { lessThan, truthy } from '../../vm/vm.meta.js'
+import { argError, checkFunction, checkInt, checkTable, optInt, register } from '../lib.args.js'
+import { unpack } from './base.js'
+
+/** @param {LuaTable} t */
+function writable(t) {
+  if (t.frozen) throw fail('attempt to modify a readonly table')
+}
+
+/**
+ * Sorts `list` in place with `less`, stably (merge sort).
+ *
+ * @param {any[]} list
+ * @param {(a: any, b: any) => boolean} less
+ */
+function sort(list, less) {
+  const n = list.length
+  if (n < 2) return
+  let src = list
+  let dst = new Array(n)
+  for (let width = 1; width < n; width *= 2) {
+    for (let lo = 0; lo < n; lo += 2 * width) {
+      const mid = Math.min(lo + width, n)
+      const hi = Math.min(lo + 2 * width, n)
+      let i = lo
+      let j = mid
+      let o = lo
+      while (i < mid && j < hi) dst[o++] = less(src[j], src[i]) ? src[j++] : src[i++]
+      while (i < mid) dst[o++] = src[i++]
+      while (j < hi) dst[o++] = src[j++]
+    }
+    const swap = src
+    src = dst
+    dst = swap
+  }
+  if (src !== list) for (let i = 0; i < n; i++) list[i] = src[i]
+}
+
+/**
+ * @param {import('../../vm/vm.js').VM} vm
+ * @param {LuaTable} G
+ */
+export function installTable(vm, G) {
+  const table = new LuaTable()
+  G.set('table', table)
+
+  register(table, {
+    insert(vm, args) {
+      const t = checkTable(args, 0, 'insert')
+      writable(t)
+      const n = t.length()
+      if (args.length === 2) {
+        t.set(n + 1, args[1])
+        return []
+      }
+      if (args.length !== 3) throw fail("wrong number of arguments to 'insert'")
+      const pos = checkInt(args, 1, 'insert')
+      if (pos < 1 || pos > n + 1) throw argError(2, 'insert', 'position out of bounds')
+      if (args[2] === undefined) return []
+      t.arr.splice(pos - 1, 0, args[2])
+      if (t.hn !== null) t.migrate()
+      return []
+    },
+
+    remove(vm, args) {
+      const t = checkTable(args, 0, 'remove')
+      writable(t)
+      const n = t.length()
+      const pos = optInt(args, 1, 'remove', n)
+      if (n === 0 && args[1] === undefined) return undefined
+      if (pos < 1 || pos > n) {
+        if (args[1] !== undefined && pos !== n + 1) throw argError(2, 'remove', 'position out of bounds')
+        return undefined
+      }
+      const v = t.arr[pos - 1]
+      t.arr.splice(pos - 1, 1)
+      let m = t.arr.length
+      while (m > 0 && t.arr[m - 1] === undefined) m--
+      t.arr.length = m
+      return v
+    },
+
+    concat(vm, args) {
+      const t = checkTable(args, 0, 'concat')
+      const sep = args[1] === undefined ? '' : String(args[1])
+      const i = optInt(args, 2, 'concat', 1)
+      const j = optInt(args, 3, 'concat', t.length())
+      const parts = []
+      for (let n = i; n <= j; n++) {
+        const v = t.get(n)
+        if (typeof v === 'string') parts.push(v)
+        else if (typeof v === 'number') parts.push(vm.tostring(v))
+        else throw fail('invalid value (' + typeName(v) + ') at index ' + n + " in table for 'concat'")
+      }
+      return parts.join(sep)
+    },
+
+    unpack(vm, args) {
+      return unpack(checkTable(args, 0, 'unpack'), args[1], args[2])
+    },
+
+    pack(vm, args) {
+      const t = new LuaTable()
+      t.setRange(1, args, 0, args.length)
+      t.set('n', args.length)
+      return t
+    },
+
+    sort(vm, args) {
+      const t = checkTable(args, 0, 'sort')
+      writable(t)
+      const cmp = args[1]
+      if (cmp !== undefined) checkFunction(args, 1, 'sort')
+      const n = t.length()
+      const list = t.arr.slice(0, n)
+      /** @type {(a: any, b: any) => boolean} */
+      const less = cmp === undefined
+        ? function (a, b) { return lessThan(vm, a, b) }
+        : function (a, b) { return truthy(vm.call(cmp, [ a, b ])[0]) }
+      sort(list, less)
+      for (let i = 0; i < n; i++) t.arr[i] = list[i]
+      return []
+    },
+
+    find(vm, args) {
+      const t = checkTable(args, 0, 'find')
+      const init = optInt(args, 2, 'find', 1)
+      const n = t.length()
+      for (let i = init; i <= n; i++) if (t.get(i) === args[1]) return i
+      return undefined
+    },
+
+    clear(vm, args) {
+      const t = checkTable(args, 0, 'clear')
+      writable(t)
+      t.arr.length = 0
+      for (let s = 0; s < t.hv.length; s++) t.hv[s] = undefined
+      t.dead = t.hv.length
+      return []
+    },
+
+    create(vm, args) {
+      const n = checkInt(args, 0, 'create')
+      if (n < 0) throw argError(1, 'create', 'size out of range')
+      const t = new LuaTable()
+      if (args[1] !== undefined) for (let i = 1; i <= n; i++) t.set(i, args[1])
+      return t
+    },
+
+    clone(vm, args) {
+      return checkTable(args, 0, 'clone').clone()
+    },
+
+    freeze(vm, args) {
+      const t = checkTable(args, 0, 'freeze')
+      if (t.meta !== undefined && t.meta.getStr('__metatable') !== undefined) throw argError(1, 'freeze', 'table has a protected metatable')
+      t.frozen = true
+      return t
+    },
+
+    isfrozen(vm, args) {
+      return checkTable(args, 0, 'isfrozen').frozen
+    },
+
+    getn(vm, args) {
+      return checkTable(args, 0, 'getn').length()
+    },
+
+    move(vm, args) {
+      const a1 = checkTable(args, 0, 'move')
+      const f = checkInt(args, 1, 'move')
+      const e = checkInt(args, 2, 'move')
+      const t = checkInt(args, 3, 'move')
+      const a2 = args[4] === undefined ? a1 : checkTable(args, 4, 'move')
+      writable(a2)
+      if (e >= f) {
+        if (!(f > 0 || e < Number.MAX_VALUE + f)) throw argError(3, 'move', 'too many elements to move')
+        if (t > e || t <= f || a1 !== a2) for (let i = 0; i <= e - f; i++) a2.set(t + i, a1.get(f + i))
+        else for (let i = e - f; i >= 0; i--) a2.set(t + i, a1.get(f + i))
+      }
+      return a2
+    },
+  }, 'table.')
+}