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

package/script/luau/luau.js

@@ -0,0 +1,132 @@
+/**
+ * A Luau bytecode loader and interpreter: load compiled bytecode, run its
+ * main chunk against globals the host provides, and call Lua functions from
+ * JS and JS functions from Lua. See `luau.md` for the design.
+ *
+ * ```js
+ * const luau = createLuau({ print: (text) => console.log(text) })
+ * luau.set('twice', (n) => n * 2)
+ * const module = luau.load(bytes)          // bytes start at the version byte
+ * const results = luau.run(module)         // the main chunk's returns, as host values
+ * luau.call(luau.get('update'), 16)        // a global Lua function
+ * ```
+ *
+ * Rive writes one wrapper byte before the bytecode of a script; strip it
+ * before `load`.
+ */
+
+import { loadBytecode } from './load/load.js'
+import { installLibs } from './lib/lib.js'
+import { LuauError, luauError, multi, toJs, toLua, encodeUtf8, decodeUtf8 } from './luau.convert.js'
+import { VM } from './vm/vm.js'
+import { LuaClosure, LuaTable, LuaThrow, NativeFunction, Vector } from './vm/vm.value.js'
+
+export { loadBytecode, LuauError, LuaClosure, LuaTable, NativeFunction, Vector, VM, multi, toJs, toLua, encodeUtf8, decodeUtf8 }
+
+/** @typedef {import('./load/load.js').Module} Module */
+
+/**
+ * @typedef {object} LuauOptions
+ * @property {(text: string) => void} [print]  where `print` writes, a line at a time; default discards
+ * @property {boolean}                [libs]   install the standard library subset; default true
+ * @property {string}                 [chunk]  the chunk name errors carry; default the module's own or `?`
+ * @property {Record<string, any>}    [globals]  host values to set as globals
+ */
+
+/** A VM with its libraries and the host-facing calls */
+export class Luau {
+  /** @param {LuauOptions} [options] */
+  constructor(options) {
+    const o = options || {}
+    this.options = o
+    this.vm = new VM({ print: o.print, chunk: o.chunk })
+    if (o.libs !== false) installLibs(this.vm)
+    if (o.globals) for (const name in o.globals) this.set(name, o.globals[name])
+  }
+
+  /**
+   * @param   {Uint8Array} bytes  bytecode from its version byte on
+   * @param   {string}     [chunk]  the chunk name for errors
+   * @returns {Module}
+   */
+  load(bytes, chunk) {
+    return loadBytecode(bytes, chunk || this.options.chunk)
+  }
+
+  /**
+   * Sets a global from a host value.
+   *
+   * @param {string} name
+   * @param {any}    value
+   */
+  set(name, value) {
+    this.vm.globals.set(encodeUtf8(name), toLua(this.vm, value))
+  }
+
+  /**
+   * @param   {string} name
+   * @returns {any}    the global as a host value
+   */
+  get(name) {
+    return toJs(this.vm, this.vm.globals.get(encodeUtf8(name)))
+  }
+
+  /**
+   * @param   {string} name
+   * @returns {any}    the global as the Lua value it is
+   */
+  getRaw(name) {
+    return this.vm.globals.get(encodeUtf8(name))
+  }
+
+  /**
+   * Runs a module's main chunk.
+   *
+   * @param   {Module} module
+   * @param   {any[]}  [args]  host values passed to the chunk as `...`
+   * @returns {any[]}  what the chunk returned, as host values
+   */
+  run(module, args) {
+    const results = this.callRaw(this.vm.instantiate(module), (args || []).map((a) => toLua(this.vm, a)))
+    return results.map((r) => toJs(this.vm, r))
+  }
+
+  /**
+   * Calls a Lua value with Lua values. Throws `LuauError` for a Lua error.
+   *
+   * @param   {any}   fn
+   * @param   {any[]} args
+   * @returns {any[]} the results, as Lua values
+   */
+  callRaw(fn, args) {
+    try {
+      return this.vm.call(fn, args)
+    } catch (e) {
+      throw e instanceof LuaThrow ? luauError(this.vm, e) : e
+    }
+  }
+
+  /**
+   * Calls a Lua function with host values.
+   *
+   * @param   {any}    fn  a Lua function (`getRaw`), or a host function made from one (`get`)
+   * @param   {...any} args
+   * @returns {any}    nothing, the one result, or an array of results, as host values
+   */
+  call(fn, ...args) {
+    if (typeof fn === 'function') return fn.apply(null, args)
+    const f = fn
+    const results = this.callRaw(f, args.map((a) => toLua(this.vm, a)))
+    if (results.length === 0) return undefined
+    if (results.length === 1) return toJs(this.vm, results[0])
+    return results.map((r) => toJs(this.vm, r))
+  }
+}
+
+/**
+ * @param   {LuauOptions} [options]
+ * @returns {Luau}
+ */
+export function createLuau(options) {
+  return new Luau(options)
+}

package/script/luau/luau.md

@@ -0,0 +1,111 @@
+# luau
+
+A Luau bytecode loader and interpreter in plain JS, for the scripts a Rive file carries as compiled Luau. It knows nothing of Rive: a host adds its own globals. The design is table-driven and keeps its state in plain arrays and objects (a register stack, a frame stack, a dispatch on small integers), so the BrightScript port can follow it file by file.
+
+```js
+import { createLuau } from '@px-petals/roku.motion-web/script/luau/luau.js'
+
+const luau = createLuau({ print: (text) => console.log(text) })
+luau.set('twice', (n) => n * 2)               // a host function, or any host value
+const module = luau.load(bytes)               // bytes start at the version byte
+const returned = luau.run(module)             // the main chunk's results, as host values
+const update = luau.getRaw('update')          // a Lua function, as the Lua value it is
+luau.call(update, 16)                         // call it with host values
+```
+
+Rive writes one wrapper byte before the bytecode of a script. The caller strips it: `load` takes a `Uint8Array` that begins at the Luau version byte.
+
+| Call | |
+| --- | --- |
+| `createLuau({ print, libs, chunk, globals })` | a VM with the standard library subset installed (`libs: false` for none) |
+| `luau.load(bytes, chunk?)` | decodes bytecode into a `Module`; throws on a version it cannot read, a truncated file or an unknown opcode |
+| `luau.run(module, args?)` | runs the main chunk in this VM's globals; `args` arrive as `...` |
+| `luau.set(name, value)` / `get(name)` / `getRaw(name)` | globals, converted to and from host values, or raw |
+| `luau.call(fn, ...args)` | calls a Lua function (or a host function made from one) and converts |
+| `luau.callRaw(fn, args)` | the same with Lua values in and an array of Lua values out |
+| `luau.vm` | the `VM`: `call`, `globals`, `native(name, fn)`, `stringMeta` |
+
+An error in Lua code throws `LuauError { message, value, line, chunk }`; `line` is 0 when the bytecode was stripped of debug info (Rive's is), and the message then has no position. A host function that throws becomes a Lua error that `pcall` can catch.
+
+`luau.convert.js` holds the conversions: strings cross as UTF-8 (Lua strings are byte strings), arrays and plain objects become tables and back, host functions become Lua functions and back, `multi(a, b)` returns several results, and Lua values (tables, functions, vectors) pass through unchanged. For live access to a Lua table, use the raw API: `LuaTable` has `get`, `set`, `getStr`, `length` and `advance` (traversal).
+
+## Files
+
+| File | Holds |
+| --- | --- |
+| `load/load.js` | the bytecode reader: strings, protos, constants, line and debug info |
+| `load/load.ops.js` | opcode names in Bytecode.h order, instruction lengths, version bounds |
+| `vm/vm.js` | `VM`: the value stack, frame stack, open upvalues, `call` |
+| `vm/vm.run.js` | `Frame`, `enter`, and `execute`, the instruction loop |
+| `vm/vm.meta.js` | `index`, `setIndex`, `arith`, `equals`, `lessThan`, `concat`, `length`, `tostring`: Lua's operations with their metamethods |
+| `vm/vm.value.js` | value types and `LuaTable` |
+| `vm/vm.num.js` | number formatting (`%g`, `%e`, `%f`) and reading |
+| `lib/` | the standard library subset, one folder per area |
+| `.tests/asm/` | a bytecode assembler for tests (Luau's `BytecodeBuilder` encoding in JS) |
+| `.tests/reference/` | the official Luau toolchain as a test oracle (see below) |
+| `.tests/sources/`, `.tests/fixtures/` | Luau programs, and their committed `-O1` bytecode and expected output |
+
+## Values
+
+| Lua | JS | Notes |
+| --- | --- | --- |
+| nil | `undefined` | |
+| boolean | `true`, `false` | |
+| number | a double | integers are doubles too, as in Luau |
+| string | a JS string holding bytes: one char per byte, 0 to 255 | `("é"):len()` is 2; the host converts at its edge |
+| vector | `Vector { x, y, z }` | immutable; equal and keyed by components |
+| table | `LuaTable` | see below |
+| function | `LuaClosure { proto, upvals, env }` or `NativeFunction { name, fn }` | |
+| upvalue | `Upvalue { s, i, v }` | `s` is the stack while the variable is live (`stack[i]`), `null` once closed (`v`) |
+
+A JS array is never a Lua value, so a native function may return one to mean several results; any other value is a single result, and `EMPTY` (an empty array) is none.
+
+**Tables** keep keys 1..n in an array `arr` (no trailing nils, so `arr.length` is a border and `#t`). Every other key lives in one of three dictionaries (strings, numbers, other values by identity id) that map a key to a *slot* in the parallel arrays `hk` and `hv`. Slots stay in insertion order, which is traversal order; a removed key keeps its slot with a nil value, so assigning nil during `pairs` is safe, and the slots are rebuilt when half are dead. A traversal position is an array index (0 and up) or `-1 - slot`. A BrightScript port can use an `roArray` and an `roAssociativeArray` of slot numbers the same way.
+
+## Bytecode
+
+A module is a string table, then protos. A proto is `maxStack`, `numParams`, `numUpvals`, `isVararg`, `flags`, type info (kept raw, not used), the instruction words (`Int32Array`), constants, child protos, `lineDefined`, debug name, line info and local and upvalue names. Versions 3 to 14 load, with type-info versions 1 to 3. Version 12 on prefixes each proto with its size and keeps feedback slots and an inline cost, which the loader reads past; the compiler of release 0.744 emits version 14, whose compiled calls are `CALLFB` (a `CALL` and a feedback word) and whose `pcall` sites carry a `FASTPCALL` hint, both run as the ordinary call.
+
+Constants load as Lua values (nil, booleans, numbers, byte strings, `Vector`) except three descriptors: `Import` (a packed path of constant names), `TableTemplate` (the keys, and for version 7 the values, of a DUPTABLE) and `ClosureRef` (the proto of a DUPCLOSURE).
+
+Line info is stored the way Luau stores it (a baseline per 2^gap words and a byte delta each) and expanded at load to one source line per instruction word.
+
+## Execution
+
+An instruction is a 32-bit word. The opcode is the low byte; `A`, `B` and `C` are the next three bytes, or `A` and a signed 16-bit `D`, or a signed 24-bit `E`. Some opcodes are followed by an AUX word (`load.ops.js` lists them). A jump `D` counts from the word after the instruction, or from its AUX word when it has one (so `1` skips the AUX).
+
+The VM has one value stack, a plain array shared by every call. A frame is `{ cl, base, pc, ret, nres, varargs, entry }`: register `n` is `stack[base + n]`; `ret` is the slot the callee's results go to, which is the slot its function was called from; `nres` is how many results the caller wants, or -1 for all.
+
+`execute` loops over the top frame: `switch (insn & 255)` over the opcode numbers, written as literal numbers with the name in a comment (a test keeps them equal to Bytecode.h's). A call from Lua to a Lua closure pushes a frame and swaps the loop's locals, so Lua recursion does not use the JS stack and is bounded by the frame limit (20000, "stack overflow"). A call to a native function, and metamethod, `pcall`, `sort` and generic-for calls, run through `VM.call`, which starts a nested `execute` on the same stacks; those nest up to 200 deep ("C stack overflow").
+
+- **Arguments and results.** The caller puts the function at `ra` and arguments after it; the callee's base is `ra + 1`, so arguments are already its first registers. Missing parameters are set to nil. A vararg function copies its extra arguments into `frame.varargs`; GETVARARGS reads them.
+- **Multiple values.** CALL, RETURN, SETLIST and GETVARARGS with count 0 mean "up to `top`". `top` is a local of the loop, set by the instruction that produced the values and read by the next.
+- **Upvalues.** NEWCLOSURE reads the CAPTURE words that follow it. A by-reference capture finds or makes an open `Upvalue` for the stack slot (`findUpvalue`, kept sorted); CLOSEUPVALS and RETURN close the ones at or above a base by copying the slot into `v`. A by-value capture makes a closed upvalue at once.
+- **Calls through the fast path.** FASTCALL, FASTCALL1, 2, 2K and 3 are skipped: Luau always emits the ordinary call sequence after them, so doing nothing is correct.
+- **Generic for.** FORGPREP recognises a table (and `pairs`/`ipairs` via FORGPREP_NEXT and FORGPREP_INEXT, identified by function identity) and turns the registers into a built-in traversal: `ra = nil`, `ra + 1 = table`, `ra + 2 = position`. FORGLOOP advances it without a call. Anything else is called each turn. A `__iter` metamethod is honoured.
+- **Errors.** `LuaThrow` carries the error value and a `level`: how many Lua frames up its position comes from (1 for the code that called `error`). `execute` catches an error on its way out, adds `chunk:line:` from the frame's saved `pc`, and rethrows. `VM.call` unwinds the frames and closes the upvalues of a call that threw, so `pcall` is a try/catch around `VM.call`.
+- **Metamethods.** The interpreter does number and plain-table work inline and calls `vm.meta.js` for the rest: `__index`, `__newindex`, `__call`, `__add` and the other arithmetic ones, `__eq`, `__lt`, `__le`, `__len`, `__concat`, `__unm`, `__tostring`, `__iter`, `__metatable`. Strings share one metatable whose `__index` is the `string` table, which is how NAMECALL on a string finds `upper`.
+
+## Library
+
+base (`assert`, `error`, `pcall`, `xpcall`, `type`, `typeof`, `tostring`, `tonumber`, `ipairs`, `pairs`, `next`, `select`, `rawget`, `rawset`, `rawequal`, `rawlen`, `setmetatable`, `getmetatable`, `unpack`, `print`, `collectgarbage` (a stub)), `math` (all, with `noise` and `random` from a small generator that is not Luau's), `table` (`insert`, `remove`, `concat`, `unpack`, `pack`, `sort`, `find`, `clear`, `create`, `clone`, `freeze`, `isfrozen`, `move`, `getn`), `string` (`byte`, `char`, `find`, `match`, `gmatch`, `gsub` on Lua 5.1 patterns, `format`, `len`, `lower`, `upper`, `rep`, `reverse`, `sub`, `split`), `bit32`, `vector`, and `os.clock` and `os.time`. `print` goes to the host hook.
+
+Not carried: coroutines, `buffer`, `utf8`, `string.pack` and `unpack`, `os.date`, `getfenv` and `setfenv`, 64-bit integer and class constants of bytecode versions 8 and up (the loader refuses a module that holds one), and Luau's native codegen opcodes. `string.format` has no `%a`.
+
+## Checked against the official Luau
+
+The tests hold the VM to the real compiler and interpreter. `.tests/sources/*.luau` are programs (arithmetic, strings and patterns, `string.format`, tables, metatables, closures, every loop, varargs, `pcall` and `error`, methods, vectors, integer-like doubles, `table.sort`, `bit32`, deep recursion). The reference test compiles each with the official `luau-compile --binary` at -O0, -O1 and -O2, loads the bytes here and requires the loader to consume every one, runs them, and runs the same source on the official `luau`; what both print must match byte for byte, error messages included.
+
+- **The reference is a pinned release** of [luau-lang/luau](https://github.com/luau-lang/luau/releases): one version, with each platform's asset URL and SHA-256 in `.tests/reference/reference.json`. It is test-only and never ships (`.tests` is outside the package's `files`).
+- **Fetch it** with `npm run luau:fetch` in `src/runtime/web`. It downloads the asset for this platform, checks the hash, unpacks it with the OS's `tar` (bsdtar reads zip) into `.artifacts/luau/<version>/` (git-ignored) and marks the binaries executable. Nothing else is fetched.
+- **Without the binaries** the reference tests skip, naming that script. CI that has not fetched them runs only the committed fixtures: `.tests/fixtures/<name>.O1.luaubc` is each program's -O1 bytecode and `<name>.out` what the reference printed, so the loader and interpreter are still checked against real compiler output.
+- **Regenerate the fixtures** after changing a source or the pinned version: `npm run luau:fetch`, then `npm run luau:fixtures`, and commit the files. With the binaries present a test fails when a committed `.luaubc` is not what the pinned compiler emits.
+- **Opt-in only.** No install or prepare hook runs the fetch, nothing under `.tests` ships, and the VM does not load it.
+- **To move the pin**, change `reference.json` (version, URLs, hashes from the release page), fetch, regenerate, and run the tests.
+
+## Porting notes
+
+- Everything the interpreter needs is a number, a string, a boolean, an array or an object with fixed fields; there is no reliance on closures for Lua semantics (`pcall` is the one place a JS exception stands in for a longjmp, and a BrightScript port can use `try`/`catch` the same way).
+- Replace the `switch` with a function table or an `if` ladder ordered by frequency; the cases are short and independent.
+- The register file is one array and a frame is a record of indices, so a port can keep the frame stack in parallel arrays.
+- `LuaTable.advance` returns a position and leaves the entry in two fields to avoid allocating per step; a port with cheap tuples can return the pair.

package/script/luau/vm/vm.js

@@ -0,0 +1,167 @@
+/**
+ * The VM state: one value stack shared by every call, a stack of call
+ * frames, the open upvalues, and the globals. `call` runs a Lua or native
+ * function from the host (or from a native function) and returns its results
+ * as an array; the interpreter loop is in `vm.run.js`.
+ */
+
+/** @import { Frame } from './vm.run.js' */
+
+import { enter, execute } from './vm.run.js'
+import { metamethod, tostring } from './vm.meta.js'
+import { LuaClosure, LuaTable, NativeFunction, Upvalue, fail, newId, typeName } from './vm.value.js'
+
+/** Nested native-to-Lua calls allowed before "C stack overflow" */
+const MAX_NATIVE_DEPTH = 200
+
+export class VM {
+  /** @param {{ print?: (text: string) => void, chunk?: string }} [options] */
+  constructor(options) {
+    const o = options || {}
+    /** The value stack: every frame's registers, one after another */
+    this.stack = /** @type {any[]} */ ([])
+    for (let i = 0; i < 1024; i++) this.stack.push(undefined)
+    /** First free stack index above the running frame's registers */
+    this.sp = 0
+    /** @type {Frame[]} */
+    this.frames = []
+    /** @type {Upvalue[]} open upvalues, by ascending stack index */
+    this.openUpvals = []
+    this.nativeDepth = 0
+    this.globals = new LuaTable()
+    /** @type {LuaTable | undefined} */
+    this.stringMeta = undefined
+    /** @type {LuaTable | undefined} */
+    this.vectorMeta = undefined
+    /** `ipairs` and `pairs` iterate with these; FORGPREP recognises them */
+    this.inext = /** @type {NativeFunction | null} */ (null)
+    this.next = /** @type {NativeFunction | null} */ (null)
+    /** Where `print` writes */
+    this.print = o.print || function () {}
+    this.chunk = o.chunk || '?'
+  }
+
+  /** @returns {number} */
+  newId() {
+    return newId()
+  }
+
+  /**
+   * Makes the main closure of a loaded module, running in this VM's globals.
+   *
+   * @param   {import('../load/load.js').Module} module
+   * @returns {LuaClosure}
+   */
+  instantiate(module) {
+    return new LuaClosure(module.main, [], this.globals)
+  }
+
+  /**
+   * Calls any callable value.
+   *
+   * @param   {any}   fn
+   * @param   {any[]} args
+   * @returns {any[]} the results
+   */
+  call(fn, args) {
+    if (fn instanceof NativeFunction) {
+      if (this.nativeDepth >= MAX_NATIVE_DEPTH) throw fail('C stack overflow')
+      this.nativeDepth++
+      try {
+        const res = fn.fn(this, args)
+        return Array.isArray(res) ? res : [ res ]
+      } finally {
+        this.nativeDepth--
+      }
+    }
+    if (!(fn instanceof LuaClosure)) {
+      const handler = metamethod(this, fn, '__call')
+      if (handler === undefined) throw fail('attempt to call a ' + typeName(fn) + ' value')
+      return this.call(handler, [ fn ].concat(args))
+    }
+    if (this.nativeDepth >= MAX_NATIVE_DEPTH) throw fail('C stack overflow')
+    const stack = this.stack
+    const ra = this.sp
+    const savedSp = this.sp
+    const depth = this.frames.length
+    while (stack.length < ra + args.length + 2) stack.push(undefined)
+    stack[ra] = fn
+    for (let i = 0; i < args.length; i++) stack[ra + 1 + i] = args[i]
+    this.nativeDepth++
+    try {
+      const frame = enter(this, fn, ra, args.length, -1)
+      frame.entry = true
+      return execute(this)
+    } catch (e) {
+      this.unwind(depth, ra)
+      throw e
+    } finally {
+      this.nativeDepth--
+      this.sp = savedSp
+    }
+  }
+
+  /**
+   * Drops the frames above `depth` and closes the upvalues from `from` up,
+   * after an error.
+   *
+   * @param {number} depth
+   * @param {number} from
+   */
+  unwind(depth, from) {
+    this.frames.length = depth
+    this.closeUpvals(from)
+  }
+
+  /**
+   * The upvalue that captures stack slot `index`, shared by every closure that captures it.
+   *
+   * @param   {number} index
+   * @returns {Upvalue}
+   */
+  findUpvalue(index) {
+    const list = this.openUpvals
+    let i = list.length
+    while (i > 0 && list[i - 1].i >= index) {
+      if (list[i - 1].i === index) return list[i - 1]
+      i--
+    }
+    const uv = new Upvalue(this.stack, index)
+    list.splice(i, 0, uv)
+    return uv
+  }
+
+  /**
+   * Closes the open upvalues at stack slot `from` and above: they keep their value from here on.
+   *
+   * @param {number} from
+   */
+  closeUpvals(from) {
+    const list = this.openUpvals
+    while (list.length > 0 && list[list.length - 1].i >= from) {
+      const uv = /** @type {Upvalue} */ (list.pop())
+      uv.v = this.stack[uv.i]
+      uv.s = null
+    }
+  }
+
+  // Convenience
+  // ■■■■■■■■■■■
+
+  /**
+   * @param   {any} v
+   * @returns {string} Lua's `tostring` of v
+   */
+  tostring(v) {
+    return tostring(this, v)
+  }
+
+  /**
+   * @param   {string}     name
+   * @param   {(vm: VM, args: any[]) => any} fn
+   * @returns {NativeFunction}
+   */
+  native(name, fn) {
+    return new NativeFunction(name, fn)
+  }
+}