@poe-platform/safe-js 0.1.38 → 0.1.40

package/README.md

@@ -168,6 +168,7 @@ This prints `2`. Evaluations share declarations, closures and object identity wi
 | --- | --- |
 | `extensions` | Explicit `defineExtension(...)` registrations; `[]`. Setup runs once, on first evaluation, not on construction or unused close. |
 | `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. |
 
 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.
@@ -209,6 +210,30 @@ try {
 
 The manifest requires `version: 1` and a nonempty `name`. Optional `capabilities` and `globals` are name arrays; `modules` maps module names to export-name arrays. Synchronous `setup(context)` returns `{ globals?, modules? }` matching those declarations exactly. Module exports use the existing record/Map registry. Duplicate names, incompatible versions, missing grants and conflicts with intrinsics or caller values are rejected before setup. Accessor-based declarations and asynchronous factories are unsupported.
 
+**Sharing an owned console.** An extension can expose the same host object as `console`, `window.console` and `self.console`:
+
+```js
+const browser = defineExtension({
+  manifest: { version: 1, name: "browser", globals: ["console", "window", "self"] },
+  setup(context) {
+    const console = context.createHostObject({ methods: {
+      log: (...args) => journal.log(...args),
+      warn: (...args) => journal.warn(...args)
+    } });
+    const window = context.createHostObject({ properties: {
+      console: { get: () => console }
+    } });
+    return { globals: { console, window, self: window } };
+  }
+});
+const realm = createRealm({
+  extensions: [browser],
+  builtinOverrides: { console: "browser" }
+});
+```
+
+Supply your own bounded `journal`; this does not add browser console behavior. Without authorization, registration still fails before setup. Caller-provided console bindings, another extension claiming console, unknown override names and missing capability grants still reject. JSON and other intrinsics cannot be overridden this way. The replacement uses normal capability accounting and revocation; its calls do not also go to the builtin `sink`. Close the realm when finished, as in the example above.
+
 | Context member | Contract |
 | --- | --- |
 | `signal` | Realm cancellation signal; aborted on close or failure. |
@@ -303,7 +328,7 @@ For one-shot use, `run(source, { extensions, grants, ... })` accepts the same re
 | --- | --- |
 | `bindings` | Global input values and host functions; none by default. |
 | `modules` | Module names mapped to export records or Maps; none by default. |
-| `extensions`, `grants`, `limits` | Opt into a one-shot extension realm; see the supported options and lifetime rules above. |
+| `extensions`, `grants`, `builtinOverrides`, `limits` | Opt into a one-shot extension realm; see the supported options and lifetime rules above. |
 | `budget` | A `Budget` instance. Without one, only the default call-depth limit of 1,000 is configured. |
 | `signal` | Host `AbortSignal` for cancellation. |
 | `filename` | Diagnostic filename; defaults to `<input>`. |

package/dist/safe-js/chunks/{chunk-BW4SYRDC.js → chunk-CZNLD2Z3.js}

@@ -30844,6 +30844,14 @@ var RealmState = class {
     this.modules = readModules(options.modules);
     const grants = new Set(readStringList(options.grants ?? [], "Realm grants"));
     for (const extension of this.extensions) getExtensionSetup(extension);
+    const overrides = readDataRecord(options.builtinOverrides === void 0 ? {} : options.builtinOverrides, "Builtin overrides");
+    for (const [name, extensionName] of Object.entries(overrides)) {
+      if (name !== "console" || typeof extensionName !== "string" || extensionName.length === 0 || extensionName.length > 256)
+        throw new TypeError("Builtin overrides only supports console with a nonempty extension name.");
+      if (!this.extensions.some((extension) => extension.manifest.name === extensionName && extension.manifest.globals?.includes(name)))
+        throw new TypeError("Console override requires a registered extension declaring console.");
+      this.consoleExtension = extensionName;
+    }
     this.budget = options.budget ?? new Budget({ maxCallDepth: 1e3 });
     this.lease = this.budget.acquireCompileOwner(true);
     this.compilation = new CompileScope(this.lease.owner);
@@ -30864,7 +30872,10 @@ var RealmState = class {
         random: createReplayableRandom({ seed: options.randomSeed }).next
       });
       const names = /* @__PURE__ */ new Set();
-      const globals = /* @__PURE__ */ new Set([...Object.keys(this.builtinBindings), ...Object.keys(this.globals)]);
+      const globals = /* @__PURE__ */ new Set([
+        ...Object.keys(this.builtinBindings).filter((name) => name !== "console" || this.consoleExtension === void 0),
+        ...Object.keys(this.globals)
+      ]);
       const modules = new Map(
         Object.entries(this.modules).map(([name, exports]) => [name, new Set(Object.keys(exports))])
       );
@@ -30878,6 +30889,8 @@ var RealmState = class {
             throw new TypeError(`Missing grant '${capability}' for extension '${manifest.name}'.`);
         }
         for (const name of manifest.globals ?? []) {
+          if (name === "console" && this.consoleExtension !== void 0 && manifest.name !== this.consoleExtension)
+            throw new TypeError(`Conflicting global 'console': replacement is authorized only for '${this.consoleExtension}'.`);
           if (globals.has(name)) throw new TypeError(`Conflicting global '${name}'.`);
           globals.add(name);
         }
@@ -30912,6 +30925,7 @@ var RealmState = class {
   bridge;
   limits;
   extensions;
+  consoleExtension;
   cleanups = [];
   callbacks = /* @__PURE__ */ new Map();
   pendingCallbacks = /* @__PURE__ */ new Set();
@@ -31342,6 +31356,8 @@ var RealmState = class {
       );
       const modules = readModules(exports.modules);
       assertNames(Object.keys(globals), extension.manifest.globals ?? [], "global");
+      if (extension.manifest.name === this.consoleExtension && !this.hostObjects.has(globals.console))
+        throw new TypeError("Console replacement must be a host object created in this realm.");
       assertNames(Object.keys(modules), Object.keys(extension.manifest.modules ?? {}), "module");
       for (const [name, values] of Object.entries(modules)) {
         assertNames(Object.keys(values), extension.manifest.modules?.[name] ?? [], "module export");
@@ -31587,6 +31603,7 @@ function readRealmOptions(value, oneShot = false) {
     "bindings",
     "modules",
     "extensions",
+    "builtinOverrides",
     "grants",
     "budget",
     "signal",
@@ -32170,7 +32187,8 @@ var UnhandledRejectionError = class extends Error {
 };
 var DEFAULT_MAX_CALL_DEPTH = 1e3;
 function run(source, options = {}) {
-  if (options.extensions !== void 0) return runWithExtensions(source, options);
+  if (options.extensions !== void 0 || options.builtinOverrides !== void 0)
+    return runWithExtensions(source, options);
   const lifecycle = {
     hostCallbackDepth: 0,
     hostCallbackContext: new AsyncLocalStorage7()
@@ -32743,4 +32761,4 @@ export {
   FileSnapshotBackend,
   run
 };
-//# sourceMappingURL=chunk-BW4SYRDC.js.map
+//# sourceMappingURL=chunk-CZNLD2Z3.js.map