From 79590b6a24618ae9f4b4254f7a7457035f351884 Mon Sep 17 00:00:00 2001
From: John Doe <john.doe@example.com>
Date: Sat, 10 Jan 2026 01:49:49 +0100
Subject: [PATCH 01/11] feat: add performance type extensions

---
 packages/utils/src/perf_hooks.d.ts    | 60 +++++++++++++++++++++
 packages/utils/src/perf_hooks.type.ts | 76 +++++++++++++++++++++++++++
 packages/utils/tsconfig.lib.json      |  2 +-
 packages/utils/tsconfig.test.json     |  3 +-
 4 files changed, 139 insertions(+), 2 deletions(-)
 create mode 100644 packages/utils/src/perf_hooks.d.ts
 create mode 100644 packages/utils/src/perf_hooks.type.ts

diff --git a/packages/utils/src/perf_hooks.d.ts b/packages/utils/src/perf_hooks.d.ts
new file mode 100644
index 000000000..abc873751
--- /dev/null
+++ b/packages/utils/src/perf_hooks.d.ts
@@ -0,0 +1,60 @@
+// perf_hooks.d.ts - Custom type definitions for performance.mark() and performance.measure()
+import type {
+  MarkOptions,
+  MeasureOptions,
+  Performance,
+  PerformanceMark,
+  PerformanceMarkOptions,
+  PerformanceMeasure,
+  PerformanceMeasureOptions,
+} from 'node:perf_hooks';
+import type {
+  MarkOptionsWithDevtools,
+  MarkerPayload,
+  MeasureOptionsWithDevtools,
+  TrackEntryPayload,
+  WithDevToolsPayload,
+} from './lib/user-timing-extensibility-api.type';
+
+export {};
+
+type DetailPayloadWithDevtools = WithDevToolsPayload<
+  TrackEntryPayload | MarkerPayload
+>;
+
+declare module 'node:perf_hooks' {
+  export interface PerformanceMarkOptions {
+    detail?: DetailPayloadWithDevtools;
+    startTime?: DOMHighResTimeStamp;
+  }
+
+  export interface PerformanceMeasureOptions {
+    detail?: DetailPayloadWithDevtools;
+    start?: string | number;
+    end?: string | number;
+    duration?: number;
+  }
+
+  const performance: {
+    mark(
+      name: string,
+      options?: {
+        detail?: DetailPayloadWithDevtools;
+      },
+    ): PerformanceMark;
+
+    measure(
+      name: string,
+      startOrOptions?:
+        | string
+        | number
+        | {
+            detail?: DetailPayloadWithDevtools;
+            start?: string | number;
+            end?: string | number;
+            duration?: number;
+          },
+      end?: string | number,
+    ): PerformanceMeasure;
+  };
+}
diff --git a/packages/utils/src/perf_hooks.type.ts b/packages/utils/src/perf_hooks.type.ts
new file mode 100644
index 000000000..fb50c1fdd
--- /dev/null
+++ b/packages/utils/src/perf_hooks.type.ts
@@ -0,0 +1,76 @@
+import { type PerformanceMarkOptions, performance } from 'node:perf_hooks';
+import { describe, expectTypeOf, it } from 'vitest';
+
+describe('perf_hooks.type', () => {
+  it('PerformanceMarkOptions should be type safe', () => {
+    expectTypeOf<{
+      startTime: number;
+      detail: {
+        devtools: {
+          dataType: 'marker';
+          color: 'error';
+        };
+      };
+    }>().toMatchTypeOf<PerformanceMarkOptions>();
+
+    expectTypeOf<{
+      startTime: number;
+      detail: {
+        devtools: {
+          dataType: 'markerr';
+        };
+      };
+    }>().not.toMatchTypeOf<PerformanceMarkOptions>();
+  });
+
+  it('perf_hooks.mark should be type safe', () => {
+    performance.mark('name', {
+      detail: {
+        devtools: {
+          dataType: 'marker',
+          color: 'error',
+        },
+      },
+    });
+
+    performance.mark('name', {
+      detail: {
+        devtools: {
+          /* @ts-expect-error - dataType should be marker | track */
+          dataType: 'markerrr',
+          color: 'error',
+        },
+      },
+    });
+  });
+
+  it('PerformanceMeasureOptions should be type safe', () => {
+    expectTypeOf<{
+      start: string;
+      end: string;
+      detail: {
+        devtools: {
+          dataType: 'track-entry';
+          track: 'test-track';
+          color: 'primary';
+        };
+      };
+    }>().toMatchTypeOf<PerformanceMeasureOptions>();
+  });
+
+  it('perf_hooks.measure should be type safe', () => {
+    performance.measure('measure-name', 'start-mark', 'end-mark');
+
+    performance.measure('measure-name', {
+      start: 'start-mark',
+      end: 'end-mark',
+      detail: {
+        /* @ts-expect-error - track is required */
+        devtools: {
+          dataType: 'track-entry',
+          color: 'primary',
+        },
+      },
+    });
+  });
+});
diff --git a/packages/utils/tsconfig.lib.json b/packages/utils/tsconfig.lib.json
index 17dadcedf..973149960 100644
--- a/packages/utils/tsconfig.lib.json
+++ b/packages/utils/tsconfig.lib.json
@@ -5,7 +5,7 @@
     "declaration": true,
     "types": ["node"]
   },
-  "include": ["src/**/*.ts"],
+  "include": ["src/**/*.{ts,d.ts}"],
   "exclude": [
     "vitest.unit.config.ts",
     "vitest.int.config.ts",
diff --git a/packages/utils/tsconfig.test.json b/packages/utils/tsconfig.test.json
index 54cacd82f..65a45077f 100644
--- a/packages/utils/tsconfig.test.json
+++ b/packages/utils/tsconfig.test.json
@@ -13,6 +13,7 @@
     "src/**/*.test.js",
     "src/**/*.test.jsx",
     "src/**/*.d.ts",
-    "../../testing/test-setup/src/vitest.d.ts"
+    "../../testing/test-setup/src/vitest.d.ts",
+    "src/perf_hooks.type.ts"
   ]
 }

From 70ad6cdd453d771039f2716ed958aae54916bd9f Mon Sep 17 00:00:00 2001
From: John Doe <john.doe@example.com>
Date: Mon, 12 Jan 2026 02:59:49 +0100
Subject: [PATCH 02/11] fix: wip

---
 packages/utils/src/perf_hooks.d.ts                   | 12 ------------
 .../{perf_hooks.type.ts => perf_hooks.type.test.ts}  |  0
 2 files changed, 12 deletions(-)
 rename packages/utils/src/{perf_hooks.type.ts => perf_hooks.type.test.ts} (100%)

diff --git a/packages/utils/src/perf_hooks.d.ts b/packages/utils/src/perf_hooks.d.ts
index abc873751..e3bf6fb1a 100644
--- a/packages/utils/src/perf_hooks.d.ts
+++ b/packages/utils/src/perf_hooks.d.ts
@@ -1,17 +1,5 @@
-// perf_hooks.d.ts - Custom type definitions for performance.mark() and performance.measure()
 import type {
-  MarkOptions,
-  MeasureOptions,
-  Performance,
-  PerformanceMark,
-  PerformanceMarkOptions,
-  PerformanceMeasure,
-  PerformanceMeasureOptions,
-} from 'node:perf_hooks';
-import type {
-  MarkOptionsWithDevtools,
   MarkerPayload,
-  MeasureOptionsWithDevtools,
   TrackEntryPayload,
   WithDevToolsPayload,
 } from './lib/user-timing-extensibility-api.type';
diff --git a/packages/utils/src/perf_hooks.type.ts b/packages/utils/src/perf_hooks.type.test.ts
similarity index 100%
rename from packages/utils/src/perf_hooks.type.ts
rename to packages/utils/src/perf_hooks.type.test.ts

From 5f1c67a8a12693741876e7debd39c6efba989991 Mon Sep 17 00:00:00 2001
From: John Doe <john.doe@example.com>
Date: Mon, 12 Jan 2026 16:03:45 +0100
Subject: [PATCH 03/11] fix: wip

---
 packages/utils/tsconfig.test.json | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/packages/utils/tsconfig.test.json b/packages/utils/tsconfig.test.json
index 65a45077f..54cacd82f 100644
--- a/packages/utils/tsconfig.test.json
+++ b/packages/utils/tsconfig.test.json
@@ -13,7 +13,6 @@
     "src/**/*.test.js",
     "src/**/*.test.jsx",
     "src/**/*.d.ts",
-    "../../testing/test-setup/src/vitest.d.ts",
-    "src/perf_hooks.type.ts"
+    "../../testing/test-setup/src/vitest.d.ts"
   ]
 }

From c95589d4049e284ac61f88a99d7b13b29f1c90f7 Mon Sep 17 00:00:00 2001
From: John Doe <john.doe@example.com>
Date: Mon, 12 Jan 2026 19:16:54 +0100
Subject: [PATCH 04/11] refactor: fix lint

---
 .../src/{perf_hooks.d.ts => perf-hooks.d.ts}    | 17 ++---------------
 ...oks.type.test.ts => perf-hooks.unit.test.ts} |  3 +--
 2 files changed, 3 insertions(+), 17 deletions(-)
 rename packages/utils/src/{perf_hooks.d.ts => perf-hooks.d.ts} (65%)
 rename packages/utils/src/{perf_hooks.type.test.ts => perf-hooks.unit.test.ts} (97%)

diff --git a/packages/utils/src/perf_hooks.d.ts b/packages/utils/src/perf-hooks.d.ts
similarity index 65%
rename from packages/utils/src/perf_hooks.d.ts
rename to packages/utils/src/perf-hooks.d.ts
index e3bf6fb1a..cf32771fb 100644
--- a/packages/utils/src/perf_hooks.d.ts
+++ b/packages/utils/src/perf-hooks.d.ts
@@ -24,24 +24,11 @@ declare module 'node:perf_hooks' {
   }
 
   const performance: {
-    mark(
-      name: string,
-      options?: {
-        detail?: DetailPayloadWithDevtools;
-      },
-    ): PerformanceMark;
+    mark(name: string, options?: PerformanceMarkOptions): PerformanceMark;
 
     measure(
       name: string,
-      startOrOptions?:
-        | string
-        | number
-        | {
-            detail?: DetailPayloadWithDevtools;
-            start?: string | number;
-            end?: string | number;
-            duration?: number;
-          },
+      startOrOptions?: string | number | PerformanceMeasureOptions,
       end?: string | number,
     ): PerformanceMeasure;
   };
diff --git a/packages/utils/src/perf_hooks.type.test.ts b/packages/utils/src/perf-hooks.unit.test.ts
similarity index 97%
rename from packages/utils/src/perf_hooks.type.test.ts
rename to packages/utils/src/perf-hooks.unit.test.ts
index fb50c1fdd..b8245d0b4 100644
--- a/packages/utils/src/perf_hooks.type.test.ts
+++ b/packages/utils/src/perf-hooks.unit.test.ts
@@ -1,7 +1,7 @@
 import { type PerformanceMarkOptions, performance } from 'node:perf_hooks';
 import { describe, expectTypeOf, it } from 'vitest';
 
-describe('perf_hooks.type', () => {
+describe('perf-hooks definitions', () => {
   it('PerformanceMarkOptions should be type safe', () => {
     expectTypeOf<{
       startTime: number;
@@ -12,7 +12,6 @@ describe('perf_hooks.type', () => {
         };
       };
     }>().toMatchTypeOf<PerformanceMarkOptions>();
-
     expectTypeOf<{
       startTime: number;
       detail: {

From 5d779e8ed8b417a276fc1d70bfd83a36775105dc Mon Sep 17 00:00:00 2001
From: John Doe <john.doe@example.com>
Date: Mon, 12 Jan 2026 19:22:20 +0100
Subject: [PATCH 05/11] refactor: revert ts cfg

---
 packages/utils/tsconfig.lib.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/utils/tsconfig.lib.json b/packages/utils/tsconfig.lib.json
index 973149960..17dadcedf 100644
--- a/packages/utils/tsconfig.lib.json
+++ b/packages/utils/tsconfig.lib.json
@@ -5,7 +5,7 @@
     "declaration": true,
     "types": ["node"]
   },
-  "include": ["src/**/*.{ts,d.ts}"],
+  "include": ["src/**/*.ts"],
   "exclude": [
     "vitest.unit.config.ts",
     "vitest.int.config.ts",

From 2aff8770fce9e41842497d16fca88c58c2d924a0 Mon Sep 17 00:00:00 2001
From: John Doe <john.doe@example.com>
Date: Wed, 14 Jan 2026 00:20:54 +0100
Subject: [PATCH 06/11] refactor: add APIs

---
 packages/utils/src/perf-hooks.d.ts         |  23 +++-
 packages/utils/src/perf-hooks.unit.test.ts | 119 ++++++++++++---------
 2 files changed, 87 insertions(+), 55 deletions(-)

diff --git a/packages/utils/src/perf-hooks.d.ts b/packages/utils/src/perf-hooks.d.ts
index cf32771fb..7f71c4010 100644
--- a/packages/utils/src/perf-hooks.d.ts
+++ b/packages/utils/src/perf-hooks.d.ts
@@ -11,6 +11,23 @@ type DetailPayloadWithDevtools = WithDevToolsPayload<
 >;
 
 declare module 'node:perf_hooks' {
+  interface PerformanceEntry {
+    readonly detail?: DetailPayloadWithDevtools;
+  }
+
+  interface MarkEntry extends PerformanceMark {
+    readonly entryType: 'mark';
+    readonly detail?: DetailPayloadWithDevtools;
+  }
+
+  interface MeasureEntry extends PerformanceMeasure {
+    readonly entryType: 'measure';
+    readonly detail?: DetailPayloadWithDevtools;
+  }
+
+  interface PerformanceMark extends PerformanceEntry {}
+  interface PerformanceMeasure extends PerformanceEntry {}
+
   export interface PerformanceMarkOptions {
     detail?: DetailPayloadWithDevtools;
     startTime?: DOMHighResTimeStamp;
@@ -24,12 +41,12 @@ declare module 'node:perf_hooks' {
   }
 
   const performance: {
-    mark(name: string, options?: PerformanceMarkOptions): PerformanceMark;
+    mark: (name: string, options?: PerformanceMarkOptions) => PerformanceMark;
 
-    measure(
+    measure: (
       name: string,
       startOrOptions?: string | number | PerformanceMeasureOptions,
       end?: string | number,
-    ): PerformanceMeasure;
+    ) => PerformanceMeasure;
   };
 }
diff --git a/packages/utils/src/perf-hooks.unit.test.ts b/packages/utils/src/perf-hooks.unit.test.ts
index b8245d0b4..1f11ac07f 100644
--- a/packages/utils/src/perf-hooks.unit.test.ts
+++ b/packages/utils/src/perf-hooks.unit.test.ts
@@ -1,75 +1,90 @@
 import { type PerformanceMarkOptions, performance } from 'node:perf_hooks';
-import { describe, expectTypeOf, it } from 'vitest';
+import { describe, expect, expectTypeOf, it } from 'vitest';
 
 describe('perf-hooks definitions', () => {
   it('PerformanceMarkOptions should be type safe', () => {
-    expectTypeOf<{
-      startTime: number;
-      detail: {
-        devtools: {
-          dataType: 'marker';
-          color: 'error';
+    expect(() =>
+      expectTypeOf<{
+        startTime: number;
+        detail: {
+          devtools: {
+            dataType: 'marker';
+            color: 'error';
+          };
         };
-      };
-    }>().toMatchTypeOf<PerformanceMarkOptions>();
-    expectTypeOf<{
-      startTime: number;
-      detail: {
-        devtools: {
-          dataType: 'markerr';
+      }>().toMatchTypeOf<PerformanceMarkOptions>(),
+    ).not.toThrow();
+
+    expect(() =>
+      expectTypeOf<{
+        startTime: number;
+        detail: {
+          devtools: {
+            dataType: 'markerr';
+          };
         };
-      };
-    }>().not.toMatchTypeOf<PerformanceMarkOptions>();
+      }>().not.toMatchTypeOf<PerformanceMarkOptions>(),
+    ).not.toThrow();
   });
 
   it('perf_hooks.mark should be type safe', () => {
-    performance.mark('name', {
-      detail: {
-        devtools: {
-          dataType: 'marker',
-          color: 'error',
+    expect(() =>
+      performance.mark('name', {
+        detail: {
+          devtools: {
+            dataType: 'marker',
+            color: 'error',
+          },
         },
-      },
-    });
+      }),
+    ).not.toThrow();
 
-    performance.mark('name', {
-      detail: {
-        devtools: {
-          /* @ts-expect-error - dataType should be marker | track */
-          dataType: 'markerrr',
-          color: 'error',
+    expect(() =>
+      performance.mark('name', {
+        detail: {
+          devtools: {
+            // @ts-expect-error - dataType should be marker | track
+            dataType: 'markerrr',
+            color: 'error',
+          },
         },
-      },
-    });
+      }),
+    ).not.toThrow();
   });
 
   it('PerformanceMeasureOptions should be type safe', () => {
-    expectTypeOf<{
-      start: string;
-      end: string;
-      detail: {
-        devtools: {
-          dataType: 'track-entry';
-          track: 'test-track';
-          color: 'primary';
+    expect(() =>
+      expectTypeOf<{
+        start: string;
+        end: string;
+        detail: {
+          devtools: {
+            dataType: 'track-entry';
+            track: 'test-track';
+            color: 'primary';
+          };
         };
-      };
-    }>().toMatchTypeOf<PerformanceMeasureOptions>();
+      }>().toMatchTypeOf<PerformanceMeasureOptions>(),
+    ).not.toThrow();
   });
 
   it('perf_hooks.measure should be type safe', () => {
-    performance.measure('measure-name', 'start-mark', 'end-mark');
+    expect(() =>
+      performance.measure('measure-name', 'start-mark', 'end-mark'),
+    ).not.toThrow();
 
-    performance.measure('measure-name', {
-      start: 'start-mark',
-      end: 'end-mark',
-      detail: {
-        /* @ts-expect-error - track is required */
-        devtools: {
-          dataType: 'track-entry',
-          color: 'primary',
+    expect(() =>
+      performance.measure('measure-name', {
+        start: 'start-mark',
+        end: 'end-mark',
+        detail: {
+          // @ts-expect-error - track is required
+          devtools: {
+            dataType: 'track-entry',
+            color: 'primary',
+          },
         },
-      },
-    });
+      }),
+    ).not.toThrow();
   });
 });

From be3d41da34f8eeb1435b1529f168cce9c9c427f8 Mon Sep 17 00:00:00 2001
From: John Doe <john.doe@example.com>
Date: Wed, 14 Jan 2026 00:33:51 +0100
Subject: [PATCH 07/11] refactor: add types

---
 packages/utils/src/lib/performance-observer.ts | 7 ++++---
 packages/utils/src/perf-hooks.d.ts             | 6 ++++++
 2 files changed, 10 insertions(+), 3 deletions(-)

diff --git a/packages/utils/src/lib/performance-observer.ts b/packages/utils/src/lib/performance-observer.ts
index 6b360d0da..53b9176d8 100644
--- a/packages/utils/src/lib/performance-observer.ts
+++ b/packages/utils/src/lib/performance-observer.ts
@@ -24,9 +24,10 @@ export class PerformanceObserverSink<T>
   #flushThreshold: number;
   #sink: Sink<T, unknown>;
   #observer: PerformanceObserver | undefined;
-  #observedTypes: EntryType[] = ['mark', 'measure'];
-  #getEntries = (list: PerformanceObserverEntryList) =>
-    this.#observedTypes.flatMap(t => list.getEntriesByType(t));
+  readonly #observedTypes: EntryType[] = ['mark', 'measure'];
+  #getEntries = (list: {
+    getEntriesByType: (t: EntryType) => PerformanceEntry[];
+  }) => this.#observedTypes.flatMap(t => list.getEntriesByType(t));
   #observedCount: number = 0;
 
   constructor(options: PerformanceObserverOptions<T>) {
diff --git a/packages/utils/src/perf-hooks.d.ts b/packages/utils/src/perf-hooks.d.ts
index 7f71c4010..4ebbb5b17 100644
--- a/packages/utils/src/perf-hooks.d.ts
+++ b/packages/utils/src/perf-hooks.d.ts
@@ -40,6 +40,10 @@ declare module 'node:perf_hooks' {
     duration?: number;
   }
 
+  export interface PerformanceObserverEntryList {
+    getEntriesByType: (type: EntryType) => PerformanceEntry[];
+  }
+
   const performance: {
     mark: (name: string, options?: PerformanceMarkOptions) => PerformanceMark;
 
@@ -48,5 +52,7 @@ declare module 'node:perf_hooks' {
       startOrOptions?: string | number | PerformanceMeasureOptions,
       end?: string | number,
     ) => PerformanceMeasure;
+
+    getEntriesByType: (type: EntryType) => PerformanceEntry[];
   };
 }

From a46bb31f5c6fdbbcd031e38d2207e1323757939c Mon Sep 17 00:00:00 2001
From: John Doe <john.doe@example.com>
Date: Wed, 14 Jan 2026 00:40:58 +0100
Subject: [PATCH 08/11] refactor: fix lint

---
 packages/utils/src/lib/performance-observer.ts | 1 -
 1 file changed, 1 deletion(-)

diff --git a/packages/utils/src/lib/performance-observer.ts b/packages/utils/src/lib/performance-observer.ts
index 53b9176d8..126ec849c 100644
--- a/packages/utils/src/lib/performance-observer.ts
+++ b/packages/utils/src/lib/performance-observer.ts
@@ -2,7 +2,6 @@ import {
   type EntryType,
   type PerformanceEntry,
   PerformanceObserver,
-  type PerformanceObserverEntryList,
   performance,
 } from 'node:perf_hooks';
 import type { Buffered, Encoder, Observer, Sink } from './sink-source.types.js';

From d78d3488b43f3b398e6783ea1c720b2d347bb777 Mon Sep 17 00:00:00 2001
From: John Doe <john.doe@example.com>
Date: Wed, 14 Jan 2026 00:44:35 +0100
Subject: [PATCH 09/11] refactor: wip

---
 packages/utils/src/lib/performance-observer.ts | 7 ++-----
 1 file changed, 2 insertions(+), 5 deletions(-)

diff --git a/packages/utils/src/lib/performance-observer.ts b/packages/utils/src/lib/performance-observer.ts
index 126ec849c..827e5c4e5 100644
--- a/packages/utils/src/lib/performance-observer.ts
+++ b/packages/utils/src/lib/performance-observer.ts
@@ -24,9 +24,9 @@ export class PerformanceObserverSink<T>
   #sink: Sink<T, unknown>;
   #observer: PerformanceObserver | undefined;
   readonly #observedTypes: EntryType[] = ['mark', 'measure'];
-  #getEntries = (list: {
+  #getEntries = (listOrGlobal: {
     getEntriesByType: (t: EntryType) => PerformanceEntry[];
-  }) => this.#observedTypes.flatMap(t => list.getEntriesByType(t));
+  }) => this.#observedTypes.flatMap(t => listOrGlobal.getEntriesByType(t));
   #observedCount: number = 0;
 
   constructor(options: PerformanceObserverOptions<T>) {
@@ -72,9 +72,6 @@ export class PerformanceObserverSink<T>
       });
     });
 
-    // In real PerformanceObserver, entries remain in the global buffer
-    // They are only cleared when explicitly requested via performance.clearMarks/clearMeasures
-
     this.#observedCount = 0;
   }
 

From 16511eb23e5db7b6f23bac5f13a31ee3fdf20c50 Mon Sep 17 00:00:00 2001
From: John Doe <john.doe@example.com>
Date: Wed, 14 Jan 2026 01:27:39 +0100
Subject: [PATCH 10/11] refactor: move types

---
 .../src/lib/user-timing-extensibility-api.type.ts      |  6 ++++++
 packages/utils/src/perf-hooks.d.ts                     | 10 +---------
 2 files changed, 7 insertions(+), 9 deletions(-)

diff --git a/packages/utils/src/lib/user-timing-extensibility-api.type.ts b/packages/utils/src/lib/user-timing-extensibility-api.type.ts
index 0e75be77b..149852ec3 100644
--- a/packages/utils/src/lib/user-timing-extensibility-api.type.ts
+++ b/packages/utils/src/lib/user-timing-extensibility-api.type.ts
@@ -117,6 +117,12 @@ export type WithDevToolsPayload<T extends TrackEntryPayload | MarkerPayload> = {
   devtools?: T;
 };
 
+/**
+ * Combined detail payload type for performance entries with DevTools support.
+ */
+export type DetailPayloadWithDevtools = WithDevToolsPayload<
+  TrackEntryPayload | MarkerPayload
+>;
 /**
  * Extended MarkOptions that supports DevTools payload in detail.
  * @example
diff --git a/packages/utils/src/perf-hooks.d.ts b/packages/utils/src/perf-hooks.d.ts
index 4ebbb5b17..5307f1e54 100644
--- a/packages/utils/src/perf-hooks.d.ts
+++ b/packages/utils/src/perf-hooks.d.ts
@@ -1,15 +1,7 @@
-import type {
-  MarkerPayload,
-  TrackEntryPayload,
-  WithDevToolsPayload,
-} from './lib/user-timing-extensibility-api.type';
+import type { DetailPayloadWithDevtools } from './lib/user-timing-extensibility-api.type';
 
 export {};
 
-type DetailPayloadWithDevtools = WithDevToolsPayload<
-  TrackEntryPayload | MarkerPayload
->;
-
 declare module 'node:perf_hooks' {
   interface PerformanceEntry {
     readonly detail?: DetailPayloadWithDevtools;

From c45d91ffc59e330cbf4e42757cf377973a3cae51 Mon Sep 17 00:00:00 2001
From: John Doe <john.doe@example.com>
Date: Wed, 14 Jan 2026 06:14:44 +0100
Subject: [PATCH 11/11] refactor: docs

---
 packages/utils/src/perf-hooks.d.ts | 142 +++++++++++++++++++++++++++++
 1 file changed, 142 insertions(+)

diff --git a/packages/utils/src/perf-hooks.d.ts b/packages/utils/src/perf-hooks.d.ts
index 5307f1e54..5501bdb4c 100644
--- a/packages/utils/src/perf-hooks.d.ts
+++ b/packages/utils/src/perf-hooks.d.ts
@@ -2,49 +2,191 @@ import type { DetailPayloadWithDevtools } from './lib/user-timing-extensibility-
 
 export {};
 
+/**
+ * Type definitions extending Node.js perf_hooks module to enable Chrome DevTools UserTiming Extensibility API.
+ *
+ * The `detail` property allows custom payloads to be attached to performance marks and measures,
+ * which are then accessible in Chrome DevTools and visualized in as custom tracks right under UserTiming.
+ * This enables richer performance instrumentation with structured data that DevTools can display.
+ */
 declare module 'node:perf_hooks' {
+  /**
+   * Extends the base PerformanceEntry interface with optional custom detail payload.
+   *
+   * The detail property enables Chrome DevTools UserTiming Extensibility API by allowing
+   * structured data to be attached to performance entries for enhanced debugging visualization.
+   * This augmentation only ensures the payload is preserved and visible to DevTools.
+   *
+   * @example
+   * ```typescript
+   * // Preserved entries with entry.detail
+   * const entry = performance.getEntriesByType('mark').at(0);
+   * ```
+   */
   interface PerformanceEntry {
+    /** Custom payload accessible in Chrome DevTools for enhanced performance analysis. */
     readonly detail?: DetailPayloadWithDevtools;
   }
 
+  /**
+   * Represents a performance mark entry with custom detail support for DevTools extensibility.
+   *
+   * Mark entries with detail payloads enable Chrome DevTools to display additional context
+   * and structured data alongside the mark in the Performance tab. Markers create vertical
+   * lines that span all tracks and appear at the top of the timeline.
+   *
+   * @example
+   * ```typescript
+   * // Preserved mark entries with entry.detail
+   * const entry = performance.getEntriesByType('mark').at(0);
+   * ```
+   */
   interface MarkEntry extends PerformanceMark {
     readonly entryType: 'mark';
+    /** Custom payload displayed in Chrome DevTools for enhanced mark visualization. */
     readonly detail?: DetailPayloadWithDevtools;
   }
 
+  /**
+   * Represents a performance measure entry with custom detail support for DevTools extensibility.
+   *
+   * Measure entries with detail payloads allow Chrome DevTools to show additional metadata
+   * and context information alongside the measured performance duration. Track entries appear
+   * in custom tracks below the main UserTiming track.
+   *
+   * @example
+   * ```typescript
+   * // Preserved measure entries with entry.detail
+   * const entry = performance.getEntriesByType('measure').at(0);
+   * ```
+   */
   interface MeasureEntry extends PerformanceMeasure {
     readonly entryType: 'measure';
+    /** Custom payload displayed in Chrome DevTools for enhanced measure visualization. */
     readonly detail?: DetailPayloadWithDevtools;
   }
 
+  /**
+   * Extends Node.js PerformanceMark to include the custom detail payload support.
+   *
+   * This interface ensures that performance marks created through the extended API
+   * have access to the `detail` property for Chrome DevTools UserTiming Extensibility.
+   */
   interface PerformanceMark extends PerformanceEntry {}
+
+  /**
+   * Extends Node.js PerformanceMeasure to include the custom detail payload support.
+   *
+   * This interface ensures that performance measures created through the extended API
+   * have access to the `detail` property for Chrome DevTools UserTiming Extensibility.
+   */
   interface PerformanceMeasure extends PerformanceEntry {}
 
+  /**
+   * Options for creating performance marks with custom detail payload for DevTools integration.
+   *
+   * The detail property enables attaching structured data that Chrome DevTools can display
+   * alongside the mark, providing richer debugging context.
+   *
+   * @example
+   * ```typescript
+   * // Options include detail property
+   * const options: PerformanceMarkOptions = { detail: { devtools: {} } };
+   * ```
+   */
   export interface PerformanceMarkOptions {
+    /** Custom payload that will be accessible in Chrome DevTools UserTiming visualization. */
     detail?: DetailPayloadWithDevtools;
     startTime?: DOMHighResTimeStamp;
   }
 
+  /**
+   * Options for creating performance measures with custom detail payload for DevTools integration.
+   *
+   * The detail property allows attaching metadata that Chrome DevTools will display
+   * with the measure, enabling better performance analysis and debugging.
+   *
+   * @example
+   * ```typescript
+   * // Options include detail property
+   * const options: PerformanceMeasureOptions = { detail: { devtools: {} } };
+   * ```
+   */
   export interface PerformanceMeasureOptions {
+    /** Custom payload that will be accessible in Chrome DevTools UserTiming visualization. */
     detail?: DetailPayloadWithDevtools;
     start?: string | number;
     end?: string | number;
     duration?: number;
   }
 
+  /**
+   * Extended performance observer entry list with typed entry retrieval.
+   */
   export interface PerformanceObserverEntryList {
     getEntriesByType: (type: EntryType) => PerformanceEntry[];
   }
 
+  /**
+   * Extended performance object with Chrome DevTools UserTiming Extensibility API support.
+   *
+   * Enables creating performance marks and measures with custom detail payloads that are
+   * displayed in Chrome DevTools, providing enhanced debugging and performance analysis capabilities.
+   */
   const performance: {
+    /**
+     * Creates a performance mark with optional custom detail payload for DevTools visualization.
+     *
+     * The detail payload will be accessible in Chrome DevTools Performance tab,
+     * enabling richer debugging context for the mark.
+     *
+     * @example
+     * ```typescript
+     * // Accepts detail options
+     * performance.mark('checkpoint', { detail: { devtools: {} } });
+     * ```
+     *
+     * @param name - The name of the mark displayed in DevTools
+     * @param options - Optional configuration including detail payload for DevTools
+     * @returns The created performance mark with DevTools-compatible detail
+     */
     mark: (name: string, options?: PerformanceMarkOptions) => PerformanceMark;
 
+    /**
+     * Creates a performance measure with optional custom detail payload for DevTools visualization.
+     *
+     * The detail payload enables Chrome DevTools to display additional metadata
+     * alongside the measured performance duration for enhanced analysis.
+     *
+     * @example
+     * ```typescript
+     * // Accepts detail options
+     * performance.measure('task', { detail: { devtools: {} } });
+     * ```
+     *
+     * @param name - The name of the measure displayed in DevTools
+     * @param startOrOptions - Start mark name/number or full options object with DevTools detail
+     * @param end - End mark name/number (when startOrOptions is not options object)
+     * @returns The created performance measure with DevTools-compatible detail
+     */
     measure: (
       name: string,
       startOrOptions?: string | number | PerformanceMeasureOptions,
       end?: string | number,
     ) => PerformanceMeasure;
 
+    /**
+     * Retrieves performance entries of the specified type, including DevTools detail payloads.
+     *
+     * @example
+     * ```typescript
+     * // Returns entries with preserved entry.detail
+     * const entry = performance.getEntriesByType('mark').at(0);
+     * ```
+     *
+     * @param type - The entry type to filter by ('mark' or 'measure')
+     * @returns Array of performance entries with DevTools detail payloads
+     */
     getEntriesByType: (type: EntryType) => PerformanceEntry[];
   };
 }