warpo 3.1.3 → 3.2.0

package/dist/debug_server/debugSession.js

@@ -1,6 +1,6 @@
 // Copyright (C) 2025 wasm-ecosystem
 // SPDX-License-Identifier: Apache-2.0
-import { LoggingDebugSession, InitializedEvent, Thread, Breakpoint, Source, Scope, StackFrame, LoadedSourceEvent, OutputEvent, StoppedEvent, ContinuedEvent, TerminatedEvent, logger, } from "@vscode/debugadapter";
+import { LoggingDebugSession, InitializedEvent, Thread, Breakpoint, BreakpointEvent, Source, Scope, StackFrame, LoadedSourceEvent, OutputEvent, StoppedEvent, ContinuedEvent, TerminatedEvent, logger, } from "@vscode/debugadapter";
 import assert from "node:assert/strict";
 import { existsSync } from "node:fs";
 import * as path from "node:path";
@@ -9,6 +9,14 @@ import { ARRAY_DATA_START_OFFSET, ARRAY_LENGTH_OFFSET, AS_STRING_CLASS_NAME, OBJ
 import { normalizeDebugPath } from "./debugPath.js";
 import { NodeDebugger } from "./nodeDebugger.js";
 import { loadConfig } from "../test_runner/config.js";
+import { configureTrace, trace } from "./debugTrace.js";
+var StepMode;
+(function (StepMode) {
+    StepMode[StepMode["None"] = 0] = "None";
+    StepMode[StepMode["Into"] = 1] = "Into";
+    StepMode[StepMode["Over"] = 2] = "Over";
+    StepMode[StepMode["Out"] = 3] = "Out";
+})(StepMode || (StepMode = {}));
 function formatUnknownError(error) {
     if (error instanceof Error) {
         return error.message;
@@ -18,6 +26,23 @@ function formatUnknownError(error) {
     }
     return "unknown error";
 }
+const UTF8_CONST_STR_CLASS_NAME = "~lib/warpo/utf8/const_str/ConstStr";
+function isDisplayableStringClass(typeName) {
+    return typeName === AS_STRING_CLASS_NAME || typeName === UTF8_CONST_STR_CLASS_NAME;
+}
+const TYPED_ARRAY_ELEMENT_TYPES = new Map([
+    ["~lib/typedarray/Int8Array", "i8"],
+    ["~lib/typedarray/Uint8Array", "u8"],
+    ["~lib/typedarray/Uint8ClampedArray", "u8"],
+    ["~lib/typedarray/Int16Array", "i16"],
+    ["~lib/typedarray/Uint16Array", "u16"],
+    ["~lib/typedarray/Int32Array", "i32"],
+    ["~lib/typedarray/Uint32Array", "u32"],
+    ["~lib/typedarray/Int64Array", "i64"],
+    ["~lib/typedarray/Uint64Array", "u64"],
+    ["~lib/typedarray/Float32Array", "f32"],
+    ["~lib/typedarray/Float64Array", "f64"],
+]);
 async function resolveUnitTestWasmPath(cwd) {
     const configPath = path.join(cwd, "as-test.config.js");
     let outputFolder = "coverage";
@@ -39,11 +64,15 @@ export class WarpoDebugSession extends LoggingDebugSession {
     nextVariablesReference = 1;
     loadedModule;
     runtime;
+    configurationDone = false;
     stoppedWasmBytecodeOffset;
     stoppedForTrap = false;
+    stepMode = StepMode.None;
+    stepStartSourceLocation;
     debugSessionLogging = false;
     log(msg) {
         logger.log(msg);
+        trace("debug-session", msg);
         if (this.debugSessionLogging) {
             this.sendEvent(new OutputEvent(`${msg}\n`, "stdout"));
         }
@@ -72,12 +101,24 @@ export class WarpoDebugSession extends LoggingDebugSession {
         }
         this.applyPendingBreakpointUpdates(runtime, () => {
             if (info.reason === "other") {
+                if (this.stepMode !== StepMode.None) {
+                    void this.handleStepPause(runtime, info);
+                    return;
+                }
                 void runtime.resume().catch((error) => {
                     const message = error instanceof Error ? error.message : "unknown error";
                     this.log(`Failed to resume after breakpoint update: ${message}`);
                 });
                 return;
             }
+            if (info.reason === "breakpoint" || info.reason === "exception") {
+                this.handleNonStepPause(runtime, info);
+                return;
+            }
+            if (this.stepMode !== StepMode.None) {
+                void this.handleStepPause(runtime, info);
+                return;
+            }
             this.sendStoppedEvent(runtime, info);
         });
     }
@@ -88,33 +129,38 @@ export class WarpoDebugSession extends LoggingDebugSession {
         response.body.supportsBreakpointLocationsRequest = false;
         response.body.supportsLoadedSourcesRequest = true;
         response.body.supportsEvaluateForHovers = false;
+        response.body.supportsTerminateRequest = true;
+        response.body.supportsRestartRequest = true;
         this.sendResponse(response);
         this.sendEvent(new InitializedEvent());
     }
     setBreakPointsRequest(response, args) {
         const sourcePath = normalizeDebugPath(args.source.path || "");
         const clientLines = args.breakpoints || [];
-        const bps = clientLines.map((bp) => {
+        const wasmModule = this.loadedModule;
+        this.log(`SetBreakpoints request: source=${sourcePath}, lines=${clientLines.map((breakpoint) => breakpoint.line).join(",") || "none"}`);
+        const bps = [];
+        for (const bp of clientLines) {
             const id = ++this.breakpointId;
-            const info = {
+            bps.push({
                 id,
                 line: bp.line,
-                verified: true,
+                verified: false,
                 source: sourcePath,
-            };
+            });
             this.log(`Breakpoint set: ${path.basename(sourcePath)}:${bp.line}`);
-            return info;
-        });
+        }
+        if (wasmModule !== undefined) {
+            for (const breakpoint of bps) {
+                breakpoint.verified = wasmModule.resolveBreakpointLocations(breakpoint).length > 0;
+            }
+        }
         this.requestedBreakpointsBySource.set(sourcePath, bps);
         this.pendingBreakpointSources.clear();
         for (const pendingSourcePath of this.requestedBreakpointsBySource.keys()) {
             this.pendingBreakpointSources.add(pendingSourcePath);
         }
-        const breakpoints = bps.map((bp) => {
-            const dbp = new Breakpoint(bp.verified, bp.line);
-            dbp.id = bp.id;
-            return dbp;
-        });
+        const breakpoints = bps.map((bp) => this.toDebugProtocolBreakpoint(bp));
         response.body = { breakpoints };
         if (this.runtime?.isPaused() && this.loadedModule) {
             this.requestBreakpointUpdate(() => this.sendResponse(response));
@@ -125,12 +171,34 @@ export class WarpoDebugSession extends LoggingDebugSession {
         }
     }
     configurationDoneRequest(response, _args) {
+        this.configurationDone = true;
         super.configurationDoneRequest(response, _args);
         this.logAllBreakpoints();
+        this.maybeStartRuntime();
     }
     launchRequest(response, args) {
         void this.doLaunchRequest(response, args);
     }
+    restartRequest(response, _args) {
+        const runtime = this.runtime;
+        if (!runtime) {
+            this.sendErrorResponse(response, 1, "No active runtime to restart");
+            return;
+        }
+        this.log("Restart requested");
+        this.resetRuntimeState();
+        this.queueAllBreakpointUpdates();
+        void this.doRestartRequest(response, runtime);
+    }
+    async doRestartRequest(response, runtime) {
+        try {
+            await runtime.restart();
+            this.sendResponse(response);
+        }
+        catch (error) {
+            this.sendErrorResponse(response, 1, `Restart failed: ${formatUnknownError(error)}`);
+        }
+    }
     async doLaunchRequest(response, args) {
         try {
             this.debugSessionLogging = args.debugSessionLogging ?? false;
@@ -142,6 +210,7 @@ export class WarpoDebugSession extends LoggingDebugSession {
                 return;
             }
             const wasmFilePath = path.resolve(program);
+            configureTrace(args.debugSessionLogFile, cwd);
             this.log(`Launch requested for: ${program}`);
             if (launchType === "wasm file" || launchType === "unittest") {
                 const runtimeName = args.runtime ?? "node";
@@ -156,6 +225,7 @@ export class WarpoDebugSession extends LoggingDebugSession {
                 runtime.onModuleLoad = (wasmModule) => {
                     this.loadedModule = wasmModule;
                     this.log(`Wasm module loaded: ${wasmModule.wasmFilePath} (reported as ${wasmModule.url}, scriptId: ${wasmModule.scriptId})`);
+                    this.log(`Module load breakpoint state: requestedSources=${this.requestedBreakpointsBySource.size}, pendingSources=${this.pendingBreakpointSources.size}`);
                     this.sendEvent(new LoadedSourceEvent("new", {
                         name: path.basename(wasmModule.wasmFilePath),
                         path: wasmModule.wasmFilePath,
@@ -164,16 +234,7 @@ export class WarpoDebugSession extends LoggingDebugSession {
                         name: path.basename(wasmModule.sourceMapFilePath),
                         path: wasmModule.sourceMapFilePath,
                     }));
-                    this.applyPendingBreakpointUpdates(runtime, () => {
-                        if (runtime.isPaused()) {
-                            void runtime.resume().catch((error) => {
-                                const message = error instanceof Error ? error.message : "unknown error";
-                                this.log(`Failed to resume after module load: ${message}`);
-                            });
-                            return;
-                        }
-                        runtime.finishModuleLoad();
-                    });
+                    this.applyPendingBreakpointUpdates(runtime, () => this.maybeStartRuntime());
                 };
                 runtime.onPause = (info) => {
                     this.handleRuntimePause(runtime, info);
@@ -188,7 +249,6 @@ export class WarpoDebugSession extends LoggingDebugSession {
                     this.log(message);
                 };
                 this.disposeLoadedModule();
-                this.runtime?.dispose();
                 this.runtime = runtime;
                 await runtime.launch(launchType === "unittest"
                     ? {
@@ -236,9 +296,52 @@ export class WarpoDebugSession extends LoggingDebugSession {
     continueRequest(response, _args) {
         this.doContinueRequest(response);
     }
+    stepInRequest(response, _args) {
+        this.doStepRequest(response, StepMode.Into);
+    }
+    nextRequest(response, _args) {
+        this.doStepRequest(response, StepMode.Over);
+    }
+    pauseRequest(response, _args) {
+        const runtime = this.runtime;
+        if (!runtime) {
+            this.sendErrorResponse(response, 1, "No active runtime");
+            return;
+        }
+        if (runtime.isPaused()) {
+            this.sendResponse(response);
+            return;
+        }
+        this.cancelStep();
+        // StepMode.Into is used as a sentinel to reuse the step-pause handling path; no actual step-in is performed.
+        this.stepMode = StepMode.Into;
+        this.stepStartSourceLocation = undefined;
+        this.clearVariableContainers();
+        runtime.pause();
+        this.sendResponse(response);
+    }
+    terminateRequest(response, _args) {
+        const runtime = this.runtime;
+        if (runtime) {
+            void this.disposeRuntimeAndTerminate(runtime);
+        }
+        this.sendResponse(response);
+    }
+    stepOutRequest(response, _args) {
+        this.doStepRequest(response, StepMode.Out);
+    }
     disconnectRequest(response, _args) {
-        this.runtime?.dispose();
+        void this.doDisconnectRequest(response);
+    }
+    async doDisconnectRequest(response) {
+        const runtime = this.runtime;
         this.runtime = undefined;
+        try {
+            await runtime?.dispose();
+        }
+        catch (error) {
+            this.log(`Failed to dispose runtime: ${formatUnknownError(error)}`);
+        }
         this.resetRuntimeState();
         this.debugSessionLogging = false;
         this.dispose();
@@ -301,6 +404,16 @@ export class WarpoDebugSession extends LoggingDebugSession {
                 response.body = { variables: await this.decodeObjectAtAddress(variableContainer.address) };
                 break;
             }
+            case "variables": {
+                response.body = { variables: variableContainer.variables };
+                break;
+            }
+            case "closure-scopes": {
+                response.body = {
+                    variables: await this.resolveClosureScopeVariables(variableContainer.functionName, variableContainer.envAddress, variableContainer.scopeLevels),
+                };
+                break;
+            }
             case "map-entry": {
                 response.body = {
                     variables: [variableContainer.key, variableContainer.value].map((variable) => this.toDebugProtocolVariable(variable)),
@@ -366,24 +479,78 @@ export class WarpoDebugSession extends LoggingDebugSession {
         }
         const sourceVariables = sourceVariableScope.variables;
         const rawWasmValues = await this.resolveRawWasmValues(sourceVariables, runtimeVariablesByIndex, runtime);
-        const closureTupleValuesByLevel = await this.readClosureTupleChain(sourceVariableScope.rootClosureEnvLocalIndex, runtimeVariablesByIndex);
-        const scopeTupleLevel = sourceVariableScope.tupleLevel ?? 0;
-        const rawLocalValues = sourceVariables.map((variable) => {
-            if (variable.kind === "closure") {
-                const elementIndex = variable.fieldOffset / SMALL_TUPLE_SLOT_SIZE;
-                const levelValues = closureTupleValuesByLevel.get(scopeTupleLevel);
-                const tupleRawValue = levelValues?.get(elementIndex);
-                if (tupleRawValue === undefined) {
-                    return { name: variable.name, value: "<unavailable>", typeName: variable.typeName };
+        const firstTupleAddress = this.resolveClosureTupleAddress(sourceVariableScope.rootClosureEnvLocalIndex, runtimeVariablesByIndex);
+        const decodedScopes = await this.decodeScopeChainVariables([sourceVariableScope], firstTupleAddress, rawWasmValues);
+        return decodedScopes[0] ?? [];
+    }
+    async decodeScopeChainVariables(scopeLevels, firstTupleAddress, rawWasmValues) {
+        const closureTupleValuesByLevel = new Map();
+        const visitedAddresses = new Set();
+        if (firstTupleAddress !== undefined && Number.isInteger(firstTupleAddress) && firstTupleAddress > 0) {
+            let currentAddress = firstTupleAddress;
+            let tupleLevel = 0;
+            while (!visitedAddresses.has(currentAddress)) {
+                visitedAddresses.add(currentAddress);
+                const tupleValues = await this.readTupleElementValues(currentAddress);
+                const levelValues = new Map();
+                for (const [index, value] of tupleValues.entries()) {
+                    levelValues.set(index, value.value);
+                }
+                closureTupleValuesByLevel.set(tupleLevel, levelValues);
+                const parentTuple = tupleValues[0];
+                if (!parentTuple) {
+                    break;
+                }
+                const parentAddress = Number(parentTuple.value);
+                if (!Number.isInteger(parentAddress) || parentAddress <= 0) {
+                    break;
                 }
-                return { name: variable.name, value: tupleRawValue, typeName: variable.typeName };
+                currentAddress = parentAddress;
+                tupleLevel++;
             }
-            const wasmRawValue = rawWasmValues.get(variable);
-            assert(wasmRawValue !== undefined);
-            return { name: variable.name, value: wasmRawValue, typeName: variable.typeName };
+        }
+        return Promise.all(scopeLevels.map(async (scopeLevel) => {
+            const rawLocalValues = scopeLevel.variables.map((variable) => {
+                if (variable.kind === "closure") {
+                    const elementIndex = variable.fieldOffset / SMALL_TUPLE_SLOT_SIZE;
+                    const levelValues = closureTupleValuesByLevel.get(scopeLevel.tupleLevel ?? 0);
+                    const tupleRawValue = levelValues?.get(elementIndex);
+                    if (tupleRawValue === undefined) {
+                        return { name: variable.name, value: "<unavailable>", typeName: variable.typeName };
+                    }
+                    return { name: variable.name, value: tupleRawValue, typeName: variable.typeName };
+                }
+                const wasmRawValue = rawWasmValues.get(variable);
+                return {
+                    name: variable.name,
+                    value: wasmRawValue ?? "<unavailable>",
+                    typeName: variable.typeName,
+                };
+            });
+            const variables = await Promise.all(rawLocalValues.map((variable) => this.toDebugSessionVariableValue(variable.name, variable.typeName, variable.value)));
+            return variables.map((variable) => this.toDebugProtocolVariable(variable));
+        }));
+    }
+    async resolveClosureScopeVariables(functionName, envAddress, scopeLevels) {
+        const wasmModule = this.loadedModule;
+        if (!wasmModule) {
+            this.log(`Warning: cannot expand closure scopes for ${functionName}: wasm module is not loaded`);
+            return [];
+        }
+        if (!scopeLevels) {
+            this.log(`Warning: cannot expand closure scopes for ${functionName}: DWARF function is unavailable`);
+            return [];
+        }
+        const decodedScopeVariables = await this.decodeScopeChainVariables(scopeLevels, envAddress, new Map());
+        return scopeLevels.map((scopeLevel, index) => {
+            const variable = {
+                kind: "synthetic",
+                name: index.toString(),
+                value: scopeLevel.name,
+                container: { kind: "variables", variables: decodedScopeVariables[index] ?? [] },
+            };
+            return this.toDebugProtocolVariable(variable);
         });
-        const variables = await Promise.all(rawLocalValues.map((variable) => this.toDebugSessionVariableValue(variable.name, variable.typeName, variable.value)));
-        return variables.map((variable) => this.toDebugProtocolVariable(variable));
     }
     async decodeObjectAtAddress(address) {
         const fields = await this.resolveObjectFields(address);
@@ -408,39 +575,16 @@ export class WarpoDebugSession extends LoggingDebugSession {
         }
         return rawWasmValues;
     }
-    async readClosureTupleChain(closureEnvLocalIndex, runtimeVariablesByIndex) {
-        const closureTupleValuesByLevel = new Map();
+    resolveClosureTupleAddress(closureEnvLocalIndex, runtimeVariablesByIndex) {
         if (closureEnvLocalIndex === undefined) {
-            return closureTupleValuesByLevel;
+            return undefined;
         }
         const closureEnvVariable = runtimeVariablesByIndex.get(closureEnvLocalIndex);
         if (closureEnvVariable === undefined) {
-            return closureTupleValuesByLevel;
-        }
-        let address = Number(closureEnvVariable.value);
-        if (!Number.isInteger(address) || address <= 0) {
-            return closureTupleValuesByLevel;
-        }
-        let level = 0;
-        while (true) {
-            const tupleValues = await this.readTupleElementValues(address);
-            const levelValues = new Map();
-            for (const [index, value] of tupleValues.entries()) {
-                levelValues.set(index, value.value);
-            }
-            closureTupleValuesByLevel.set(level, levelValues);
-            const parentAddress = levelValues.get(0);
-            if (parentAddress === undefined) {
-                break;
-            }
-            const parentAddressNumber = Number(parentAddress);
-            if (!Number.isInteger(parentAddressNumber) || parentAddressNumber <= 0) {
-                break;
-            }
-            address = parentAddressNumber;
-            level++;
+            return undefined;
         }
-        return closureTupleValuesByLevel;
+        const address = Number(closureEnvVariable.value);
+        return Number.isInteger(address) && address > 0 ? address : undefined;
     }
     resolvePausedStackFrame(frameId) {
         return this.pausedStackFramesById.get(frameId);
@@ -452,7 +596,7 @@ export class WarpoDebugSession extends LoggingDebugSession {
         if (typeName !== undefined) {
             const objectAddress = this.parseObjectAddress(typeName, value);
             if (objectAddress) {
-                if (typeName === AS_STRING_CLASS_NAME) {
+                if (isDisplayableStringClass(typeName)) {
                     const stringValue = await this.decodeStringAtAddress(typeName, objectAddress);
                     return this.createClassVariable(name, typeName, objectAddress, stringValue);
                 }
@@ -487,12 +631,18 @@ export class WarpoDebugSession extends LoggingDebugSession {
             case "map-entry": {
                 return "";
             }
+            case "synthetic": {
+                return variable.value;
+            }
         }
     }
     getVariableReference(variable, isExpandableClass) {
         if (isExpandableClass && variable.kind === "class") {
             return this.toObjectVariablesReference(variable.address);
         }
+        if (variable.kind === "synthetic") {
+            return variable.container === undefined ? 0 : this.createVariableContainer(variable.container);
+        }
         if (variable.kind === "map-entry") {
             return this.createVariableContainer({ kind: "map-entry", key: variable.key, value: variable.value });
         }
@@ -502,7 +652,7 @@ export class WarpoDebugSession extends LoggingDebugSession {
         return { kind: "class", name, typeName, address, displayValue };
     }
     parseObjectAddress(typeName, value) {
-        if (!this.loadedModule?.getClassLayout(typeName)) {
+        if (typeName !== UTF8_CONST_STR_CLASS_NAME && !this.loadedModule?.getClassLayout(typeName)) {
             return undefined;
         }
         const address = Number(value);
@@ -599,9 +749,16 @@ export class WarpoDebugSession extends LoggingDebugSession {
             return [];
         }
         const view = new DataView(memory.buffer, memory.byteOffset, memory.byteLength);
+        if (classLayout.builtinKind === BuiltinContainerKind.Function) {
+            return this.decodeFunctionElements(view, classLayout);
+        }
         if (classLayout.builtinKind === BuiltinContainerKind.ArrayBuffer) {
             return this.decodeArrayBufferElements(view);
         }
+        const typedArrayElementType = TYPED_ARRAY_ELEMENT_TYPES.get(classLayout.name);
+        if (typedArrayElementType !== undefined) {
+            return this.decodeTypedArrayElements(address, view, classLayout, typedArrayElementType);
+        }
         if (classLayout.builtinKind === BuiltinContainerKind.Array) {
             return this.decodeArrayElements(address, view, classLayout);
         }
@@ -616,10 +773,49 @@ export class WarpoDebugSession extends LoggingDebugSession {
         }
         return Promise.all(classLayout.fields.map((field) => this.decodeFieldVariable(view, field)));
     }
+    decodeFunctionElements(view, classLayout) {
+        const indexField = classLayout.fields.find((field) => field.name === "_index" || field.name === "index");
+        let functionName;
+        if (indexField) {
+            const indexValue = this.decodeFieldValue(view, indexField);
+            const functionIndex = Number(indexValue);
+            if (Number.isInteger(functionIndex) && functionIndex >= 0) {
+                functionName = this.loadedModule?.getFunctionNameByTableIndex(functionIndex);
+            }
+        }
+        else {
+            this.log(`Warning: cannot expand function: index field is unavailable`);
+        }
+        const envField = classLayout.fields.find((field) => field.name === "_env" || field.name === "env");
+        let envAddress;
+        if (envField) {
+            const envValue = Number(this.decodeFieldValue(view, envField));
+            if (Number.isInteger(envValue) && envValue > 0) {
+                envAddress = envValue;
+            }
+        }
+        else {
+            this.log(`Warning: cannot expand function: env field is unavailable`);
+        }
+        const closureScopes = functionName === undefined ? undefined : this.loadedModule?.getClosureVariableScopesByFunctionName(functionName);
+        return [
+            { kind: "basic", name: "name", value: functionName ?? "<unavailable>", typeName: "string" },
+            {
+                kind: "synthetic",
+                name: "[[scopes]]",
+                value: `Scopes[${closureScopes?.length ?? 0}]`,
+                typeName: "Scopes",
+                container: functionName === undefined || envAddress === undefined
+                    ? undefined
+                    : { kind: "closure-scopes", functionName, envAddress, scopeLevels: closureScopes },
+            },
+        ];
+    }
     async resolveRuntimeObjectPayloadSize(address, classLayout) {
         if (classLayout.builtinKind !== BuiltinContainerKind.SmallTuple &&
             classLayout.builtinKind !== BuiltinContainerKind.StaticArray &&
-            classLayout.builtinKind !== BuiltinContainerKind.ArrayBuffer) {
+            classLayout.builtinKind !== BuiltinContainerKind.ArrayBuffer &&
+            !TYPED_ARRAY_ELEMENT_TYPES.has(classLayout.name)) {
             return classLayout.byteSize;
         }
         const sizeMemory = await this.runtime?.readWasmMemory(address + OBJECT_RTSIZE_OFFSET, OBJECT_RTSIZE_SIZE);
@@ -659,7 +855,7 @@ export class WarpoDebugSession extends LoggingDebugSession {
             this.log(`Error: cannot expand tuple reference at ${elementAddress}: runtime class layout is missing`);
             return { kind: "basic", name, value: elementAddress.toString(), typeName: undefined };
         }
-        if (classLayout.name === AS_STRING_CLASS_NAME) {
+        if (isDisplayableStringClass(classLayout.name)) {
             const stringValue = await this.decodeStringAtAddress(classLayout.name, elementAddress);
             return this.createClassVariable(name, classLayout.name, elementAddress, stringValue);
         }
@@ -699,6 +895,32 @@ export class WarpoDebugSession extends LoggingDebugSession {
         }
         return elements;
     }
+    async decodeTypedArrayElements(address, view, classLayout, elementTypeName) {
+        const dataStartField = classLayout.fields.find((field) => field.name === "dataStart");
+        const byteLengthField = classLayout.fields.find((field) => field.name === "byteLength");
+        if (!dataStartField || !byteLengthField) {
+            this.log(`Error: cannot expand typed array at ${address}: typed array header is unavailable`);
+            return [];
+        }
+        const dataStart = Number(this.decodeFieldValue(view, dataStartField));
+        const byteLength = Number(this.decodeFieldValue(view, byteLengthField));
+        const elementSize = resolveArrayElementSize(elementTypeName, false);
+        if (!Number.isInteger(dataStart) ||
+            dataStart < 0 ||
+            !Number.isInteger(byteLength) ||
+            byteLength < 0 ||
+            byteLength % elementSize !== 0) {
+            this.log(`Error: cannot expand typed array at ${address}: typed array data is invalid`);
+            return [];
+        }
+        const elementsMemory = await this.runtime?.readWasmMemory(dataStart, byteLength);
+        if (!elementsMemory) {
+            this.log(`Error: cannot expand typed array at ${address}: typed array data is unavailable`);
+            return [];
+        }
+        const elementsView = new DataView(elementsMemory.buffer, elementsMemory.byteOffset, elementsMemory.byteLength);
+        return this.decodeArrayElementVariables(elementsView, byteLength / elementSize, elementTypeName, elementSize, false);
+    }
     async decodeStaticArrayElements(address, view, classLayout) {
         assert.equal(classLayout.builtinKind, BuiltinContainerKind.StaticArray);
         const elementTypeName = classLayout.templateType;
@@ -857,7 +1079,7 @@ export class WarpoDebugSession extends LoggingDebugSession {
         const value = this.decodeFieldValue(view, field);
         const address = field.isReference ? this.parseObjectAddress(field.typeName, value) : undefined;
         if (address) {
-            if (field.typeName === AS_STRING_CLASS_NAME) {
+            if (isDisplayableStringClass(field.typeName)) {
                 const stringValue = await this.decodeStringAtAddress(field.typeName, address);
                 return this.createClassVariable(field.name, field.typeName, address, stringValue);
             }
@@ -939,7 +1161,7 @@ export class WarpoDebugSession extends LoggingDebugSession {
         }
     }
     async decodeStringAtAddress(typeName, address) {
-        assert.equal(typeName, AS_STRING_CLASS_NAME);
+        assert.ok(isDisplayableStringClass(typeName));
         if (!this.runtime) {
             this.log(`Error: cannot decode string at ${address}: runtime is not active`);
             return "<unavailable>";
@@ -956,7 +1178,8 @@ export class WarpoDebugSession extends LoggingDebugSession {
             this.log(`Error: cannot decode string at ${address}: string payload memory is unavailable`);
             return "<unavailable>";
         }
-        return JSON.stringify(Buffer.from(stringMemory).toString("utf16le"));
+        const encoding = typeName === UTF8_CONST_STR_CLASS_NAME ? "utf8" : "utf16le";
+        return JSON.stringify(Buffer.from(stringMemory).toString(encoding));
     }
     doContinueRequest(response) {
         const runtime = this.runtime;
@@ -965,13 +1188,107 @@ export class WarpoDebugSession extends LoggingDebugSession {
             return;
         }
         response.body = { allThreadsContinued: true };
-        this.sendResponse(response);
         if (this.stoppedForTrap) {
+            this.sendResponse(response);
             this.log("Continue requested from wasm trap; terminating debug session");
-            this.disposeRuntimeAndTerminate(runtime);
+            void this.disposeRuntimeAndTerminate(runtime);
             return;
         }
+        this.cancelStep();
         void this.resumeRuntime(runtime);
+        this.sendResponse(response);
+    }
+    doStepRequest(response, mode) {
+        const runtime = this.runtime;
+        if (!runtime) {
+            this.sendErrorResponse(response, 1, "No active runtime");
+            return;
+        }
+        if (!runtime.isPaused()) {
+            this.sendErrorResponse(response, 1, "Runtime is not paused");
+            return;
+        }
+        if (this.stoppedForTrap) {
+            this.sendResponse(response);
+            this.log("Step requested from wasm trap; terminating debug session");
+            void this.disposeRuntimeAndTerminate(runtime);
+            return;
+        }
+        this.stepMode = mode;
+        this.stepStartSourceLocation = this.resolveSourceLocation(this.stoppedWasmBytecodeOffset);
+        this.clearVariableContainers();
+        this.sendResponse(response);
+        this.sendEvent(new ContinuedEvent(WarpoDebugSession.threadId, true));
+        void this.advanceStep(runtime).catch((error) => {
+            this.handleStepFailure(error);
+        });
+    }
+    async handleStepPause(runtime, info) {
+        try {
+            if (this.hasReachedNextSourceLine(info.wasmBytecodeOffset)) {
+                this.completeStep(runtime, info);
+                return;
+            }
+            await this.advanceStep(runtime);
+        }
+        catch (error) {
+            this.handleStepFailure(error);
+        }
+    }
+    handleNonStepPause(runtime, info) {
+        this.cancelStep();
+        if (this.runtime !== runtime) {
+            return;
+        }
+        this.sendStoppedEvent(runtime, info);
+    }
+    hasReachedNextSourceLine(wasmBytecodeOffset) {
+        const sourceLocation = this.resolveSourceLocation(wasmBytecodeOffset);
+        if (!sourceLocation) {
+            return false;
+        }
+        const startSourceLocation = this.stepStartSourceLocation;
+        return (startSourceLocation === undefined ||
+            sourceLocation.sourcePath !== startSourceLocation.sourcePath ||
+            sourceLocation.sourceLine !== startSourceLocation.sourceLine);
+    }
+    async advanceStep(runtime) {
+        if (this.runtime !== runtime || this.stepMode === StepMode.None) {
+            return;
+        }
+        const wasmModule = this.loadedModule;
+        const wasmBytecodeOffset = this.stoppedWasmBytecodeOffset;
+        if (this.stepMode === StepMode.Out) {
+            this.stepMode = StepMode.Into;
+            await runtime.stepOut();
+        }
+        else if (this.stepMode === StepMode.Over &&
+            wasmModule &&
+            wasmBytecodeOffset !== undefined &&
+            wasmModule.getNextBytecodeOffsetAfterCall(wasmBytecodeOffset) !== undefined) {
+            await runtime.stepOver();
+        }
+        else {
+            // Source-level stepping advances through runtime primitives until the source location changes. Calls use the
+            // runtime's call-aware operation because their following bytecode may be a structural `end`, not an executable instruction.
+            await runtime.stepInstruction();
+        }
+    }
+    completeStep(runtime, info) {
+        this.cancelStep();
+        if (this.runtime !== runtime) {
+            return;
+        }
+        this.clearVariableContainers();
+        this.sendStoppedEvent(runtime, info);
+    }
+    handleStepFailure(error) {
+        this.log(`Step failed: ${formatUnknownError(error)}`);
+        this.cancelStep();
+    }
+    cancelStep() {
+        this.stepMode = StepMode.None;
+        this.stepStartSourceLocation = undefined;
     }
     async resumeRuntime(runtime) {
         try {
@@ -992,13 +1309,18 @@ export class WarpoDebugSession extends LoggingDebugSession {
         if (this.runtime !== runtime) {
             return;
         }
-        this.disposeRuntimeAndTerminate(runtime);
+        void this.disposeRuntimeAndTerminate(runtime);
     }
-    disposeRuntimeAndTerminate(runtime) {
-        runtime.dispose();
+    async disposeRuntimeAndTerminate(runtime) {
         if (this.runtime === runtime) {
             this.runtime = undefined;
         }
+        try {
+            await runtime.dispose();
+        }
+        catch (error) {
+            this.log(`Failed to dispose runtime: ${formatUnknownError(error)}`);
+        }
         this.resetRuntimeState();
         this.sendEvent(new TerminatedEvent());
     }
@@ -1007,6 +1329,13 @@ export class WarpoDebugSession extends LoggingDebugSession {
         this.pendingBreakpointSources.clear();
         this.stoppedWasmBytecodeOffset = undefined;
         this.stoppedForTrap = false;
+        this.stepMode = StepMode.None;
+        this.stepStartSourceLocation = undefined;
+    }
+    queueAllBreakpointUpdates() {
+        for (const sourcePath of this.requestedBreakpointsBySource.keys()) {
+            this.pendingBreakpointSources.add(sourcePath);
+        }
     }
     logAllBreakpoints() {
         this.log("=== Registered Breakpoints ===");
@@ -1017,8 +1346,15 @@ export class WarpoDebugSession extends LoggingDebugSession {
         }
         this.log("==============================");
     }
+    toDebugProtocolBreakpoint(breakpoint) {
+        const dbp = new Breakpoint(breakpoint.verified, breakpoint.line);
+        dbp.id = breakpoint.id;
+        return dbp;
+    }
     requestBreakpointUpdate(onComplete) {
+        this.log(`Breakpoint update requested: hasRuntime=${this.runtime !== undefined}, hasModule=${this.loadedModule !== undefined}, pendingSources=${this.pendingBreakpointSources.size}, runtimePaused=${this.runtime?.isPaused() ?? false}`);
         if (!this.runtime || !this.loadedModule || this.pendingBreakpointSources.size === 0) {
+            this.log("Breakpoint update skipped: runtime, module, or pending source is unavailable");
             onComplete?.();
             return;
         }
@@ -1028,33 +1364,40 @@ export class WarpoDebugSession extends LoggingDebugSession {
         }
         this.runtime.pause();
     }
+    maybeStartRuntime() {
+        const runtime = this.runtime;
+        if (!this.configurationDone || !runtime || !this.loadedModule) {
+            return;
+        }
+        if (runtime.isPaused()) {
+            void runtime.resume().catch((error) => {
+                const message = error instanceof Error ? error.message : "unknown error";
+                this.log(`Failed to resume after configuration: ${message}`);
+            });
+            return;
+        }
+        runtime.finishModuleLoad();
+    }
     applyPendingBreakpointUpdates(runtime, onComplete) {
         const wasmModule = this.loadedModule;
         if (!wasmModule) {
+            this.log("Breakpoint update skipped: no loaded wasm module");
             onComplete?.();
             return;
         }
         if (this.pendingBreakpointSources.size === 0) {
+            this.log("Breakpoint update skipped: no pending breakpoint sources");
             onComplete?.();
             return;
         }
+        this.log(`Applying breakpoint updates: requestedSources=${this.requestedBreakpointsBySource.size}, pendingSources=${this.pendingBreakpointSources.size}`);
         this.pendingBreakpointSources.clear();
-        const wasmBytecodeOffsets = new Set();
-        for (const [sourcePath, breakpoints] of this.requestedBreakpointsBySource) {
-            for (const breakpoint of breakpoints) {
-                const breakpointLocations = wasmModule.resolveBreakpointLocations(breakpoint);
-                if (breakpointLocations.length === 0) {
-                    this.log(`No source-map match for breakpoint ${path.basename(sourcePath)}:${breakpoint.line}`);
-                }
-                for (const location of breakpointLocations) {
-                    wasmBytecodeOffsets.add(location.wasmBytecodeOffset);
-                    this.log(`Resolved breakpoint ${path.basename(sourcePath)}:${breakpoint.line} -> ${location.wasmBytecodeOffset}`);
-                }
-            }
-        }
+        const wasmBytecodeOffsets = this.collectBreakpointOffsets(wasmModule);
         runtime.setWasmBreakpoints(wasmModule, Array.from(wasmBytecodeOffsets).toSorted((left, right) => left - right), {
             onSuccess: () => {
-                this.log(`Breakpoint set installed: ${wasmBytecodeOffsets.size} locations`);
+                this.log(`Breakpoint set installed: ${wasmBytecodeOffsets.size} locations, offsets=${Array.from(wasmBytecodeOffsets)
+                    .toSorted((left, right) => left - right)
+                    .join(",") || "none"}`);
                 onComplete?.();
             },
             onError: (error) => {
@@ -1063,6 +1406,32 @@ export class WarpoDebugSession extends LoggingDebugSession {
             },
         });
     }
+    collectBreakpointOffsets(wasmModule) {
+        const wasmBytecodeOffsets = new Set();
+        for (const [sourcePath, breakpoints] of this.requestedBreakpointsBySource) {
+            for (const breakpoint of breakpoints) {
+                this.collectBreakpointLocations(wasmModule, sourcePath, breakpoint, wasmBytecodeOffsets);
+            }
+        }
+        return wasmBytecodeOffsets;
+    }
+    collectBreakpointLocations(wasmModule, sourcePath, breakpoint, wasmBytecodeOffsets) {
+        const sourceMapHasSource = wasmModule.hasSource(sourcePath);
+        this.log(`Resolving breakpoint: source=${sourcePath}, line=${breakpoint.line}, sourceMapHasSource=${sourceMapHasSource}`);
+        const breakpointLocations = wasmModule.resolveBreakpointLocations(breakpoint);
+        if (breakpointLocations.length > 0 && !breakpoint.verified) {
+            breakpoint.verified = true;
+            this.sendEvent(new BreakpointEvent("changed", this.toDebugProtocolBreakpoint(breakpoint)));
+        }
+        if (breakpointLocations.length === 0) {
+            this.log(`Source-map lookup failed for breakpoint ${path.basename(sourcePath)}:${breakpoint.line}: ${sourceMapHasSource ? "source present but line has no mapping" : "source is absent"}`);
+        }
+        this.log(`Breakpoint resolution result: source=${sourcePath}, line=${breakpoint.line}, locations=${breakpointLocations.length}, offsets=${breakpointLocations.map((location) => location.wasmBytecodeOffset).join(",") || "none"}`);
+        for (const location of breakpointLocations) {
+            wasmBytecodeOffsets.add(location.wasmBytecodeOffset);
+            this.log(`Resolved breakpoint ${path.basename(sourcePath)}:${breakpoint.line} -> ${location.wasmBytecodeOffset}`);
+        }
+    }
     disposeLoadedModule() {
         this.clearVariableContainers();
         this.loadedModule?.dispose();