Update API docs

Author: szegedi

doc/api/v8.md

@@ -1603,9 +1603,85 @@ added:
   - v24.12.0
 -->
 
-* Returns: {string}
+* Returns: {string|undefined}
 
-Stopping collecting the profile and return the profile data.
+Stop collecting the profile and return the profile data as a JSON-encoded
+string. Calling `stop()` after the handle has already been stopped returns
+`undefined`.
+
+### `syncCpuProfileHandle.stopAndCapture()`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Returns: {Object|undefined}
+
+Stop collecting the profile and return a structured profile object instead
+of a JSON string. Calling `stopAndCapture()` after the handle has already
+been stopped returns `undefined`.
+
+The returned object has shape:
+
+* `startTime` {number} Microseconds since V8's clock origin.
+* `endTime` {number} Microseconds since V8's clock origin.
+* `droppedContexts` {number} Number of samples for which a context could not
+  be recorded because the per-session context buffer was full. Always `0`
+  when the profile was started without `withContext`.
+* `topDownRoot` {Object} Root of the recursive call tree:
+  * `functionName` {string}
+  * `scriptName` {string}
+  * `lineNumber` {number}
+  * `columnNumber` {number}
+  * `hitCount` {number} Number of samples that landed at this node.
+  * `contexts` {Array} Optional. Present only when at least one sample at
+    this node carried a context. Each element is `{ context, timestamp }`.
+  * `children` {Array} Child nodes (same shape).
+
+### `syncCpuProfileHandle.snapshot()`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Returns: {Object}
+
+Capture a profile of samples taken since the last `start` or `snapshot`
+call, and continue sampling with a fresh internal session. Returns the
+same shape as [`stopAndCapture()`][]. Useful for continuous profiling: emit
+a snapshot every minute without losing samples between sessions. Throws
+`ERR_INVALID_STATE` if the handle has already been stopped.
+
+### `syncCpuProfileHandle.runWithContext(value, fn[, ...args])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `value` {any} Arbitrary JavaScript value to associate with samples
+  captured during the execution of `fn`.
+* `fn` {Function} Function to invoke.
+* `...args` {any} Arguments forwarded to `fn`.
+* Returns: {any} The return value of `fn(...args)`.
+
+Run `fn(...args)` with `value` recorded as the context for any samples
+captured during its synchronous execution and across awaited continuations
+that propagate the context (via {AsyncLocalStorage}). Throws if the profile
+was started without `withContext: true`.
+
+### `syncCpuProfileHandle.enterWithContext(value)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `value` {any} Arbitrary JavaScript value to associate with subsequent
+  samples in the current asynchronous scope.
+
+Set `value` as the current sample context for the rest of the active
+{AsyncLocalStorage} scope. Mirrors the naming of
+[`asyncLocalStorage.enterWith()`][]. Throws if the profile was started
+without `withContext: true`.
 
 ### `syncCpuProfileHandle[Symbol.dispose]()`
 
@@ -1615,7 +1691,8 @@ added:
   - v24.12.0
 -->
 
-Stopping collecting the profile and the profile will be discarded.
+Stops collecting the profile (equivalent to `stop()`); the profile is
+discarded.
 
 ## Class: `SyncHeapProfileHandle`
 
@@ -1783,6 +1860,19 @@ added:
   * `sampleInterval` {number} Requested sampling interval in milliseconds. **Default:** `0`.
   * `maxBufferSize` {integer} Maximum number of samples to keep before older
     entries are discarded. **Default:** `4294967295`.
+  * `withContext` {boolean} If `true`, the returned handle exposes
+    [`runWithContext()`][] and [`enterWithContext()`][] for associating
+    arbitrary JavaScript values with samples captured during their execution
+    scope. The values are surfaced on each sample of the structured profile
+    returned by [`stopAndCapture()`][] or [`snapshot()`][]. When `false`
+    (default), no per-sample context tracking is performed and there is no
+    extractor overhead. **Default:** `false`.
+  * `contextBufferSize` {integer} Maximum number of samples that can carry a
+    context value during a single profile session. Once exceeded, further
+    samples are recorded with no associated context and the
+    `droppedContexts` counter on the result is incremented. Only meaningful
+    when `withContext` is `true`. **Default:** `60000` (sufficient for 60
+    seconds of sampling at the default 10 ms interval).
 * Returns: {SyncCPUProfileHandle}
 
 Starting a CPU profile then return a `SyncCPUProfileHandle` object.
@@ -1794,6 +1884,21 @@ const profile = handle.stop();
 console.log(profile);
 ```
 
+The returned handle can also produce a structured object tree instead of the
+JSON string, and can carry a per-sample JavaScript context that propagates
+across asynchronous boundaries via {AsyncLocalStorage}:
+
+```cjs
+const handle = v8.startCpuProfile({ withContext: true });
+handle.runWithContext({ requestId: 42 }, () => {
+  // Synchronous and propagated-async work here is sampled with
+  // { requestId: 42 } associated with each sample.
+});
+const profile = handle.stopAndCapture();
+// profile.topDownRoot is a recursive tree; each node may carry
+// `contexts: [{ context, timestamp }, ...]`.
+```
+
 ## `v8.startHeapProfile([options])`
 
 <!-- YAML
@@ -1879,13 +1984,16 @@ console.log(profile);
 [`Serializer`]: #class-v8serializer
 [`after` callback]: #afterpromise
 [`async_hooks`]: async_hooks.md
+[`asyncLocalStorage.enterWith()`]: async_context.md#asynclocalstorageenterwithstore
 [`before` callback]: #beforepromise
 [`buffer.constants.MAX_LENGTH`]: buffer.md#bufferconstantsmax_length
 [`cppgc::HeapStatistics struct`]: https://v8docs.nodesource.com/node-22.4/df/d2f/structcppgc_1_1_heap_statistics.html
 [`cppgc::HeapStatistics`]: https://v8docs.nodesource.com/node-22.4/d7/d51/heap-statistics_8h_source.html
 [`deserializer._readHostObject()`]: #deserializer_readhostobject
 [`deserializer.transferArrayBuffer()`]: #deserializertransferarraybufferid-arraybuffer
+[`enterWithContext()`]: #synccpuprofilehandleenterwithcontextvalue
 [`init` callback]: #initpromise-parent
+[`runWithContext()`]: #synccpuprofilehandlerunwithcontextvalue-fn-args
 [`queryObjects()` console API]: https://developer.chrome.com/docs/devtools/console/utilities#queryObjects-function
 [`serialize()`]: #v8serializevalue
 [`serializer._getSharedArrayBufferId()`]: #serializer_getsharedarraybufferidsharedarraybuffer
@@ -1894,6 +2002,8 @@ console.log(profile);
 [`serializer.transferArrayBuffer()`]: #serializertransferarraybufferid-arraybuffer
 [`serializer.writeRawBytes()`]: #serializerwriterawbytesbuffer
 [`settled` callback]: #settledpromise
+[`snapshot()`]: #synccpuprofilehandlesnapshot
+[`stopAndCapture()`]: #synccpuprofilehandlestopandcapture
 [`v8.stopCoverage()`]: #v8stopcoverage
 [`v8.takeCoverage()`]: #v8takecoverage
 [`vm.Script`]: vm.md#new-vmscriptcode-options