[datamoc]

Description

Why

The starting point was running a game campaign using Lua in the browser on top of Fengari. The first thing that failed was the bundle itself: Fengari called
require('os').platform() (src/luaconf.js), which a browser bundler cannot resolve, and consumers had to write a local shim.

Behind it was a list of things the game's Lua needs from its VM:

• synchronous Lua calls into game APIs, returning results;
• Lua callbacks and table references retaining their identity;
• dialogue coroutines that pause for player input and resume;
• loading the real Lua modules, with Lua 5.4 compatibility.

Upstream Fengari (v0.1.5) is Lua 5.3.4 with 32-bit integers, no <const> / <close>, no host-driven coroutines, and a luaconf.js that cannot be bundled without shims.

This PR closes those gaps. Securing the VM for untrusted content, and the migration tooling, came out of that work.

What each goal needed

Bundling for the browser (0.5.3)

• require('os').platform() is gone (process.platform). typeof process was tested in 13 places, so a bundler's process shim also made ldblib.js crash at load on an empty
  readline-sync stub. One module, src/isnode.js (process.versions.node), replaces them.
• package.json has a browser field mapping fs, os, path, tmp, child_process and readline-sync to empty modules. esbuild, webpack, Vite and Browserify bundle the
  package without shims or resolve.fallback. Verified with esbuild --platform=browser, with and without a process shim.

Synchronous calls into game APIs (0.4.0, 0.5.x)

• defineFunction(name, fn) registers a host function under a dotted path; Lua calls it synchronously and gets its return values (Multi for several).
• run, runMulti, call, callMulti and callRef call Lua and return results with value conversion in both directions (BigInt for 64-bit integers, Uint8Array
  strings, Map for exotic keys, 1..n tables as arrays, LuaFloat / preserveFloats).
• vm.protect(fn) runs a host callback in a Lua protected call, so Lua errors raised through the C API become LuaError / LimitError and the stack is restored.
  vm.throwLuaError builds the same error from a stack value.

Callbacks retaining their identity (0.4.0)

• Functions, threads and userdata come back as LuaRef, anchored in the Lua registry and released with release() or by garbage collection. The same Lua function is
  value when called back with callRef / LuaRef#call. A LuaRef from another VM is refused.
• Userdata carries opaque host values through Lua.
• Not covered: tables are converted to JavaScript values on read, not kept as references. Identity-preserving table references are not provided; a host that needs them must hold the table behind a Lua function or userdata.

Dialogue coroutines (0.4.0)

• vm.coroutine(path | LuaRef) and vm.coroutineFromSource(source) return a Coroutine with status, resume(...args) and close(). A host function returning new Yield([...]) suspends the calling coroutine; the resume arguments become the host function's return values. That is the shape of "pause for player input, resume when the player answers".
• Coroutine#close() runs pending <close> handlers and reports a failure.

Real Lua modules and Lua 5.4 (0.1.6 – 0.3.0)

• The baseline is now honest Lua 5.4.6 (LUA_VERSION_NUM 504). A "full Lua 5.5.1 compliance" claim had been added to the README (953794a) while the VM reports 5.4.6; it was removed (a0853cb).
• 64-bit integers (upstream: 32-bit) with fixes in the string, math and table libraries.
• <const> and <close> (0.2.0 advertised them but no such program compiled): attribute grammar (the 5.5 prefix form too), compile-time const checks, to-be-closed variables closed on block exit, break, goto, return and error, a new OP_TBC opcode, the closing value of generic for, coroutine.close, lua_closethread, lua_toclose, real lua_resetthread / lua_closeslot. Known limitation: a __close cannot yield.
• files (read / list) lets the host serve module files, and libs / remove choose the libraries a module can see.
• Per-state allocation hook (lua_setallocf) so memory can be bounded.

Security hardening

Campaign content is third-party Lua, so the VM had to be safe to run it.

• sandbox: true (base, coroutine, table, string, utf8, math only; no os, io, debug, package, require; dofile, loadfile, string.dump removed; text-only load; no host helper left as a global: __fs_read, __fs_list, __random).
• limits (instructions, wall-clock time, per-allocation and total allocation) per top-level call, with a LimitError the script cannot catch.
• A print option ('buffer', 'native', false) so a host that wants Lua's own print no longer re-opens libraries, which restored string.dump after the sandbox removed it.
• Hardening of the conversion layer: __proto__ keys cannot modify prototypes, conversion errors in host functions become Lua errors.

Bypasses of the limits found and fixed along the way (do not use 0.4.x to 0.5.3 for untrusted scripts with limits):

• the message handler of xpcall ran during the counting hook and could loop forever;
• native pattern matching (find, match, gmatch, gsub), table.move and plain-text find were not interruptible;
• huge allocations: new limits.allocation and limits.totalAllocation;
• sandbox exposed the host files through __fs_read / __fs_list;
• a limit overrun could be hidden by a script that caught the failure of a coroutine it created: every host entry point now fails with a LimitError whenever a limit was hit during the call;
• Coroutine#close() ran its handlers without a budget;
• a global path lookup (call, compile, coroutine) ran before the budget, so an __index on _G could loop forever or raise outside a protected call.

Limitations: other native functions whose cost depends only on argument size (default-comparator table.sort, table.concat, string.format) are not interrupted; bound limits.allocation / totalAllocation. limits only acts on the VM created here, so combine it with sandbox. compile is deliberately disabled while limits are active (documented in the README).

Tooling added on the way

• TypeScript declarations (src/fengari.d.ts, "types" in package.json) so a TypeScript host needs no @ts-expect-error or hand-written types; test/types.test.js checks them against the runtime exports.
• lua2js / FengariVm.toJs: translates Lua to readable JavaScript for code that eventually leaves Lua, with TODO(lua2js) markers for what it cannot translate faithfully, and an online demo (docs/lua2js). a or b keeps Lua's meaning (nullishOr opts in to ??). A Lua comment can no longer break out of the generated // comment (0.5.0 only).
• Optional numeric compilation (vm.compile) and a benchmark page comparing the interpreter, compiled Lua and JavaScript in the browser.

Testing

test/browser-compat.test.js (fails if the library requires a Node-only module on the browser path), test/lattribs.test.js (const/close), test/lalloc.test.js, test/fengari-vm.test.js, test/fengari-vm-limits.test.js (every bypass above), test/types.test.js, test/ltranspile.test.js, test/numeric-compiler.test.js. 837 passing, 21 skipped; lint clean. The browser bundle was also built with esbuild and run with and without a process shim. All 34 files of the official Lua 5.5 test suite translate with lua2js to syntactically valid JavaScript.

[giann]

I don't know about you @daurnimator , but I'm not going to even consider this vibe-coded PR.

[daurnimator]

I don't know about you @daurnimator , but I'm not going to even consider this vibe-coded PR.

Agreed. This does way too much for one PR in any case.

@datamoc start piecemeal and a PR should only solve one small problem at a time. We don't have an AI policy yet but you should be prepared to answer questions on why things were done a particular way without referring back to AI. i.e. you need to understand what your AI is suggesting at least as well as what you expect us to.