@markii/lua 0.17.0-next.0 → 0.17.0-next.2

package/dist/globals.d.ts

@@ -6,23 +6,37 @@ export declare const DENIED_GLOBALS: readonly string[];
 export interface CreateEmptyLuaEngineOptions {
     /**
      * Forwarded verbatim as wasmoon's `LuaFactory` first constructor argument
-     * (`customWasmUri` — confirmed against `node_modules/wasmoon/dist/
-     * factory.d.ts`). Left `undefined` (the default), `LuaFactory` keeps its
-     * own built-in resolution: the local `node_modules/wasmoon/dist/glue.wasm`
-     * file in Node (used by this package's own Vitest suite), or — in a
-     * browser bundle with no bundler-provided URL — a fetch to
-     * `https://unpkg.com/wasmoon@<version>/dist/glue.wasm` at runtime
-     * (confirmed in `node_modules/wasmoon/dist/index.js`). That CDN fetch is
-     * exactly what makes an unconfigured browser host non-offline-capable: no
-     * network to unpkg means no script can ever run. A host that wants to
-     * avoid it (e.g. the playground, via a Vite `?url` asset import so the
-     * wasm ships in its own bundle) passes its own local URL here instead.
-     * Passing `undefined` is IDENTICAL to omitting this options object
-     * entirely — this parameter only ever narrows behavior, never changes it
-     * by default.
+     * (`customWasmUri`). In Node, leaving it `undefined` keeps wasmoon's own
+     * resolution of the local `node_modules/wasmoon/dist/glue.wasm`. Outside
+     * Node it is REQUIRED: wasmoon's browser default is a runtime fetch from
+     * `https://unpkg.com/...`, and this package never lets that happen
+     * silently. With no `wasmUri` outside Node, engine creation throws a
+     * `MissingWasmUriError` before wasmoon is touched (`runScript` turns it
+     * into a labeled `runtime` failure). A browser host ships its own copy of
+     * `glue.wasm` (for example via a bundler `?url` import) and passes that
+     * URL here.
      */
     wasmUri?: string;
+    /**
+     * Test seam: overrides the Node detection (`isNodeEnvironment`). Leave
+     * unset in production.
+     */
+    isNode?: boolean;
+}
+/** Message shared by the thrown error and the `runScript` failure. */
+export declare const MISSING_WASM_URI_MESSAGE = "the Lua engine needs its WebAssembly file but this host did not pass `wasmUri`; the host must pass `wasmUri` (a URL to wasmoon glue.wasm) when running outside Node";
+/** Thrown by `createEmptyLuaEngine` when no `wasmUri` is given outside Node. */
+export declare class MissingWasmUriError extends Error {
+    constructor();
 }
+/**
+ * True only when running under Node. Guarded so a browser, worker, or any
+ * other environment without a real `process.versions.node` counts as "not
+ * Node".
+ */
+export declare function isNodeEnvironment(): boolean;
+/** True when a run with these options must be refused for want of `wasmUri`. */
+export declare function needsWasmUri(options?: CreateEmptyLuaEngineOptions): boolean;
 /**
  * Creates a fresh wasmoon engine with the curated, empty environment
  * described above. `traceAllocations: true` is required for the memory cap

package/dist/globals.js

@@ -280,6 +280,36 @@ export const DENIED_GLOBALS = [
     '_G',
     '_VERSION',
 ];
+/** Message shared by the thrown error and the `runScript` failure. */
+export const MISSING_WASM_URI_MESSAGE = 'the Lua engine needs its WebAssembly file but this host did not pass `wasmUri`; the host must pass `wasmUri` (a URL to wasmoon glue.wasm) when running outside Node';
+/** Thrown by `createEmptyLuaEngine` when no `wasmUri` is given outside Node. */
+export class MissingWasmUriError extends Error {
+    constructor() {
+        super(MISSING_WASM_URI_MESSAGE);
+        this.name = 'MissingWasmUriError';
+    }
+}
+/**
+ * True only when running under Node. Guarded so a browser, worker, or any
+ * other environment without a real `process.versions.node` counts as "not
+ * Node".
+ */
+export function isNodeEnvironment() {
+    try {
+        const proc = globalThis
+            .process;
+        return typeof proc?.versions?.node === 'string';
+    }
+    catch {
+        return false;
+    }
+}
+/** True when a run with these options must be refused for want of `wasmUri`. */
+export function needsWasmUri(options) {
+    if (options?.wasmUri !== undefined)
+        return false;
+    return !(options?.isNode ?? isNodeEnvironment());
+}
 /**
  * Creates a fresh wasmoon engine with the curated, empty environment
  * described above. `traceAllocations: true` is required for the memory cap
@@ -297,6 +327,8 @@ export const DENIED_GLOBALS = [
  * the only supported way to execute a note's script.
  */
 export async function createEmptyLuaEngine(options) {
+    if (needsWasmUri(options))
+        throw new MissingWasmUriError();
     const factory = new LuaFactory(options?.wasmUri);
     const engine = await factory.createEngine({
         openStandardLibs: false,

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export type { ScriptFailure, ScriptLimitKind, ScriptMarshalReason, } from './errors.js';
 export { CAPABILITY_ERROR_TAG, FETCH_DECODE_ERROR_TAG, MARSHAL_ERROR_TAG, ScriptLimitError, } from './errors.js';
 export type { CreateEmptyLuaEngineOptions } from './globals.js';
-export { ALLOWED_GLOBALS, DENIED_GLOBALS, createEmptyLuaEngine, } from './globals.js';
+export { ALLOWED_GLOBALS, DENIED_GLOBALS, MISSING_WASM_URI_MESSAGE, MissingWasmUriError, createEmptyLuaEngine, isNodeEnvironment, } from './globals.js';
 export type { LimitHandle, ScriptLimits } from './limits.js';
 export { DEFAULT_LIMITS, installLimits } from './limits.js';
 export type { CacheEntry, CacheProvider, CapabilityConfig, CapabilityDenial, CapabilityDenials, CapabilityTier, NetGrants, NetProvider, NetResponse, } from './capabilities.js';

package/dist/index.js

@@ -4,7 +4,7 @@
 // import rule and the ESLint guard in the root config. May depend on
 // @markii/bundle for the `ScriptView` capability type only.
 export { CAPABILITY_ERROR_TAG, FETCH_DECODE_ERROR_TAG, MARSHAL_ERROR_TAG, ScriptLimitError, } from './errors.js';
-export { ALLOWED_GLOBALS, DENIED_GLOBALS, createEmptyLuaEngine, } from './globals.js';
+export { ALLOWED_GLOBALS, DENIED_GLOBALS, MISSING_WASM_URI_MESSAGE, MissingWasmUriError, createEmptyLuaEngine, isNodeEnvironment, } from './globals.js';
 export { DEFAULT_LIMITS, installLimits } from './limits.js';
 export { DEFAULT_MAX_FETCH_BYTES, bytesToLuaString, buildCapabilities, isNetProviderDenial, luaStringToBytes, netProviderDenial, } from './capabilities.js';
 export { buildDoc } from './doc.js';

package/dist/require.d.ts

@@ -86,12 +86,12 @@ import type { ScriptView } from '@markii/bundle';
  * `./limits`' out-of-band JS flag regardless of what any Lua-level
  * `pcall` around it reports.
  */
-/** A pack-namespaced `require "packName/modulePath"` resolver, injected by a host that has actually wired up pack installation. Returns pure Lua SOURCE TEXT, or `undefined` if this pack/module isn't available — never throws for a routine "not found". */
-export type PackModuleResolver = (packName: string, modulePath: string) => string | undefined;
+/** A pack-namespaced `require "packName/modulePath"` resolver, injected by a host that has actually wired up pack installation. Returns pure Lua SOURCE TEXT, or `undefined` if this pack/module isn't available — never throws for a routine "not found". May be synchronous or return a promise; a rejection fails the require like a sync throw, and a promise that never settles is bounded by the run's wall-clock guard. */
+export type PackModuleResolver = (packName: string, modulePath: string) => string | undefined | Promise<string | undefined>;
 export interface RequireConfig {
     /** The SAME `ScriptView` `./capabilities` wires up for `bundle.read`/`bundle.write` — reused, never re-implemented, so bundle-local `require` is subject to the identical path-jail and read-permission check. */
     bundle?: ScriptView;
-    /** Optional pack-module seam — see the module doc comment. Absent (the current default: no host wires packs yet) means every pack-namespaced `require` fails as a clean capability denial. */
+    /** Optional pack-module seam — see the module doc comment. Absent (a host that has not wired pack modules) means every pack-namespaced `require` fails as a clean capability denial. */
     packModuleResolver?: PackModuleResolver;
     /**
      * Records a genuine denial onto the SAME per-run `CapabilityDenials`

package/dist/require.js

@@ -96,7 +96,7 @@ export function buildRequire(config) {
             const segIdx = name.indexOf('/');
             const packName = segIdx === -1 ? name : name.slice(0, segIdx);
             const modulePath = segIdx === -1 ? '' : name.slice(segIdx + 1);
-            const resolved = resolver(packName, modulePath);
+            const resolved = await resolver(packName, modulePath);
             if (resolved === undefined) {
                 throw new Error(`require: no pack module "${modulePath}" in pack "${packName}"`);
             }

package/dist/sandbox.d.ts

@@ -28,16 +28,15 @@ export interface RunScriptOptions {
     limits?: Partial<ScriptLimits>;
     marshalLimits?: Partial<MarshalLimits>;
     /**
-     * Forwarded to `./globals`' `createEmptyLuaEngine` as its
-     * `wasmUri` option (wasmoon's `customWasmUri`). Left `undefined` (the
-     * default), engine creation is byte-for-byte the same as before this
-     * option existed: local `node_modules` resolution in Node, the unpkg CDN
-     * default in an unconfigured browser bundle. A host that bundles its own
-     * copy of wasmoon's `glue.wasm` (e.g. the playground, to avoid a runtime
-     * dependency on the unpkg CDN) passes that local URL here instead — see
-     * `createEmptyLuaEngine`'s doc comment for the full rationale.
+     * Forwarded to `./globals`' `createEmptyLuaEngine` as its `wasmUri`
+     * option (wasmoon's `customWasmUri`). In Node it may be omitted (local
+     * `node_modules` resolution). Outside Node it is required: a run without
+     * it fails before any engine is created, as a `runtime` failure saying
+     * the host must pass `wasmUri`. There is no silent CDN fetch.
      */
     wasmUri?: string;
+    /** Test seam: overrides the Node detection. Leave unset in production. */
+    isNode?: boolean;
 }
 export type RunScriptResult = {
     ok: true;

package/dist/sandbox.js

@@ -2,7 +2,7 @@ import { LuaReturn } from 'wasmoon';
 import { buildCapabilities, DEFAULT_MAX_FETCH_BYTES, } from './capabilities.js';
 import { buildDoc } from './doc.js';
 import { MARSHAL_ERROR_TAG, ScriptLimitError } from './errors.js';
-import { createEmptyLuaEngine } from './globals.js';
+import { createEmptyLuaEngine, MISSING_WASM_URI_MESSAGE, needsWasmUri, } from './globals.js';
 import { buildJsonTable } from './json-table.js';
 import { DEFAULT_LIMITS, installLimits } from './limits.js';
 import { buildMarshalPrelude, DEFAULT_MARSHAL_LIMITS, finalizeMarshaledValue, wrapUserCode, } from './marshal.js';
@@ -224,7 +224,14 @@ export async function runScript(options) {
         ...DEFAULT_MARSHAL_LIMITS,
         ...options.marshalLimits,
     };
-    const engine = await createEmptyLuaEngine({ wasmUri: options.wasmUri });
+    const engineOptions = { wasmUri: options.wasmUri, isNode: options.isNode };
+    if (needsWasmUri(engineOptions)) {
+        return {
+            ok: false,
+            error: { kind: 'runtime', message: MISSING_WASM_URI_MESSAGE },
+        };
+    }
+    const engine = await createEmptyLuaEngine(engineOptions);
     engine.global.setMemoryMax(limits.maxMemoryBytes);
     let thread;
     let threadStackIndex;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markii/lua",
-  "version": "0.17.0-next.0",
+  "version": "0.17.0-next.2",
   "description": "Sandboxed Lua 5.4 (wasmoon) execution runtime for Mark's document scripting: an empty-env global whitelist, two-tier capability-gated net/cache/bundle access, instruction-count/wall-clock/memory limits, and depth/size-capped Lua<->JS marshaling.",
   "keywords": [
     "markdown",
@@ -44,8 +44,8 @@
     "lint": "eslint ."
   },
   "dependencies": {
-    "@markii/bundle": "^0.17.0-next.0",
-    "@markii/runtime": "^0.17.0-next.0",
+    "@markii/bundle": "^0.17.0-next.2",
+    "@markii/runtime": "^0.17.0-next.2",
     "wasmoon": "^1.16.0"
   }
 }