chore: refresh guidelines on obtaining simulate traces (#328)

* docs: refresh guidelines on obtaining simulate traces

* docs: adding migration for algokit-utils-ts-debug

* chore: updating teal sourcemap file extension convention

This was meant to be merged in puya sourcemaps pr; adding as a chore commit

docs/capabilities/debugging.md

@@ -15,7 +15,7 @@ Config.configure({
 })
 ```
 
-## Debugging Utilities
+## Debugging in `node` environment (recommended)
 
 Refer to the [algokit-utils-ts-debug](https://github.com/algorandfoundation/algokit-utils-ts-debug) for more details on how to activate the addon package with `algokit-utils` in your project.
 
@@ -24,3 +24,13 @@ Refer to the [algokit-utils-ts-debug](https://github.com/algorandfoundation/algo
 ### Why are the debug utilities in a separate package?
 
 To keep the `algokit-utils-ts` package lean and isomporphic, the debugging utilities are located in a separate package. This eliminates various error cases with bundlers (e.g. `webpack`, `esbuild`) when building for the browser.
+
+## Debugging in `browser` environment
+
+Note that it's not possible to use `algokit-utils-ts-debug` in browser environments; however, you can still obtain and persist simulation traces from the browser network tab whenever a transaction is being submitted using the algokit-utils-ts package. Make sure to enable the debug mode in the algokit-utils-ts config as described in the [getting started](./docs/code/getting-started.md) guide. To obtain the simulation trace:
+
+1. Open the browser network tab
+2. Submit the transaction
+3. Filter the requests by `simulate`
+4. Copy the 'simulate' request body and store it in a file with a .trace.avm.json extension, then place it under the `debug_traces` folder in your AlgoKit contract project.
+   4.1. (Optional) If you are not using an AlgoKit project structure for your contracts codebase, as long as the trace file is within your VSCode workspace, the extension will present a picker to select the trace file.

docs/code/modules/types_debugging.md

@@ -70,7 +70,7 @@ ___
 
 ### TEAL\_SOURCEMAP\_EXT
 
-• `Const` **TEAL\_SOURCEMAP\_EXT**: ``".teal.tok.map"``
+• `Const` **TEAL\_SOURCEMAP\_EXT**: ``".teal.map"``
 
 The file extension for TEAL source map files
 

docs/v7-migration.md

@@ -147,3 +147,33 @@ If you are converting from an older typed client to a new one you will need to m
 - `extraPages` is no longer nested within a `schema` property, instead it's directly on the method call params as `extraProgramPages`
 - `client.compose()` is now `client.newGroup()`
 - `client.compose()....execute()` is now `client.compose()....send()`
+
+### Optional steps
+
+#### AlgoKit VScode AVM debugger extension utils
+
+If you previously used `Config.configure({ debug: true })` for AVM sourcemaps and TEAL traces, you can now debug `puya` compiler-based sourcemaps. This allows stepping through higher-level Algorand Python constructs instead of raw TEAL.
+
+To incorporate this change and resolve frontend bundler issues, `algokit-utils` is now isomorphic. Node-specific dependencies are split into the `algokit-utils-ts-debug` package.
+
+To migrate:
+
+1. Install the new package:
+
+```bash
+npm i @algorandfoundation/algokit-utils-debug
+```
+
+2. Activate the new package:
+
+```typescript
+import { Config } from '@algorandfoundation/algokit-utils'
+import { registerDebugEventHandlers } from '@algorandfoundation/algokit-utils-debug'
+
+Config.configure({ debug: true })
+registerDebugEventHandlers()
+```
+
+This approach maintains debug functionality while ensuring compatibility with frontend bundlers.
+
+> For more details on debugging puya based contracts, refer [here](https://github.com/algorandfoundation/algokit-avm-vscode-debugger).

src/types/debugging.ts

@@ -15,7 +15,7 @@ export const SOURCES_DIR = 'sources'
 export const TEAL_FILE_EXT = '.teal'
 
 /** The file extension for TEAL source map files */
-export const TEAL_SOURCEMAP_EXT = '.teal.tok.map'
+export const TEAL_SOURCEMAP_EXT = '.teal.map'
 
 /** The default maximum search depth for file operations */
 export const DEFAULT_MAX_SEARCH_DEPTH = 10