@poe-platform/safe-js 0.1.35 → 0.1.36

package/README.md

@@ -172,6 +172,8 @@ This prints `2`. Evaluations share declarations, closures and object identity wi
 
 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.
 
+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.
+
 <details>
 <summary>Trusted extensions and live host objects</summary>
 
@@ -214,6 +216,7 @@ The manifest requires `version: 1` and a nonempty `name`. Optional `capabilities
 | `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. |
 | `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. |
 | `retainGuestArguments(operation, from)` | During setup, opt an operation into opaque argument references starting at the zero-based index `from`. Requires declared and granted `guest:retain`. Earlier arguments keep normal conversion; live host methods preserve the declaration. |
 | `releaseGuestReference(reference)` | Revoke one reference and release its retained state. Also available on the realm. |

package/dist/safe-js/chunks/{chunk-D4J7UXVE.js → chunk-ARXBI427.js}

@@ -27,7 +27,7 @@ import {
   validateMigrationSemantics,
   validateSnapshotData,
   validateSnapshotMigration
-} from "./chunk-MO3YD4ID.js";
+} from "./chunk-LBJGHXII.js";
 
 // packages/safe-js/src/migrate.ts
 import { createHash } from "node:crypto";
@@ -8245,4 +8245,4 @@ export {
   parseMcpConfig,
   makeMcpModule
 };
-//# sourceMappingURL=chunk-D4J7UXVE.js.map
+//# sourceMappingURL=chunk-ARXBI427.js.map

package/dist/safe-js/chunks/{chunk-MO3YD4ID.js → chunk-LBJGHXII.js}

@@ -28648,7 +28648,7 @@ function wrapCallerInjectedFunction(name, value, options, state) {
               throw error;
             }
             if (options.realm.awaitResult(callable)) {
-              return Promise.resolve(result).then((value2) => copyHostResultToSandbox(value2, stackFrames, options));
+              return wrapHostPromiseWithSignal(Promise.resolve(result), options.signal).then((value2) => copyHostResultToSandbox(value2, stackFrames, options));
             }
             return copyHostResultToSandbox(result, stackFrames, options);
           }
@@ -29158,6 +29158,7 @@ function wrapHostPromiseWithSignal(promise, signal) {
     return promise;
   }
   if (signal.aborted) {
+    void promise.catch(() => void 0);
     return Promise.reject(readAbortReason2(signal));
   }
   return new Promise((resolve, reject) => {
@@ -31135,7 +31136,20 @@ var RealmState = class {
         this.compilation
       );
   };
-  invokeCallback = async (callback, options = {}) => {
+  startCallback = (callback, options = {}) => {
+    let complete;
+    let fail2;
+    const synchronous = new Promise((resolve, reject) => {
+      complete = resolve;
+      fail2 = reject;
+    });
+    const result = this.executeCallback(callback, options, complete);
+    void result.catch(fail2);
+    void synchronous.catch(() => void 0);
+    return Object.freeze({ synchronous, result });
+  };
+  invokeCallback = this.executeCallback.bind(this);
+  async executeCallback(callback, options = {}, completeSynchronous) {
     if (this.closed || this.failure !== void 0) await this.dispose();
     this.assertOpen();
     const closure = readGuestCallback(callback, this);
@@ -31157,9 +31171,13 @@ var RealmState = class {
           compilation: this.compilation,
           stack: []
         });
-        const settled = await suspendJob(
-          awaitSandboxValue(value, this.controller.signal, this.budget)
-        );
+        const settlement = awaitSandboxValue(value, this.controller.signal, this.budget);
+        void settlement.catch(() => void 0);
+        if (isSandboxPromise(value) && value.synchronousPrefix !== void 0)
+          await value.synchronousPrefix;
+        this.assertOpen();
+        completeSynchronous?.();
+        const settled = await suspendJob(settlement);
         return this.exportValue(settled);
       } finally {
         leaveCall();
@@ -31167,20 +31185,18 @@ var RealmState = class {
       }
     };
     try {
-      if (this.active !== void 0) {
-        record2.promise = withSandboxPromiseRejectionTracker(
-          this.tracker,
-          () => runResources.run(
-            { signal: this.controller.signal, add: this.onCleanup },
-            () => withCancellationSignal(
-              this.controller.signal,
-              () => this.phase.getStore()?.active ? runAsyncPrefix(invoke) : this.queue.run(invoke)
-            )
+      const active = this.active !== void 0;
+      const pending = withSandboxPromiseRejectionTracker(
+        this.tracker,
+        () => runResources.run(
+          { signal: this.controller.signal, add: this.onCleanup },
+          () => withCancellationSignal(
+            this.controller.signal,
+            () => active && this.phase.getStore()?.active ? runAsyncPrefix(invoke) : this.queue.run(invoke)
           )
-        );
-      } else {
-        record2.promise = this.perform(() => this.queue.run(invoke));
-      }
+        )
+      );
+      record2.promise = active ? pending : this.perform(() => pending);
       return await record2.promise;
     } catch (error) {
       if (error instanceof SandboxError) this.poison(error);
@@ -31194,7 +31210,7 @@ var RealmState = class {
           this.compilation
         );
     }
-  };
+  }
   initialize() {
     if (this.initialized) return;
     this.assertOpen();
@@ -31205,6 +31221,7 @@ var RealmState = class {
         onCleanup: this.onCleanup,
         chargeWork: this.chargeWork,
         createHostObject: this.createHostObject,
+        startCallback: this.startCallback,
         invokeCallback: this.invokeCallback,
         releaseCallback: this.releaseCallback,
         releaseGuestReference: this.releaseGuestReference,
@@ -31476,6 +31493,7 @@ function createRealm(options = {}) {
   return Object.freeze({
     extensions: Object.freeze(state.extensions.map((extension) => extension.manifest)),
     evaluate: state.evaluate,
+    startCallback: state.startCallback,
     invokeCallback: state.invokeCallback,
     releaseCallback: state.releaseCallback,
     releaseGuestReference: state.releaseGuestReference,
@@ -32675,4 +32693,4 @@ export {
   FileSnapshotBackend,
   run
 };
-//# sourceMappingURL=chunk-MO3YD4ID.js.map
+//# sourceMappingURL=chunk-LBJGHXII.js.map