@engine262/engine262 0.0.1-07c72085c73f960bcf0aa06db807321f3b446518

package/lib-src/inspector/methods.mts

@@ -0,0 +1,123 @@
+import type {
+  DebuggerNamespace, HeapProfilerNamespace, ProfilerNamespace, RuntimeNamespace,
+} from './types.mts';
+import {
+  Call, NormalCompletion, ObjectValue, ThrowCompletion, Value, type FunctionObject,
+} from '#self';
+
+export const Debugger: DebuggerNamespace = {
+  enable(_req) {
+    return { debuggerId: 'debugger.0' };
+  },
+  setAsyncCallStackDepth() { },
+  setBlackboxPatterns() { },
+  setPauseOnExceptions() { },
+  setBlackboxExecutionContexts() { },
+  setBreakpointByUrl() {
+    return { breakpointId: '0', locations: [] };
+  },
+};
+export const Profiler: ProfilerNamespace = {
+  enable() { },
+};
+export const Runtime: RuntimeNamespace = {
+  discardConsoleEntries() { },
+  enable() { },
+  compileScript() {
+    return { scriptId: 'script.0' };
+  },
+  callFunctionOn(options, { getContext }) {
+    const context = getContext(options.executionContextId);
+    const { Value: F } = context.realm.evaluateScript(`(${options.functionDeclaration})`) as NormalCompletion<FunctionObject>;
+    const thisValue = options.objectId
+      ? context.getObject(options.objectId)!
+      : Value.undefined;
+    const args = options.arguments?.map((a) => {
+      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;
+    });
+    const r = Call(F, thisValue, args || []);
+    // @ts-expect-error
+    return context.createEvaluationResult(r, options);
+  },
+  evaluate(options, { preference, getContext }) {
+    if (options.awaitPromise || (!preference.preview && options.throwOnSideEffect)) {
+      return {
+        result: { type: 'undefined' },
+        exceptionDetails: {
+          text: 'unsupported', lineNumber: 0, columnNumber: 0, exceptionId: 0,
+        },
+      };
+    }
+
+    const context = getContext(options.contextId);
+    // TODO: introduce devtool scoping
+    const finalSource = options.throwOnSideEffect ? `{\n${options.expression}}\n` : options.expression;
+    const r = context.realm.evaluateScript(finalSource, { inspectorPreview: options.throwOnSideEffect });
+    // @ts-expect-error
+    return context.createEvaluationResult(r, options);
+  },
+  getExceptionDetails(req, { getContext }) {
+    const context = getContext();
+    const object = context.getObject(req.errorObjectId)!;
+    if (object instanceof ObjectValue) {
+      return {
+        // @ts-expect-error
+        exceptionDetails: context.createExceptionDetails(ThrowCompletion(object), {}),
+      };
+    }
+    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, { getContext }) {
+    const context = getContext();
+    const object = context.getObject(options.objectId)!;
+    // @ts-expect-error
+    return context.getProperties(object, options);
+  },
+  globalLexicalScopeNames({ executionContextId }, { getContext }) {
+    const context = getContext(executionContextId);
+    const envRec = context.realm.GlobalEnv;
+    const names = Array.from(envRec.DeclarativeRecord.bindings.keys(), (v) => v.stringValue());
+    return { names };
+  },
+  releaseObject(req, { getContext }) {
+    getContext().releaseObject(req.objectId);
+  },
+  releaseObjectGroup({ objectGroup }, { getContext }) {
+    getContext().releaseObjectGroup(objectGroup);
+  },
+  runIfWaitingForDebugger(_, ctx) {
+    ctx.sendEvent['Runtime.executionContextCreated']({
+      context: {
+        id: 0,
+        origin: 'eval',
+        name: 'top',
+        uniqueId: '',
+      },
+    });
+  },
+};
+export const HeapProfiler: HeapProfilerNamespace = {
+  enable() { },
+  collectGarbage() { },
+};

package/lib-src/inspector/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "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": [
+    "./context.mts",
+    "./methods.mts",
+    "./types.mts",
+    "./index.mts",
+    "./utils.mts"
+  ]
+}

package/lib-src/inspector/types.mts

@@ -0,0 +1,213 @@
+import type { Protocol } from 'devtools-protocol';
+import type { InspectorContext } from './context.mts';
+
+export interface DebuggerPreference {
+  preview: boolean;
+  previewDebug: boolean;
+}
+
+export interface DebuggerContext {
+  sendEvent: DevtoolEvents;
+  getContext(executionContextId?: number | undefined): InspectorContext;
+  preference: DebuggerPreference;
+}
+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;
+  /** 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;
+  /** 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;
+}
+
+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,86 @@
+import type Protocol from 'devtools-protocol';
+import { Inspector } from './index.mts';
+import {
+  CreateBuiltinFunction, CreateDataProperty, CreateNonEnumerableDataPropertyOrThrow, DefinePropertyOrThrow, Descriptor, DetachArrayBuffer, isArrayBufferObject, NormalCompletion, OrdinaryObjectCreate, surroundingAgent, ThrowCompletion, Value, type Arguments, type ManagedRealm,
+} 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 | NormalCompletion<void>>>) {
+  realm.scope(() => {
+    const console = OrdinaryObjectCreate(realm.Intrinsics['%Object.prototype%']);
+    DefinePropertyOrThrow(
+      realm.GlobalObject,
+      Value('console'),
+      Descriptor({
+        Configurable: Value.true,
+        Enumerable: Value.false,
+        Writable: Value.true,
+        Value: console,
+      }),
+    );
+    consoleMethods.forEach((method) => {
+      const f = CreateBuiltinFunction(
+        (args) => {
+          if (surroundingAgent.debugger_isPreviewing) {
+            return Value.undefined;
+          }
+          if (defaultBehaviour[method]) {
+            const completion = (defaultBehaviour[method](args));
+            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),
+        [],
+      );
+      CreateDataProperty(console, Value(method), f);
+    });
+  });
+}
+
+export function createInternals(realm: ManagedRealm) {
+  realm.scope(() => {
+    const $ = OrdinaryObjectCreate.from({
+      debugger: () => {
+        if (surroundingAgent.debugger_isPreviewing) {
+          return;
+        }
+        // eslint-disable-next-line no-debugger
+        debugger;
+      },
+      detachArrayBuffer: (object) => {
+        if (!isArrayBufferObject(object)) {
+          return surroundingAgent.Throw('TypeError', 'Raw', 'Argument must be an ArrayBuffer');
+        }
+        return DetachArrayBuffer(object);
+      },
+    });
+    CreateNonEnumerableDataPropertyOrThrow(realm.GlobalObject, Value('$'), $);
+  });
+}

package/lib-src/node/bin.mts

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+
+import { start } from 'node:repl';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { format as _format, inspect as _inspect, parseArgs } from 'node:util';
+import packageJson from '../../package.json' with { type: 'json' }; // eslint-disable-line import/order
+import { createConsole, createInternals } from '../inspector/utils.mts';
+import {
+  setSurroundingAgent, FEATURES, inspect, Value, Type, Completion, AbruptCompletion, JSStringValue,
+  type Arguments,
+  evalQ,
+  Agent,
+  ManagedRealm,
+  Throw,
+} from '#self';
+
+const help = `
+engine262 v${packageJson.version}
+
+Usage:
+
+    engine262 [options]
+    engine262 [options] [input file]
+    engine262 [input file]
+
+Options:
+
+    -h, --help      Show help (this screen)
+    -m, --module    Evaluate contents of input-file as a module.
+    --features=...  A comma separated list of features.
+    --features=all  Enable all features.
+    --list-features List available features.
+    --no-inspector  Do not attach an inspector.
+    --no-preview    Do not enable preview in the inspector.
+`;
+
+const argv = parseArgs({
+  args: process.argv.slice(2),
+  allowPositionals: true,
+  allowNegative: true,
+  strict: true,
+  options: {
+    'help': { type: 'boolean', short: 'h' },
+    'module': { type: 'boolean', short: 'm' },
+    'features': { type: 'string' },
+    'list-features': { type: 'boolean' },
+    'inspector': { type: 'boolean' },
+    'preview': { type: 'boolean', default: true },
+    // hidden options
+    'preview-debug': { type: 'boolean' },
+  },
+});
+
+if (argv.values.help) {
+  process.stdout.write(help);
+  process.exit(0);
+} else if (argv.values['list-features']) {
+  let nameLength = 0;
+  let flagLength = 0;
+  FEATURES.forEach((f) => {
+    if (f.name.length > nameLength) {
+      nameLength = f.name.length;
+    }
+    if (f.flag.length > flagLength) {
+      flagLength = f.flag.length;
+    }
+  });
+  const log = (f: string, n: string, u: string) => {
+    process.stdout.write(`${f.padEnd(flagLength, ' ')} ${n.padEnd(nameLength, ' ')} ${u}\n`);
+  };
+  log('flag', 'name', 'url');
+  log('----', '----', '---');
+  FEATURES.forEach((f) => {
+    log(f.flag, f.name, f.url);
+  });
+  process.exit(0);
+}
+
+let features: string[];
+if (argv.values.features === 'all') {
+  features = FEATURES.map((f) => f.flag);
+} else if (argv.values.features) {
+  features = argv.values.features.split(',');
+} else {
+  features = [];
+}
+
+const agent = new Agent({ features });
+setSurroundingAgent(agent);
+
+const realm = new ManagedRealm({});
+// Define console.log
+const format = (args: Arguments) => args.map((a, i) => {
+  if (i === 0 && Type(a) === 'String') {
+    return (a as JSStringValue).stringValue();
+  }
+  return inspect(a);
+}).join(' ');
+createConsole(realm, {
+  log: (args) => {
+    process.stdout.write(`${format(args)}\n`);
+  },
+  error: (args) => {
+    process.stderr.write(`${format(args)}\n`);
+  },
+  debug: (args) => {
+    process.stderr.write(`${_format(...args)}\n`);
+  },
+});
+createInternals(realm);
+
+if (argv.values.inspector !== false) {
+  let has_ws = false;
+  try {
+    await import('ws');
+    has_ws = true;
+  } catch {
+    if (argv.values.inspector === true) {
+      process.stderr.write('--inspector requires the "ws" package to be installed.\n');
+      process.exit(1);
+    }
+  }
+  if (has_ws) {
+    // @ts-ignore
+    const { NodeWebsocketInspector } = await import('./inspector.mts');
+    const inspect = await NodeWebsocketInspector.new();
+    inspect.attachRealm(realm);
+    inspect.preference.preview = argv.values.preview;
+    inspect.preference.previewDebug = argv.values['preview-debug'] || false;
+  }
+}
+
+function oneShotEval(source: string, filename: string) {
+  realm.scope(() => {
+    const completion = evalQ((Q) => {
+      if (argv.values.module || filename.endsWith('.mjs')) {
+        const module = Q(realm.createSourceTextModule(filename, source));
+        realm.HostDefined.resolverCache?.set(filename, module);
+        const load = Q(module.LoadRequestedModules());
+        if (load.PromiseState === 'rejected') {
+          Q(Throw(load.PromiseResult!, 'Raw', load.PromiseResult!));
+        } else if (load.PromiseState === 'pending') {
+          throw new Error('Internal error: .LoadRequestedModules() returned a pending promise');
+        }
+        Q(module.Link());
+        const evaluate = Q(module.Evaluate());
+        if (evaluate.PromiseState === 'rejected') {
+          Q(Throw(evaluate.PromiseResult!, 'Raw', evaluate.PromiseResult!));
+        }
+      } else {
+        Q(realm.evaluateScript(source, { specifier: filename }));
+      }
+    });
+    if (completion instanceof AbruptCompletion) {
+      const inspected = inspect(completion);
+      process.stderr.write(`${inspected}\n`);
+      process.exit(1);
+    } else {
+      throw completion;
+    }
+  });
+}
+
+if (argv.positionals[0]) {
+  const source = readFileSync(argv.positionals[0], 'utf8');
+  oneShotEval(source, resolve(argv.positionals[0]));
+} else if (!process.stdin.isTTY) {
+  process.stdin.setEncoding('utf8');
+  let source = '';
+  process.stdin.on('data', (data) => {
+    source += data;
+  });
+  process.stdin.once('end', () => {
+    oneShotEval(source, process.cwd());
+  });
+} else {
+  process.stdout.write(`${packageJson.name} v${packageJson.version}
+Please report bugs to ${packageJson.bugs.url}
+`);
+  start({
+    prompt: '> ',
+    eval: (cmd, _context, _filename, callback) => {
+      try {
+        const result = realm.evaluateScript(cmd, { specifier: '(engine262)' });
+        callback(null, result);
+      } catch (e) {
+        callback(e as Error, null);
+      }
+    },
+    preview: false,
+    completer: () => [],
+    writer: (o) => realm.scope(() => {
+      if (o instanceof Value || o instanceof Completion) {
+        return inspect(o as Value | Completion<unknown>);
+      }
+      return _inspect(o);
+    }),
+  });
+}