Address remaining AI-reviewer concerns on PR #166

- `Console.cpp`: clear any pending N-API exception after the
  best-effort stack capture. N-API operations like `Object::Get` can
  leave a pending JS exception on `env` independently of throwing a
  C++ exception (e.g., a property accessor that throws). Without
  clearing, returning to the polyfill's wrapper function would surface
  the pending exception and `console.*` would itself throw on the JS
  side -- defeating the "side-effect free" contract.
- `Console.h`: document the lifetime of `CallbackT`'s `const
  char*` message (valid only for the duration of the callback; copy
  to retain). Strengthen the `CaptureCurrentJsStack` doc to
  explicitly state capture is best-effort, may return empty even from
  a valid JS context, and hosts must check before using.
- `Readme.md`: note that the helper is best-effort and may return
  empty.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: Copilot

Polyfills/Console/Include/Babylon/Polyfills/Console.h

@@ -17,6 +17,13 @@ namespace Babylon::Polyfills::Console
         Error,
     };
 
+    /**
+     * Callback invoked for each `console.log` / `console.warn` / `console.error` call.
+     *
+     * The `const char*` message is the formatted message produced by joining the call arguments
+     * (like browsers do). Its storage is only valid for the duration of the callback -- copy if
+     * you need to retain it. The `LogLevel` indicates which `console.*` method was invoked.
+     */
     using CallbackT = std::function<void BABYLON_API (const char*, LogLevel)>;
 
     void BABYLON_API Initialize(Napi::Env env, CallbackT callback);
@@ -29,8 +36,10 @@ namespace Babylon::Polyfills::Console
      * `console.*` call. The polyfill's own shim frame(s) are skipped, so the top frame is the
      * user's call site.
      *
-     * Format is engine-defined opaque text -- treat as diagnostic-only, do not parse. Returns an
-     * empty string if no JS context is active or if stack capture fails for any reason.
+     * Format is engine-defined opaque text -- treat as diagnostic-only, do not parse. Capture is
+     * **best-effort**: returns an empty string if no JS context is active, the engine doesn't
+     * expose a `stack` property on `Error`, or any internal operation fails. Hosts must check
+     * for an empty result before using the value.
      *
      * Cost is non-trivial (currently implemented via `new Error().stack` under the hood); the
      * caller decides per-message whether to invoke. Hosts that want stacks only on error

Polyfills/Console/Readme.md

@@ -14,7 +14,7 @@ Babylon::Polyfills::Console::Initialize(env, [](const char* message, auto) {
 });
 ```
 
-Inside the callback you can optionally capture the JavaScript callstack at the originating `console.*` call site via `Babylon::Polyfills::Console::CaptureCurrentJsStack(env)`. The polyfill's own shim frames are skipped, so the top frame is the user's call site. The capture is opt-in per-call -- hosts that don't need stacks pay nothing; hosts that want them on a specific level can branch on the `LogLevel` argument:
+Inside the callback you can optionally capture the JavaScript callstack at the originating `console.*` call site via `Babylon::Polyfills::Console::CaptureCurrentJsStack(env)`. The polyfill's own shim frames are skipped, so the top frame is the user's call site. Capture is best-effort -- the returned string can be empty (no JS context active, engine doesn't expose `Error.stack`, etc.), so always check before using. The capture is opt-in per-call -- hosts that don't need stacks pay nothing; hosts that want them on a specific level can branch on the `LogLevel` argument:
 ```c++
 Babylon::Polyfills::Console::Initialize(env, [env](const char* message, auto level) {
     fprintf(stdout, "%s", message);

Polyfills/Console/Source/Console.cpp

@@ -165,6 +165,16 @@ namespace Babylon::Polyfills::Console
         catch (...)
         {
         }
+
+        // N-API operations can leave a pending JS exception on `env` independently of throwing a
+        // C++ exception (e.g., `Object::Get` on a property accessor that throws); returning from
+        // the callback with a pending exception would cause `console.*` itself to throw on the
+        // JS side. Clear it so stack capture is truly side-effect free.
+        if (env.IsExceptionPending())
+        {
+            (void)env.GetAndClearPendingException();
+        }
+
         return stack;
     }
 }