# Native Modules & Bundling (JS Runtime Contract)

**Audience**: runtime/embedding owners, native module authors, and app/bundler authors.

**Purpose**: keep runtime behavior predictable by defining (1) what exists at runtime and (2) what bundling must produce. Module-loader complexity lives in tooling.

## Key Decisions

- The runtime executes **one entry script** (or a `.rong` bytecode artifact).
- The runtime does **not** implement an ES module loader or Node.js CommonJS. There is no runtime contract for `import`, `import()`, or `require`.
- Native/platform APIs live under `globalThis.Rong` (and optionally a few Web-style globals).

## Runtime Contract

- `globalThis.Rong` is always present.
- The embedder may install Web-style globals (e.g. `fetch`, `URL`, `ReadableStream`, `AbortController`, timers, `console`).
- Capability discovery is recommended: `Rong.capabilities()` / `Rong.has(name)`.

## Native Module Contract (Rust)

Every native module exposes:

```rust
pub fn init(ctx: &JSContext) -> JSResult<()>;
```

It registers classes/functions/properties into:
- `ctx.global()` (Web-style globals), and/or
- `ctx.rong()` (the `Rong` namespace).

The embedder decides what modules to install (e.g. `rong_modules::init(&ctx)`).

## Bundling Contract (JS)

Bundles must be a plain script (IIFE / `async` IIFE) and must not depend on:
- runtime `import`/`export` resolution
- runtime code-splitting (`import()`)
- `require`, `module`, `exports`
- `node_modules` / filesystem module resolution

Bundles may rely on:
- `globalThis.Rong`
- any globals installed by the embedder/module set

## `.rong` Bytecode Artifact (Optional)

- Produced by `rong compile <input.js> <output.rong>`.
- Engine-specific (QuickJS vs JavaScriptCore); portability is not guaranteed.

Prefer JS bundles for portability; use `.rong` as an optimization.

## FAQ

- Do we implement `require`? No. Tooling bundles code into a single script. If a product wants a `require`-like API, it should be a userland shim (not part of the runtime contract).
