@engine262/engine262 0.0.1-0574c6b92a2925de851f895445b7cfd7e97cc0ba

package/lib-src/inspector/methods.mts

@@ -0,0 +1,333 @@
+import type { Protocol } from 'devtools-protocol';
+import type {
+  DebuggerContext,
+  DebuggerNamespace, HeapProfilerNamespace, ProfilerNamespace, RuntimeNamespace,
+  TargetNamespace,
+} from './types.mts';
+import { getParsedEvent } from './internal-utils.mts';
+import { InspectorContext } from './context.mts';
+import {
+  Call, NormalCompletion, ObjectValue, ParseScript, runJobQueue, ScriptRecord, surroundingAgent, ThrowCompletion, skipDebugger, Value, type FunctionObject,
+  ParseModule,
+  SourceTextModuleRecord, performDevtoolsEval,
+  ValueOfNormalCompletion,
+  JSStringValue,
+  evalQ,
+  Assert,
+  kInternal,
+  captureStack,
+} from '#self';
+
+export const Debugger: DebuggerNamespace = {
+  enable(_req, { onDebuggerAttached }) {
+    onDebuggerAttached();
+    return { debuggerId: 'debugger.0' };
+  },
+  getScriptSource({ scriptId }) {
+    const source = surroundingAgent.parsedSources.get(scriptId);
+    if (!source) {
+      throw new Error('Not found');
+    }
+    return { scriptSource: source.ECMAScriptCode.sourceText };
+  },
+  setAsyncCallStackDepth() { },
+  setBlackboxPatterns() { },
+  setPauseOnExceptions() { },
+  setBlackboxExecutionContexts() { },
+  setBreakpointByUrl() {
+    return { breakpointId: '0', locations: [] };
+  },
+  stepInto(_, { sendEvent }) {
+    sendEvent['Debugger.resumed']();
+    surroundingAgent.resumeEvaluate({ pauseAt: 'step-in' });
+  },
+  resume(_, { sendEvent }) {
+    sendEvent['Debugger.resumed']();
+    surroundingAgent.resumeEvaluate();
+  },
+  stepOver(_req, { sendEvent }) {
+    sendEvent['Debugger.resumed']();
+    surroundingAgent.resumeEvaluate({ pauseAt: 'step-over' });
+  },
+  stepOut(_req, { sendEvent }) {
+    sendEvent['Debugger.resumed']();
+    surroundingAgent.resumeEvaluate({ pauseAt: 'step-out' });
+  },
+  evaluateOnCallFrame(req, context) {
+    return evaluate({
+      ...req,
+      uniqueContextId: context.context.getRealm(undefined)!.descriptor.uniqueId,
+      evalMode: context.context.evaluateMode,
+    }, context);
+  },
+  engine262_setEvaluateMode({ mode }, { context }) {
+    if (mode === 'module' || mode === 'script' || mode === 'console') {
+      context.evaluateMode = mode;
+    }
+  },
+  engine262_setFeatures() {
+    throw new Error('Method should not be implemented here.');
+  },
+};
+export const Profiler: ProfilerNamespace = {
+  enable() { },
+};
+export const Runtime: RuntimeNamespace = {
+  discardConsoleEntries() { },
+  enable() {},
+  compileScript(options, { context, sendEvent }) {
+    let parsed!: ScriptRecord | SourceTextModuleRecord | ObjectValue[];
+    let realm = context.getRealm(options.executionContextId);
+    if (!realm && !options.persistScript) {
+      realm = context.getAnyRealm();
+    }
+    if (!realm) {
+      return unsupportedError;
+    }
+    realm.realm.scope(() => {
+      if (context.evaluateMode === 'module') {
+        parsed = ParseModule(options.expression, realm.realm, { specifier: options.sourceURL, doNotTrackScriptId: !options.persistScript });
+      } else {
+        parsed = ParseScript(options.expression, realm.realm, { specifier: options.sourceURL, doNotTrackScriptId: !options.persistScript, [kInternal]: { allowAllPrivateNames: true } });
+      }
+    });
+    if (!parsed) {
+      throw new Error('No parsed result');
+    }
+    if (Array.isArray(parsed)) {
+      const e = context.createExceptionDetails(ThrowCompletion(parsed[0]), false);
+      // Note: it has to be this message to trigger devtools' line wrap.
+      e.exception!.description = 'SyntaxError: Unexpected end of input';
+      return { exceptionDetails: e };
+    }
+    if (options.persistScript) {
+      if (realm?.descriptor.id === undefined) {
+        throw new Error('No realm id found');
+      }
+      const event = getParsedEvent(parsed, parsed.HostDefined.scriptId!, realm.descriptor.id);
+      sendEvent['Debugger.scriptParsed'](event);
+      return { scriptId: event.scriptId };
+    }
+    return {};
+  },
+  callFunctionOn(options, { context }): Protocol.Runtime.CallFunctionOnResponse {
+    const realmDesc = context.getRealm(options.uniqueContextId || options.executionContextId) || context.getAnyRealm();
+    if (!realmDesc) {
+      throw new Error('No realm found');
+    }
+    const { Value: F } = realmDesc.realm.evaluateScript(`(${options.functionDeclaration})`, { doNotTrackScriptId: true }) as NormalCompletion<FunctionObject>;
+    const thisValue = options.objectId
+      ? context.getObject(options.objectId)!
+      : Value.undefined;
+    const args = options.arguments?.map((a) => {
+      // TODO: revisit
+      if ('value' in a) {
+        return Value(a.value);
+      }
+      if (a.objectId) {
+        return context.getObject(a.objectId)!;
+      }
+      if ('unserializableValue' in a) {
+        throw new RangeError();
+      }
+      return Value.undefined;
+    });
+    return realmDesc.realm.scope((): Protocol.Runtime.CallFunctionOnResponse => {
+      const completion = evalQ((Q, X): Protocol.Runtime.CallFunctionOnResponse => {
+        const r = Q(skipDebugger(Call(F, thisValue, args || [])));
+        if (options.returnByValue) {
+          const value = X(Call(realmDesc.realm.Intrinsics['%JSON.stringify%'], Value.undefined, [r]));
+          if (value instanceof JSStringValue) {
+            const valueRealized = JSON.parse(value.stringValue());
+            return { result: { type: typeof value, value: valueRealized } };
+          }
+        }
+        return context.createEvaluationResult(r);
+      });
+      if (completion instanceof ThrowCompletion) {
+        return { result: { type: 'undefined' }, exceptionDetails: context.createExceptionDetails(completion, false) };
+      }
+      return completion.Value;
+    });
+  },
+  evaluate(options, context) {
+    return evaluate({
+      ...options,
+      evalMode: context.context.evaluateMode,
+      uniqueContextId: options.uniqueContextId!,
+    }, context);
+  },
+  getExceptionDetails(req, { context }) {
+    const object = context.getObject(req.errorObjectId)!;
+    if (object instanceof ObjectValue) {
+      return {
+        exceptionDetails: context.createExceptionDetails(ThrowCompletion(object), false),
+      };
+    }
+    return {
+      exceptionDetails: {
+        text: 'unsupported', lineNumber: 0, columnNumber: 0, exceptionId: 0,
+      },
+    };
+  },
+  getHeapUsage() {
+    return {
+      usedSize: 0, totalSize: 0, backingStorageSize: 0, embedderHeapUsedSize: 0,
+    };
+  },
+  getIsolateId() {
+    return { id: 'isolate.0' };
+  },
+  getProperties(options, { context }) {
+    return context.getProperties(options);
+  },
+  globalLexicalScopeNames({ executionContextId }, { context }) {
+    const global = context.getRealm(executionContextId)?.realm.GlobalObject;
+    if (!global) {
+      return { names: [] };
+    }
+    const keys = skipDebugger(global.OwnPropertyKeys());
+    if (keys instanceof ThrowCompletion) {
+      return { names: [] };
+    }
+    return { names: ValueOfNormalCompletion(keys).map((k) => (k instanceof JSStringValue ? k.stringValue() : null!)).filter(Boolean) };
+  },
+  releaseObject(req, { context }) {
+    context.releaseObject(req.objectId);
+  },
+  releaseObjectGroup({ objectGroup }, { context }) {
+    context.releaseObjectGroup(objectGroup);
+  },
+  runIfWaitingForDebugger() { },
+};
+export const HeapProfiler: HeapProfilerNamespace = {
+  enable() { },
+  collectGarbage() { },
+};
+
+export const Target: TargetNamespace = {
+  setDiscoverTargets() { },
+  // @ts-expect-error no doc
+  setRemoteLocations() { },
+};
+
+const unsupportedError: Protocol.Runtime.EvaluateResponse = {
+  result: { type: 'undefined' },
+  exceptionDetails: {
+    text: 'unsupported', lineNumber: 0, columnNumber: 0, exceptionId: 0,
+  },
+};
+function evaluate(options: {
+  uniqueContextId: string,
+  expression: string,
+  evalMode: InspectorContext['evaluateMode'],
+  throwOnSideEffect?: boolean,
+  awaitPromise?: boolean,
+  callFrameId?: string,
+}, _context: DebuggerContext): Protocol.Runtime.EvaluateResponse | Promise<Protocol.Runtime.EvaluateResponse> {
+  const { context } = _context;
+  const isPreview = options.throwOnSideEffect;
+  if (options.awaitPromise) {
+    return unsupportedError;
+  }
+  const realm = context.getRealm(options.uniqueContextId);
+  if (!realm) {
+    return unsupportedError;
+  }
+
+  const isCallOnFrame = typeof options.callFrameId === 'string';
+  let callOnFramePoppedLevel = 0;
+  const oldExecutionStack = [...surroundingAgent.executionContextStack];
+  if (isCallOnFrame) {
+    const frame = surroundingAgent.executionContextStack[options.callFrameId as `${number}`];
+    if (!frame) {
+      // eslint-disable-next-line no-console
+      console.error('Execution context not found: ', options.callFrameId);
+      return unsupportedError;
+    }
+    for (const currentFrame of [...surroundingAgent.executionContextStack].reverse()) {
+      if (currentFrame === frame) {
+        break;
+      }
+      callOnFramePoppedLevel += 1;
+      surroundingAgent.executionContextStack.pop(currentFrame);
+    }
+  }
+  const promise = new Promise<Protocol.Runtime.EvaluateResponse>((resolve) => {
+    let toBeEvaluated;
+    if (isPreview || options.evalMode === 'console' || isCallOnFrame) {
+      toBeEvaluated = performDevtoolsEval(options.expression, realm.realm, false, !!(isPreview || isCallOnFrame));
+    } else {
+      let parsed!: ScriptRecord | SourceTextModuleRecord | ObjectValue[];
+      const realm = context.getRealm(options.uniqueContextId);
+      realm?.realm.scope(() => {
+        if (options.evalMode === 'module') {
+          parsed = ParseModule(options.expression, realm.realm);
+        } else {
+          parsed = ParseScript(options.expression, realm.realm);
+        }
+      });
+      if (Array.isArray(parsed)) {
+        const e = context.createExceptionDetails(ThrowCompletion(parsed[0]), false);
+        resolve({ exceptionDetails: e, result: { type: 'undefined' } });
+        return;
+      }
+      toBeEvaluated = parsed;
+    }
+
+    const noDebuggerEvaluate = () => {
+      if (!('next' in toBeEvaluated)) {
+        throw new Assert.Error('Unexpected');
+      }
+      resolve(context.createEvaluationResult(skipDebugger(toBeEvaluated)));
+    };
+    if (isPreview) {
+      surroundingAgent.debugger_scopePreview(noDebuggerEvaluate);
+      return;
+    }
+    if (isCallOnFrame) {
+      noDebuggerEvaluate();
+      return;
+    }
+
+    const completion = realm.realm.evaluate(toBeEvaluated, (completion) => {
+      resolve(context.createEvaluationResult(completion));
+      runJobQueue();
+    });
+    if (completion) {
+      return;
+    }
+    surroundingAgent.resumeEvaluate();
+  });
+  promise.then(() => {
+    if (callOnFramePoppedLevel) {
+      Assert(oldExecutionStack.length - callOnFramePoppedLevel === surroundingAgent.executionContextStack.length);
+      for (const [newIndex, newStack] of surroundingAgent.executionContextStack.entries()) {
+        Assert(newStack === oldExecutionStack[newIndex]);
+      }
+      surroundingAgent.executionContextStack.length = 0;
+      for (const stack of oldExecutionStack) {
+        surroundingAgent.executionContextStack.push(stack);
+      }
+    }
+  }, (err): Protocol.Runtime.EvaluateResponse => {
+    const expr = surroundingAgent.runningExecutionContext.callSite.lastNode?.sourceText;
+    const frame = InspectorContext.callSiteToCallFrame(captureStack().stack);
+    _context.sendEvent['Runtime.exceptionThrown']({
+      timestamp: Date.now(),
+      exceptionDetails: {
+        stackTrace: frame.length ? { callFrames: frame } : undefined,
+        text: `engine262 error when evaluating the following node:\n\n    ${expr}\n\n${err.constructor.name}: ${err.message}\n${err.stack.slice(err.stack.indexOf(err.message) + err.message.length + 1)}\n\nFrom now on, the engine262 VM state is broken, please press the reload button.`,
+        columnNumber: frame[0]?.columnNumber,
+        lineNumber: frame[0]?.lineNumber,
+        scriptId: frame[0]?.scriptId,
+        url: frame[0]?.url,
+        exceptionId: 0,
+      },
+    });
+    return {
+      result: { type: 'undefined' },
+    };
+  });
+  return promise;
+}

package/lib-src/inspector/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "references": [{ "path": "../../src/" }],
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "composite": true,
+    "incremental": true,
+    "declarationDir": "../../lib/inspector",
+    "tsBuildInfoFile": "../../lib/inspector/.tsbuildinfo",
+    "erasableSyntaxOnly": true,
+    "rootDir": "./",
+    "outDir": "../../lib/inspector/",
+    "allowImportingTsExtensions": true,
+    "rewriteRelativeImportExtensions": true,
+    "resolveJsonModule": true
+  },
+  "include": ["./*.mts"]
+}

package/lib-src/inspector/types.mts

@@ -0,0 +1,225 @@
+import type { Protocol } from 'devtools-protocol';
+import type { InspectorContext } from './context.mts';
+
+export interface DebuggerPreference {
+  previewDebug: boolean;
+}
+
+export interface DebuggerContext {
+  sendEvent: DevtoolEvents;
+  onDebuggerAttached(): void;
+  preference: DebuggerPreference;
+  context: InspectorContext;
+}
+
+export interface DebuggerNamespace {
+  engine262_setEvaluateMode(req: { mode: 'module' | 'script' | 'console' }, context: DebuggerContext): void;
+  engine262_setFeatures(req: { features: string[] }, context: DebuggerContext): void;
+}
+export interface DebuggerNamespace {
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Debugger/#method-continueToLocation */
+  continueToLocation?(req: Protocol.Debugger.ContinueToLocationRequest, context: DebuggerContext): void;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Debugger/#method-disable */
+  disable?(req: void, context: DebuggerContext): void;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Debugger/#method-enable */
+  enable?(req: Protocol.Debugger.EnableRequest, context: DebuggerContext): Protocol.Debugger.EnableResponse;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Debugger/#method-evaluateOnCallFrame */
+  evaluateOnCallFrame?(req: Protocol.Debugger.EvaluateOnCallFrameRequest, context: DebuggerContext): Protocol.Debugger.EvaluateOnCallFrameResponse | Promise<Protocol.Debugger.EvaluateOnCallFrameResponse>;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Debugger/#method-getPossibleBreakpoints */
+  getPossibleBreakpoints?(req: Protocol.Debugger.GetPossibleBreakpointsRequest, context: DebuggerContext): Protocol.Debugger.GetPossibleBreakpointsResponse;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Debugger/#method-getScriptSource */
+  getScriptSource?(req: Protocol.Debugger.GetScriptSourceRequest, context: DebuggerContext): Protocol.Debugger.GetScriptSourceResponse;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Debugger/#method-pause */
+  pause?(req: void, context: DebuggerContext): void;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Debugger/#method-removeBreakpoint */
+  removeBreakpoint?(req: Protocol.Debugger.RemoveBreakpointRequest, context: DebuggerContext): void;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Debugger/#method-restartFrame */
+  restartFrame?(req: Protocol.Debugger.RestartFrameRequest, context: DebuggerContext): Protocol.Debugger.RestartFrameResponse;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Debugger/#method-resume */
+  resume?(req: void, context: DebuggerContext): void;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Debugger/#method-searchInContent */
+  searchInContent?(req: Protocol.Debugger.SearchInContentRequest, context: DebuggerContext): Protocol.Debugger.SearchInContentResponse;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Debugger/#method-setAsyncCallStackDepth */
+  setAsyncCallStackDepth?(req: Protocol.Debugger.SetAsyncCallStackDepthRequest, context: DebuggerContext): void;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Debugger/#method-setBreakpoint */
+  setBreakpoint?(req: Protocol.Debugger.SetBreakpointRequest, context: DebuggerContext): Protocol.Debugger.SetBreakpointResponse;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Debugger/#method-setBreakpointByUrl */
+  setBreakpointByUrl?(req: Protocol.Debugger.SetBreakpointByUrlRequest, context: DebuggerContext): Protocol.Debugger.SetBreakpointByUrlResponse;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Debugger/#method-setBreakpointsActive */
+  setBreakpointsActive?(req: Protocol.Debugger.SetBreakpointsActiveRequest, context: DebuggerContext): void;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Debugger/#method-setInstrumentationBreakpoint */
+  setInstrumentationBreakpoint?(req: Protocol.Debugger.SetInstrumentationBreakpointRequest, context: DebuggerContext): Protocol.Debugger.SetInstrumentationBreakpointResponse;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Debugger/#method-setPauseOnExceptions */
+  setPauseOnExceptions?(req: Protocol.Debugger.SetPauseOnExceptionsRequest, context: DebuggerContext): void;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Debugger/#method-setScriptSource */
+  setScriptSource?(req: Protocol.Debugger.SetScriptSourceRequest, context: DebuggerContext): Protocol.Debugger.SetScriptSourceResponse;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Debugger/#method-setSkipAllPauses */
+  setSkipAllPauses?(req: Protocol.Debugger.SetSkipAllPausesRequest, context: DebuggerContext): void;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Debugger/#method-setVariableValue */
+  setVariableValue?(req: Protocol.Debugger.SetVariableValueRequest, context: DebuggerContext): void;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Debugger/#method-stepInto */
+  stepInto?(req: Protocol.Debugger.StepIntoRequest, context: DebuggerContext): void;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Debugger/#method-stepOut */
+  stepOut?(req: void, context: DebuggerContext): void;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Debugger/#method-stepOver */
+  stepOver?(req: Protocol.Debugger.StepOverRequest, context: DebuggerContext): void;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Debugger/#method-getStackTrace */
+  getStackTrace?(req: Protocol.Debugger.GetStackTraceRequest, context: DebuggerContext): Protocol.Debugger.GetStackTraceResponse;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Debugger/#method-setBlackboxedRanges */
+  setBlackboxedRanges?(req: Protocol.Debugger.SetBlackboxedRangesRequest, context: DebuggerContext): void;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Debugger/#method-setBlackboxExecutionContexts */
+  setBlackboxExecutionContexts?(req: Protocol.Debugger.SetBlackboxExecutionContextsRequest, context: DebuggerContext): void;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Debugger/#method-setBlackboxPatterns */
+  setBlackboxPatterns?(req: Protocol.Debugger.SetBlackboxPatternsRequest, context: DebuggerContext): void;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Debugger/#method-setBreakpointOnFunctionCall */
+  setBreakpointOnFunctionCall?(req: Protocol.Debugger.SetBreakpointOnFunctionCallRequest, context: DebuggerContext): Protocol.Debugger.SetBreakpointOnFunctionCallResponse;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Debugger/#method-setReturnValue */
+  setReturnValue?(req: Protocol.Debugger.SetReturnValueRequest, context: DebuggerContext): void;
+}
+
+export interface ProfilerNamespace {
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Profiler/#method-disable */
+  disable?(req: void, context: DebuggerContext): void;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Profiler/#method-enable */
+  enable?(req: void, context: DebuggerContext): void;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Profiler/#method-getBestEffortCoverage */
+  getBestEffortCoverage?(req: void, context: DebuggerContext): Protocol.Profiler.GetBestEffortCoverageResponse;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Profiler/#method-setSamplingInterval */
+  setSamplingInterval?(req: Protocol.Profiler.SetSamplingIntervalRequest, context: DebuggerContext): void;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Profiler/#method-start */
+  start?(req: void, context: DebuggerContext): void;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Profiler/#method-startPreciseCoverage */
+  startPreciseCoverage?(req: Protocol.Profiler.StartPreciseCoverageRequest, context: DebuggerContext): Protocol.Profiler.StartPreciseCoverageResponse;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Profiler/#method-stop */
+  stop?(req: void, context: DebuggerContext): void;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Profiler/#method-stopPreciseCoverage */
+  stopPreciseCoverage?(req: void, context: DebuggerContext): void;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Profiler/#method-takePreciseCoverage */
+  takePreciseCoverage?(req: void, context: DebuggerContext): Protocol.Profiler.TakePreciseCoverageResponse;
+}
+
+export interface RuntimeNamespace {
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Runtime/#method-addBinding */
+  addBinding?(req: Protocol.Runtime.AddBindingRequest, context: DebuggerContext): void;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Runtime/#method-awaitPromise */
+  awaitPromise?(req: Protocol.Runtime.AwaitPromiseRequest, context: DebuggerContext): Protocol.Runtime.AwaitPromiseResponse;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Runtime/#method-callFunctionOn */
+  callFunctionOn?(req: Protocol.Runtime.CallFunctionOnRequest, context: DebuggerContext): Protocol.Runtime.CallFunctionOnResponse;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Runtime/#method-compileScript */
+  compileScript?(req: Protocol.Runtime.CompileScriptRequest, context: DebuggerContext): Protocol.Runtime.CompileScriptResponse;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Runtime/#method-disable */
+  disable?(req: void, context: DebuggerContext): void;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Runtime/#method-discardConsoleEntries */
+  discardConsoleEntries?(req: void, context: DebuggerContext): void;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Runtime/#method-enable */
+  enable?(req: void, context: DebuggerContext): void;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Runtime/#method-evaluate */
+  evaluate?(req: Protocol.Runtime.EvaluateRequest, context: DebuggerContext): Protocol.Runtime.EvaluateResponse | Promise<Protocol.Runtime.EvaluateResponse>;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Runtime/#method-getProperties */
+  getProperties?(req: Protocol.Runtime.GetPropertiesRequest, context: DebuggerContext): Protocol.Runtime.GetPropertiesResponse;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Runtime/#method-globalLexicalScopeNames */
+  globalLexicalScopeNames?(req: Protocol.Runtime.GlobalLexicalScopeNamesRequest, context: DebuggerContext): Protocol.Runtime.GlobalLexicalScopeNamesResponse;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Runtime/#method-queryObjects */
+  queryObjects?(req: Protocol.Runtime.QueryObjectsRequest, context: DebuggerContext): Protocol.Runtime.QueryObjectsResponse;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Runtime/#method-releaseObject */
+  releaseObject?(req: Protocol.Runtime.ReleaseObjectRequest, context: DebuggerContext): void;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Runtime/#method-releaseObjectGroup */
+  releaseObjectGroup?(req: Protocol.Runtime.ReleaseObjectGroupRequest, context: DebuggerContext): void;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Runtime/#method-removeBinding */
+  removeBinding?(req: Protocol.Runtime.RemoveBindingRequest, context: DebuggerContext): void;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Runtime/#method-runIfWaitingForDebugger */
+  runIfWaitingForDebugger?(req: void, context: DebuggerContext): void;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Runtime/#method-runScript */
+  runScript?(req: Protocol.Runtime.RunScriptRequest, context: DebuggerContext): Protocol.Runtime.RunScriptResponse;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Runtime/#method-setAsyncCallStackDepth */
+  setAsyncCallStackDepth?(req: Protocol.Runtime.SetAsyncCallStackDepthRequest, context: DebuggerContext): void;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Runtime/#method-getExceptionDetails */
+  getExceptionDetails?(req: Protocol.Runtime.GetExceptionDetailsRequest, context: DebuggerContext): Protocol.Runtime.GetExceptionDetailsResponse;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Runtime/#method-getHeapUsage */
+  getHeapUsage?(req: void, context: DebuggerContext): Protocol.Runtime.GetHeapUsageResponse;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Runtime/#method-getIsolateId */
+  getIsolateId?(req: void, context: DebuggerContext): Protocol.Runtime.GetIsolateIdResponse;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Runtime/#method-setCustomObjectFormatterEnabled */
+  setCustomObjectFormatterEnabled?(req: Protocol.Runtime.SetCustomObjectFormatterEnabledRequest, context: DebuggerContext): void;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Runtime/#method-setMaxCallStackSizeToCapture */
+  setMaxCallStackSizeToCapture?(req: Protocol.Runtime.SetMaxCallStackSizeToCaptureRequest, context: DebuggerContext): void;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Runtime/#method-terminateExecution */
+  terminateExecution?(req: void, context: DebuggerContext): void;
+}
+
+export interface HeapProfilerNamespace {
+  /** https://chromedevtools.github.io/devtools-protocol/v8/HeapProfiler/#method-addInspectedHeapObject */
+  addInspectedHeapObject?(req: Protocol.HeapProfiler.AddInspectedHeapObjectRequest, context: DebuggerContext): void;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/HeapProfiler/#method-collectGarbage */
+  collectGarbage?(req: void, context: DebuggerContext): void;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/HeapProfiler/#method-disable */
+  disable?(req: void, context: DebuggerContext): void;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/HeapProfiler/#method-enable */
+  enable?(req: void, context: DebuggerContext): void;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/HeapProfiler/#method-getHeapObjectId */
+  getHeapObjectId?(req: Protocol.HeapProfiler.GetHeapObjectIdRequest, context: DebuggerContext): Protocol.HeapProfiler.GetHeapObjectIdResponse;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/HeapProfiler/#method-getObjectByHeapObjectId */
+  getObjectByHeapObjectId?(req: Protocol.HeapProfiler.GetObjectByHeapObjectIdRequest, context: DebuggerContext): Protocol.HeapProfiler.GetObjectByHeapObjectIdResponse;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/HeapProfiler/#method-getSamplingProfile */
+  getSamplingProfile?(req: void, context: DebuggerContext): Protocol.HeapProfiler.GetSamplingProfileResponse;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/HeapProfiler/#method-startSampling */
+  startSampling?(req: Protocol.HeapProfiler.StartSamplingRequest, context: DebuggerContext): void;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/HeapProfiler/#method-startTrackingHeapObjects */
+  startTrackingHeapObjects?(req: Protocol.HeapProfiler.StartTrackingHeapObjectsRequest, context: DebuggerContext): void;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/HeapProfiler/#method-stopSampling */
+  stopSampling?(req: void, context: DebuggerContext): Protocol.HeapProfiler.StopSamplingResponse;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/HeapProfiler/#method-stopTrackingHeapObjects */
+  stopTrackingHeapObjects?(req: Protocol.HeapProfiler.StopTrackingHeapObjectsRequest, context: DebuggerContext): void;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/HeapProfiler/#method-takeHeapSnapshot */
+  takeHeapSnapshot?(req: Protocol.HeapProfiler.TakeHeapSnapshotRequest, context: DebuggerContext): void;
+}
+
+// https://chromedevtools.github.io/devtools-protocol/1-3/Target/
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface TargetNamespace {
+  /** https://chromedevtools.github.io/devtools-protocol/1-3/Target/#method-setDiscoverTargets */
+  setDiscoverTargets?(req: Protocol.Target.SetDiscoverTargetsRequest, context: DebuggerContext): void;
+}
+
+export interface DevtoolEvents {
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Debugger/#event-paused */
+  'Debugger.paused'(event: Protocol.Debugger.PausedEvent): void;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Debugger/#event-resumed */
+  'Debugger.resumed'(event: void): void;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Debugger/#event-scriptFailedToParse */
+  'Debugger.scriptFailedToParse'(event: Protocol.Debugger.ScriptFailedToParseEvent): void;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Debugger/#event-scriptParsed */
+  'Debugger.scriptParsed'(event: Protocol.Debugger.ScriptParsedEvent): void;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/HeapProfiler/#event-addHeapSnapshotChunk */
+  'HeapProfiler.addHeapSnapshotChunk'(event: Protocol.HeapProfiler.AddHeapSnapshotChunkEvent): void;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/HeapProfiler/#event-heapStatsUpdate */
+  'HeapProfiler.heapStatsUpdate'(event: Protocol.HeapProfiler.HeapStatsUpdateEvent): void;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/HeapProfiler/#event-lastSeenObjectId */
+  'HeapProfiler.lastSeenObjectId'(event: Protocol.HeapProfiler.LastSeenObjectIdEvent): void;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/HeapProfiler/#event-reportHeapSnapshotProgress */
+  'HeapProfiler.reportHeapSnapshotProgress'(event: Protocol.HeapProfiler.ReportHeapSnapshotProgressEvent): void;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/HeapProfiler/#event-resetProfiles */
+  'HeapProfiler.resetProfiles'(event: void): void;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Profiler/#event-consoleProfileFinished */
+  'Profiler.consoleProfileFinished'(event: Protocol.Profiler.ConsoleProfileFinishedEvent): void;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Profiler/#event-consoleProfileStarted */
+  'Profiler.consoleProfileStarted'(event: Protocol.Profiler.ConsoleProfileStartedEvent): void;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Profiler/#event-preciseCoverageDeltaUpdate */
+  'Profiler.preciseCoverageDeltaUpdate'(event: Protocol.Profiler.PreciseCoverageDeltaUpdateEvent): void;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Runtime/#event-consoleAPICalled */
+  'Runtime.consoleAPICalled'(event: Protocol.Runtime.ConsoleAPICalledEvent): void;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Runtime/#event-exceptionRevoked */
+  'Runtime.exceptionRevoked'(event: Protocol.Runtime.ExceptionRevokedEvent): void;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Runtime/#event-exceptionThrown */
+  'Runtime.exceptionThrown'(event: Protocol.Runtime.ExceptionThrownEvent): void;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Runtime/#event-executionContextCreated */
+  'Runtime.executionContextCreated'(event: Protocol.Runtime.ExecutionContextCreatedEvent): void;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Runtime/#event-executionContextDestroyed */
+  'Runtime.executionContextDestroyed'(event: Protocol.Runtime.ExecutionContextDestroyedEvent): void;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Runtime/#event-executionContextsCleared */
+  'Runtime.executionContextsCleared'(event: void): void;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Runtime/#event-inspectRequested */
+  'Runtime.inspectRequested'(event: Protocol.Runtime.InspectRequestedEvent): void;
+  /** https://chromedevtools.github.io/devtools-protocol/v8/Runtime/#event-bindingCalled */
+  'Runtime.bindingCalled'(event: Protocol.Runtime.BindingCalledEvent): void;
+}

package/lib-src/inspector/utils.mts

@@ -0,0 +1,81 @@
+import type Protocol from 'devtools-protocol';
+import { Inspector } from './index.mts';
+import {
+  CreateBuiltinFunction, CreateDataProperty, DefinePropertyOrThrow, Descriptor, OrdinaryObjectCreate, surroundingAgent, ThrowCompletion, skipDebugger, Value, type Arguments, type ManagedRealm,
+  type PlainEvaluator,
+  type PlainCompletion,
+} from '#self';
+
+const consoleMethods = [
+  'log',
+  'debug',
+  'info',
+  'error',
+  'warning',
+  'dir',
+  'dirxml',
+  'table',
+  'trace',
+  'clear',
+  'startGroup',
+  'startGroupCollapsed',
+  'endGroup',
+  'assert',
+  'profile',
+  'profileEnd',
+  'count',
+  'timeEnd',
+] as const;
+type ConsoleMethod = typeof consoleMethods[number];
+export function createConsole(
+  realm: ManagedRealm,
+  defaultBehaviour: Partial<Record<ConsoleMethod, (args: Arguments) => void | PlainCompletion<void> | PlainEvaluator<void>>> & { default?: (method: ConsoleMethod, args: Arguments) => void | PlainCompletion<void> | PlainEvaluator<void> },
+) {
+  realm.scope(() => {
+    const console = OrdinaryObjectCreate(realm.Intrinsics['%Object.prototype%']);
+    skipDebugger(DefinePropertyOrThrow(
+      realm.GlobalObject,
+      Value('console'),
+      Descriptor({
+        Configurable: Value.true,
+        Enumerable: Value.false,
+        Writable: Value.true,
+        Value: console,
+      }),
+    ));
+    consoleMethods.forEach((method) => {
+      const f = CreateBuiltinFunction(
+        function* Console(args): PlainEvaluator<Value> {
+          if (surroundingAgent.debugger_isPreviewing) {
+            return Value.undefined;
+          }
+
+          let completion;
+          if (defaultBehaviour[method]) {
+            completion = defaultBehaviour[method](args);
+          } else if (defaultBehaviour.default) {
+            completion = defaultBehaviour.default(method, args);
+          }
+
+          if (completion) {
+            if (typeof completion === 'object' && 'next' in completion) {
+              completion = yield* completion;
+            }
+            // Do not use Q(host) here. A host may return something invalid like ReturnCompletion.
+            if (completion instanceof ThrowCompletion) {
+              return completion;
+            }
+          }
+          if (realm.HostDefined.attachingInspector instanceof Inspector) {
+            realm.HostDefined.attachingInspector.console(realm, method as Protocol.Protocol.Runtime.ConsoleAPICalledEventType, args);
+          }
+          return Value.undefined;
+        },
+        1,
+        Value(method),
+        [],
+      );
+      skipDebugger(CreateDataProperty(console, Value(method), f));
+    });
+  });
+}