Documentation: Add debugging and profiling articles

Author: kateinoigakukun

Sources/JavaScriptKit/Documentation.docc/Articles/Debugging.md

@@ -0,0 +1,59 @@
+# Debugging
+
+Debug your Swift applications running on JavaScript environment using DWARF-based debugging tools, including Chrome DevTools extensions and command-line debuggers.
+
+## Overview
+
+These debugging tools are DWARF-based, so you need to build your application with DWARF sections enabled.
+
+Build your application with debug configuration using:
+
+```bash
+swift package --swift-sdk $SWIFT_SDK_ID js -c debug
+```
+
+Alternatively, you can omit the `-c debug` flag since the `js` plugin builds with debug configuration by default:
+
+```bash
+swift package --swift-sdk $SWIFT_SDK_ID js
+```
+
+## Chrome DevTools
+
+When debugging a web browser application, Chrome DevTools provides a powerful debugging environment. It allows you to set breakpoints and step through your Swift source code at the source level.
+
+There are two DWARF extensions available for Chrome DevTools: an enhanced extension specifically designed for Swift, and the official C/C++ extension. For Swift development, the enhanced extension is recommended.
+
+> Important: The two extensions cannot coexist. You must use only one extension at a time.
+
+### Enhanced DWARF Extension for Swift
+
+For the best Swift debugging experience, use the enhanced DWARF extension that provides:
+
+- Breakpoint setting and Swift code inspection
+- Human-readable call stack frames
+- Swift variable value inspection
+
+![Chrome DevTools with Swift support](chrome-devtools-swift.png)
+
+To install this enhanced extension:
+
+1. If you have the official "C/C++ DevTools Support (DWARF)" extension installed, uninstall it first
+2. Download the extension ZIP file from [GitHub Releases](https://github.com/GoodNotes/devtools-frontend/releases/tag/swift-0.2.3.0)
+3. Go to `chrome://extensions/` and enable "Developer mode"
+4. Drag and drop the downloaded ZIP file into the page
+
+When you close and reopen the DevTools window, DevTools will suggest reloading itself to apply settings.
+
+> Note: There is a known issue where some JavaScriptKit types like `JSObject` and `JSValue` are not shown in pretty format in the variables view.
+
+### Official DWARF Extension
+
+Alternatively, you can use the official [`C/C++ DevTools Support (DWARF)`](https://goo.gle/wasm-debugging-extension) extension. However, it has limitations for Swift development:
+
+- Function names in the stack trace are mangled (you can demangle them using `swift demangle` command)
+- Variable inspection is unavailable since Swift depends on its own mechanisms instead of DWARF's structure type feature
+
+![Chrome DevTools](chrome-devtools.png)
+
+See [the DevTools team's official introduction](https://developer.chrome.com/blog/wasm-debugging-2020) for more details about the extension.

Sources/JavaScriptKit/Documentation.docc/Articles/Deploying-Pages.md

@@ -11,7 +11,7 @@ Once you've built your application with JavaScriptKit, you'll need to deploy it
 Build your application using [Vite](https://vite.dev/) build tool:
 
 ```bash
-# Build the Swift package for WebAssembly
+# Build the Swift package for WebAssembly with release configuration
 $ swift package --swift-sdk wasm32-unknown-wasi js -c release
 
 # Create a minimal HTML file (if you don't have one)

Sources/JavaScriptKit/Documentation.docc/Articles/JavaScript-Environment-Requirements.md

@@ -1,5 +1,7 @@
 # JavaScript Environment Requirements
 
+Understand the JavaScript features required by JavaScriptKit and ensure your target environment supports them.
+
 ## Required JavaScript Features
 
 The JavaScript package produced by the JavaScriptKit packaging plugin requires the following JavaScript features:

Sources/JavaScriptKit/Documentation.docc/Articles/Profiling-Memory-Usage.md

@@ -0,0 +1,37 @@
+# Profiling Memory Usage
+
+Profile memory usage of your Swift applications running on JavaScript environment to identify memory leaks and understand memory allocation patterns.
+
+## Overview
+
+Memory profiling helps you understand how your application uses memory, identify memory leaks, and optimize memory allocation patterns. This guide covers tools and techniques for profiling memory usage in Swift applications running on JavaScript environment.
+
+When profiling memory usage, start with JavaScript execution environment's heap profiler. If `WebAssembly.Memory` objects are the bottleneck, use specialized WebAssembly memory profilers that understand the Wasm instance's memory allocator.
+
+## Chrome DevTools Heap Snapshots
+
+Start by using Chrome DevTools' built-in heap profiler to understand overall memory usage in your application. See [Chrome DevTools documentation on heap snapshots](https://developer.chrome.com/docs/devtools/memory-problems/heap-snapshots) for detailed instructions.
+
+## wasm-memprof
+
+If `WebAssembly.Memory` objects are the bottleneck, JavaScript engine's default profiler typically doesn't track allocations within WebAssembly's memory space, so you won't get good insights. In such cases, use a profiler like [wasm-memprof](https://github.com/kateinoigakukun/wasm-memprof) that understands the Wasm instance's memory allocator.
+
+wasm-memprof is a heap profiler specifically designed for WebAssembly applications. It provides detailed memory allocation tracking with Swift symbol demangling support, helping you identify memory leaks and understand memory usage patterns within WebAssembly's linear memory.
+
+![wasm-memprof visualization](https://raw.githubusercontent.com/kateinoigakukun/wasm-memprof/main/docs/demo.png)
+
+### Setup
+
+Add wasm-memprof to your application before instantiating your Wasm program:
+
+```javascript
+import { WMProf } from "wasm-memprof";
+import { SwiftDemangler } from "wasm-memprof/plugins/swift-demangler.js";
+
+const swiftDemangler = SwiftDemangler.create();
+globalThis.WebAssembly = WMProf.wrap(globalThis.WebAssembly, {
+  demangler: swiftDemangler.demangle.bind(swiftDemangler),
+});
+```
+
+Check the [wasm-memprof repository](https://github.com/kateinoigakukun/wasm-memprof) for detailed documentation and examples.

Sources/JavaScriptKit/Documentation.docc/Articles/Profiling-Performance-Issues.md

@@ -0,0 +1,51 @@
+# Profiling Performance Issues
+
+Profile your Swift applications running on JavaScript environment to identify performance bottlenecks using Chrome DevTools and other profiling tools.
+
+## Overview
+
+Profiling helps you understand where your application spends time. This guide covers tools and techniques for profiling Swift applications running on JavaScript environment, focusing on performance profiling. For memory profiling, see <doc:Profiling-Memory-Usage>.
+
+## Chrome DevTools Performance Tab
+
+Chrome DevTools provides a built-in Performance profiler that can help you identify performance bottlenecks in your WebAssembly application. See [Chrome DevTools documentation on performance profiling](https://developer.chrome.com/docs/devtools/performance) for detailed instructions.
+
+![Chrome DevTools Performance Tab](chrome-devtools-perf.png)
+
+> Note: WebAssembly function names may appear mangled in the performance timeline. You can use `swift demangle` to decode them, or use the enhanced DWARF extension mentioned in <doc:Debugging> for better symbol resolution.
+
+### V8 Compilation Pipeline Considerations
+
+When DevTools is open, V8's WebAssembly compilation pipeline behaves differently:
+
+- **With DevTools open**: V8 replaces optimized TurboFan code with unoptimized Liftoff code for debugging purposes. This means performance measurements taken while DevTools is open will not reflect actual production performance.
+
+- **With Performance tab recording**: When you click the "Record" button in the Performance tab, code gets recompiled with TurboFan again for profiling. However, the initial tier-down to Liftoff when DevTools opens can still affect measurements.
+
+> Important: Do not measure FPS or performance metrics while DevTools is open, as the results will not be representative of actual production performance. Close DevTools before taking performance measurements, or use the Performance tab's recording feature which recompiles code appropriately for profiling.
+
+See [V8's WebAssembly compilation pipeline documentation](https://v8.dev/docs/wasm-compilation-pipeline#debugging) for more details.
+
+## Performance Best Practices
+
+### Build Configuration
+
+For profiling, use a release build with debug information. You have two options:
+
+**DWARF mode** (recommended for easier symbol resolution):
+
+```bash
+swift package --swift-sdk $SWIFT_SDK_ID js -c release --debug-info-format dwarf
+```
+
+DWARF mode preserves DWARF structures, which may disable some wasm-opt optimizations. This can result in performance characteristics that differ from actual release builds. However, the DevTools extension can automatically demangle function names, making results easier to read.
+
+**Name section mode** (recommended for accurate performance characteristics):
+
+```bash
+swift package --swift-sdk $SWIFT_SDK_ID js -c release --debug-info-format name
+```
+
+Name section mode uses WebAssembly's [name section](https://webassembly.github.io/spec/core/appendix/custom.html#name-section) and applies the same optimizations as regular release builds, providing more accurate performance characteristics. However, you'll need to manually demangle function names using `swift demangle` when analyzing results.
+
+> Note: The limitation of name section mode requiring manual demangling may be alleviated in the future through improvements to the DevTools extension.

Sources/JavaScriptKit/Documentation.docc/Articles/Resources/chrome-devtools-perf.png

@@ -53,6 +53,9 @@ Check out the [examples](https://github.com/swiftwasm/JavaScriptKit/tree/main/Ex
 
 - <doc:Deploying-Pages>
 - <doc:JavaScript-Environment-Requirements>
+- <doc:Debugging>
+- <doc:Profiling-Performance-Issues>
+- <doc:Profiling-Memory-Usage>
 
 ### BridgeJS