mrdocs::js

These functions abstract over the embedded JavaScript engine so that scripts and helpers can be bound, invoked, and marshalled without leaking engine‐specific types into the rest of the codebase.

## Implementation Notes (for Python/Lua integrations)

The current implementation uses JerryScript with the following design choices:

### Integer Limitations JerryScript only guarantees 32‐bit integer precision. Values outside the int32 range (approximately ±2 billion) are converted to strings when passed to JavaScript to avoid wraparound bugs. When reading values back, integers that fit in int64 are returned as integers; others remain as doubles.

### DOM ↔ JS Conversion Strategy ‐ Objects: Use lazy Proxy wrappers to avoid infinite recursion from circular references (e.g., Handlebars symbol contexts that reference parent symbols). Properties are converted on‐demand when accessed. ‐ Arrays: Converted eagerly (snapshot semantics) because they rarely contain circular references. This means JS mutations don't affect the original C++ array and vice versa. ‐ Functions: Wrapped bidirectionally so JS can call C++ functions and C++ can invoke JS functions through dom::Function.

### Thread Safety The Context mutex serializes all engine operations. Values can be safely copied across threads; the underlying handle operations are protected.

Created with MrDocs