@poe-platform/safe-js 0.1.719 → 0.1.721

package/README.md

@@ -88,6 +88,10 @@ const result = await run(`
 Builtin prototypes retain their originating Object prototype when inspected
 from another realm, including when a budget is reused. Checkpoints preserve
 constructor/prototype identity and their supported property mutations.
+Persistent realms can use `budget.forkRealm()` to keep separate globals and
+intrinsic caches while sharing step, call-depth and retained-data limits. A fork
+preserves consumed allowances, including when a sibling closes. Each budget view
+supports one live realm; suspended invocation data remains charged until released.
 Map and Set instances also retain their selected prototype during inspection
 from another realm.
 Mixed-realm intrinsic checkpoints preserve separate constructor/prototype
@@ -218,8 +222,14 @@ This prints `2`. Evaluations share declarations, closures and object identity wi
 | `grants` | Granted capability names; `[]`. Every requested capability must be granted before any extension setup runs. |
 | `builtinOverrides` | Optional `{ console: "extension-name" }` authorizes that registered extension to replace only the builtin console. It must declare `console` and export a host object created in the realm. No overrides by default. |
 | `limits` | Positive integer caps: `extensions: 32`, `hostObjects: 1024`, `callbacks: 1024`, `guestReferences: 1024`, `cleanups: 1024`, `nestedEvaluations: 16`. Collection budgets also apply. |
+| `classicScripts` | Optional boolean, default `false`. Evaluations use classic Script grammar with persistent globals: top-level `this` is the intrinsic global object, `var` and functions create global properties, and `let`/`const` remain lexical. Injected capabilities stay immutable lexical bindings. Explicit source modules retain module semantics. |
 
-Ordinary host arguments/results are still copied. To preserve live native identity, explicitly create a host object. A guest function crossing to the host becomes an opaque callback: invoke it with `realm.invokeCallback(callback, { thisValue?, args? })`, then `realm.releaseCallback(callback)` when no longer needed. Callbacks and live objects cannot cross realms or survive close. For deferred arguments that must preserve guest identity, opt into retained references as described below.
+Classic Scripts reject top-level return, await and static imports/exports. This
+option preserves declaration history across evaluations and checkpoints; browser
+window aliases and callback scheduling belong to the host. Source-resolved dynamic
+imports from classic Scripts require separate support.
+
+Ordinary host arguments/results are still copied. To preserve live native identity, explicitly create a host object. A guest function crossing to the host becomes an opaque callback: invoke it with `realm.invokeCallback(callback, { thisValue?, args? })`, then `realm.releaseCallback(callback)` when no longer needed. Inside a declared and granted `context.nestedOperation`, await `context.invokeCallback` to settle the full guest result, including nested host calls and returned promises. Callbacks and live objects cannot cross realms or survive close. For deferred arguments that must preserve guest identity, opt into retained references as described below.
 
 Need synchronous effects without waiting for an async callback's tail? Use `realm.startCallback(callback, options)` or `context.startCallback(callback, options)`. The frozen `CallbackInvocation` exposes two promises: await `synchronous` when the guest function returns or its async body reaches its first `await`; await `result` for the final value. Interpreter implementation awaits and budget work do not complete the prefix. Ordinary throws reject both promises; nonfatal async-function errors reject only `result`, even before the first `await`. Close, abort and fatal errors reject still-pending handles without changing a completed prefix. The same callback limits, identity and reentry rules apply; no extra grant is required. Calls started outside a host operation are queued in invocation order. Browser event/default-action policy remains the host's responsibility.
 
@@ -288,6 +298,7 @@ Supply your own bounded `journal`; this does not add browser console behavior. W
 | `onCleanup(fn)` | Register a sync/async disposer. Cleanup runs in reverse order, awaits every disposer, and reports failures without skipping the rest. |
 | `chargeWork(units = 1)` | Charge a nonnegative integer against the shared execution budget. Fatal exhaustion cannot be swallowed to continue execution. |
 | `createHostObject({ properties?, methods?, indexed?, named? })` | Create a realm-owned capability. Properties declare synchronous `get`/`set` functions; methods are host functions. Optional `indexed` and `named` expose bounded live members. Undeclared members expose no native prototype. |
+| `createArrayBufferReference(buffer)` | Create an opaque live reference to a fixed, attached, plain ArrayBuffer without own metadata. Requires declared and granted `array-buffer:share`; full buffer bytes count against array/data budgets and `limits.guestReferences`. |
 | `invokeCallback(callback, { thisValue?, args? })` | Invoke a captured guest function with the realm's state, cancellation and budgets. Same operation as on the realm. |
 | `startCallback(callback, { thisValue?, args? })` | Return separate `synchronous` and `result` promises for the same realm-owned invocation. Also available on the realm. |
 | `releaseCallback(callback)` | Revoke the callback and release its retained guest state. |
@@ -298,6 +309,8 @@ Supply your own bounded `journal`; this does not add browser console behavior. W
 
 For a timer-shaped `schedule(callback, delay, ...args)`, register `context.retainGuestArguments(schedule, 2)`. The host receives normal callback/delay values and opaque `GuestReference` handles for the remaining arguments. Pass those handles to `context.invokeCallback(callback, { args })` to recover the original guest objects and observe mutations made after scheduling. References also work as callback receivers and host return values, including cycles, closures, primitives and live host objects.
 
+For a trusted native buffer such as WebAssembly memory, use `context.createArrayBufferReference(buffer)` and return the handle from a host property or operation. Guest ArrayBuffer views then share its bytes with the host, preserving identity and bidirectional writes. Ordinary host buffers still copy. Shared, resizable, detached, subclassed and proxy buffers reject, as do buffers with own properties or symbols. After native memory growth detaches the old buffer, create a new reference to the new buffer; the old reference continues to denote the detached buffer.
+
 Release each reference when the host no longer needs it; returning it does not release it. Retained graphs count against data budgets and `limits.guestReferences`. Synchronous native failure releases references captured for that call; asynchronous operations must release theirs in host cleanup. Close revokes all remaining references. Handles cannot be inspected, used in another realm, or serialized into replay/error data. Unmarked operations still copy values.
 
 For a live collection, keep the elements in your adapter and expose virtual indices instead of declaring one getter per element:
@@ -426,7 +439,7 @@ Compiling stored module source enforces the owning budget's string-length
 limit and charges one step per UTF-16 source unit before parsing. Regex
 compilation retains its additional work charges.
 
-`deepCopyToSandbox(value)` and `deepCopyFromSandbox(value, { wrapClosure? })` convert supported values. `wrapClosure` lets the host choose how to represent an exported sandbox function. Not every native JavaScript object is convertible.
+`deepCopyToSandbox(value)` and `deepCopyFromSandbox(value, { wrapClosure? })` convert supported values. `wrapClosure` lets the host choose how to represent an exported sandbox function. Not every native JavaScript object is convertible. When passing sandbox typed arrays to native APIs, use `deepCopyFromSandbox`: SDK-created views use internal wrappers and do not satisfy the host's native `ArrayBuffer.isView` check. Guest reflection and `ArrayBuffer.isView` retain their normal behavior.
 
 Native Promise imports accept genuine promises from other JavaScript realms,
 preserving aliases and copying fulfillment or rejection values. Own string-keyed

package/dist/safe-js/chunks/{chunk-APKV5Y6T.js → chunk-4CX3HYRY.js}

@@ -1,6 +1,6 @@
 import {
   isSandboxClosure
-} from "./chunk-KP6I45ET.js";
+} from "./chunk-DNA7BMBY.js";
 
 // packages/safe-js/src/lint/runtime-modules.ts
 var AsyncFunction = (async () => void 0).constructor;
@@ -34,4 +34,4 @@ function isAsyncRuntimeExport(value) {
 export {
   createLintModulesFromRuntimeRegistry
 };
-//# sourceMappingURL=chunk-APKV5Y6T.js.map
+//# sourceMappingURL=chunk-4CX3HYRY.js.map

package/dist/safe-js/chunks/{chunk-NJM2Q74Z.js → chunk-A4L72WXV.js}

@@ -1,7 +1,7 @@
 import {
   hashSource,
   validateSnapshotMigration
-} from "./chunk-U6KZ2DQ2.js";
+} from "./chunk-GMPZBMPA.js";
 import {
   SnapshotValidationError,
   assertSnapshotInactive,
@@ -14,12 +14,12 @@ import {
   validateGuestFunctionAst,
   validateRuntimeSnapshotDescriptors,
   validateTemplateObjects
-} from "./chunk-KP6I45ET.js";
+} from "./chunk-DNA7BMBY.js";
 import {
   ParseError,
   parseModule,
   replaceErrorStack
-} from "./chunk-IDQ67DY2.js";
+} from "./chunk-ILYJBA2D.js";
 
 // packages/safe-js/src/restore.ts
 var SnapshotMismatchError = class extends Error {
@@ -112,4 +112,4 @@ export {
   SnapshotMismatchError,
   restore
 };
-//# sourceMappingURL=chunk-NJM2Q74Z.js.map
+//# sourceMappingURL=chunk-A4L72WXV.js.map

package/dist/safe-js/chunks/{chunk-B2SQLK4O.js → chunk-B4M6QVUV.js}

@@ -8,7 +8,7 @@ import {
   numericTypedArrayConstructors,
   parseModule,
   tokenize
-} from "./chunk-IDQ67DY2.js";
+} from "./chunk-ILYJBA2D.js";
 
 // packages/safe-js/src/lint/rules/AS001.ts
 function AS001(source, options = {}) {
@@ -11176,4 +11176,4 @@ function hasOnlyRegexLiteralDiagnostics(diagnostics) {
 export {
   lint
 };
-//# sourceMappingURL=chunk-B2SQLK4O.js.map
+//# sourceMappingURL=chunk-B4M6QVUV.js.map

package/dist/safe-js/chunks/{chunk-A7CADQAD.js → chunk-BEXRQET4.js}

@@ -1,10 +1,10 @@
 import {
   SnapshotNotReadyError,
   serializeSafeJSSnapshot
-} from "./chunk-KP6I45ET.js";
+} from "./chunk-DNA7BMBY.js";
 import {
   SandboxError
-} from "./chunk-IDQ67DY2.js";
+} from "./chunk-ILYJBA2D.js";
 
 // packages/safe-js/src/snapshot/dump.ts
 var RUN_DUMP_CONTROLLER = /* @__PURE__ */ Symbol("SafeJS.run-dump-controller");
@@ -195,4 +195,4 @@ export {
   dumpCurrent,
   serializeRunSnapshot
 };
-//# sourceMappingURL=chunk-A7CADQAD.js.map
+//# sourceMappingURL=chunk-BEXRQET4.js.map

package/dist/safe-js/chunks/{chunk-OP3H3ZDN.js → chunk-BHYBD6SY.js}

@@ -4,7 +4,7 @@ import {
 import {
   accessDeniedSystemError,
   declareHostOperation
-} from "./chunk-KP6I45ET.js";
+} from "./chunk-DNA7BMBY.js";
 
 // packages/safe-js/src/modules/fs.ts
 import { constants as nodeFsConstants } from "node:fs";
@@ -671,4 +671,4 @@ export {
   FS_OPTION_SURFACE,
   makeFsModule
 };
-//# sourceMappingURL=chunk-OP3H3ZDN.js.map
+//# sourceMappingURL=chunk-BHYBD6SY.js.map