react-render-pulse 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Amal M
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,98 @@
-# Temporary Holding Version
+# react-render-pulse
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm version](https://img.shields.io/npm/v/react-render-pulse?color=cb3837&logo=npm)](https://www.npmjs.com/package/react-render-pulse)
+[![CI](https://github.com/Amalmktk/react-render-pulse/actions/workflows/ci.yml/badge.svg)](https://github.com/Amalmktk/react-render-pulse/actions/workflows/ci.yml)
+[![license](https://img.shields.io/npm/l/react-render-pulse)](https://github.com/Amalmktk/react-render-pulse/blob/main/LICENSE)
+
+Real-user render performance monitoring for React, at the component level. Wrap the parts of your tree you care about and get render timings from real sessions: render counts, slow renders, p50/p75/p95 and the slowest renders per area and route, plus long tasks attributed to the area that was rendering.
+
+Under 3.75 kB brotli. No runtime dependencies besides React 18 or 19.
+
+## Install
+
+```bash
+npm install react-render-pulse
+```
+
+## Usage
+
+Start it once, in the browser, before your app renders:
+
+```tsx
+import { createRoot } from "react-dom/client";
+import { initRenderPulse } from "react-render-pulse";
+import { App } from "./App";
+
+initRenderPulse({
+  endpoint: "/api/render-pulse", // leave out to log batches to the console
+  sampleRate: 0.1, // 10% of page loads
+  appVersion: import.meta.env.VITE_APP_VERSION,
+});
+
+createRoot(document.getElementById("root")!).render(<App />);
+```
+
+Wrap areas you want timings for:
+
+```tsx
+import { RenderMonitor, useRenderMonitor } from "react-render-pulse";
+
+export function OrdersPage() {
+  return (
+    <RenderMonitor id="orders-table">
+      <OrdersTable />
+    </RenderMonitor>
+  );
+}
+
+function PriceChart() {
+  useRenderMonitor("price-chart"); // exact render count; duration is an upper bound
+  return <Chart />;
+}
+```
+
+`<RenderMonitor>` adds no DOM elements and never remounts its children. Errors inside the package never reach your app.
+
+Batches are sent when the page is hidden and every 3 minutes while it's visible. Send them to [`react-render-pulse-collector`](https://www.npmjs.com/package/react-render-pulse-collector) and read them with [`react-render-pulse-viewer`](https://www.npmjs.com/package/react-render-pulse-viewer).
+
+## Key options
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `endpoint` | none | Where batches are `POST`ed. Without one, batches are logged to the console. |
+| `sampleRate` | `1` | Fraction of page loads that collect anything. |
+| `mode` | `"auto"` | `"lightweight"`, `"profiling"`, or `"auto"`: lightweight until React's profiling build is detected. |
+| `slowRenderMs` | `16` | Renders slower than this count as slow. |
+| `longTaskMs` | `50` | Shorter long tasks and long animation frames are ignored. |
+| `appVersion` | none | Your app's version, for comparing releases. |
+| `getRoute` | numeric path segments → `:id` | Returns the current route template, e.g. `/orders/:id`. |
+| `exporters` | `[]` | Extra receivers, e.g. `createOtelExporter` from `react-render-pulse/otel`. |
+
+All options: [client API reference](https://github.com/Amalmktk/react-render-pulse/blob/main/docs/api/client.md).
+
+## Modes
+
+- **Lightweight** (any production build): times each area between two marker components. About 10–15 µs per measured render. Doesn't see updates that start inside the area.
+- **Profiling** (React's profiling build): React's `<Profiler>` timings for every commit. Exact, but the profiling build itself costs more; use it for a sampled group.
+
+Enable the profiling build by aliasing `react-dom/client` to `react-dom/profiling` (Vite) or with `next build --profile`. See [Modes](https://github.com/Amalmktk/react-render-pulse/blob/main/docs/guide/modes.md).
+
+## Entry points
+
+| Import | Contents |
+| --- | --- |
+| `react-render-pulse` | `initRenderPulse`, `RenderMonitor`, `useRenderMonitor`, `createConsoleExporter`, types. Marked `"use client"`. |
+| `react-render-pulse/core` | Types, `HISTOGRAM_BOUNDS`, `histogramPercentile`. No React; safe on servers. |
+| `react-render-pulse/otel` | `createOtelExporter`, for OpenTelemetry metrics. |
+
+## Privacy
+
+No user IDs, IP addresses, page text, input values or query strings. The session id is random per page load and never stored. Routes come from `location.pathname`; numeric segments are replaced by default, but pass a `getRoute` if paths can contain names, slugs or UUIDs. See [What we collect](https://github.com/Amalmktk/react-render-pulse/blob/main/docs/guide/what-we-collect.md).
+
+## Documentation
+
+Full docs: https://github.com/Amalmktk/react-render-pulse/tree/main/docs
+
+## License
+
+MIT © Amal M

package/dist/aggregate/aggregator.d.cts

@@ -0,0 +1,27 @@
+import type { AreaReport, LongTaskEvent, LongTaskReport, RenderEvent, SessionSummary } from "../types.cjs";
+export interface AggregatorOptions {
+    /** Renders slower than this count as slow. */
+    slowRenderMs: number;
+    /** Most distinct area/route pairs kept per batch; renders for new ones past this are dropped. */
+    maxAreas: number;
+    /** How many of the slowest renders to keep per area. */
+    worstCases: number;
+    /** `performance.now()` at session start, so worst cases report time since then. */
+    sessionStart: number;
+}
+export interface AggregatedBatch {
+    summary: SessionSummary;
+    areas: AreaReport[];
+    longTasks: LongTaskReport[];
+    longFrames: LongTaskReport[];
+    droppedAreas: number;
+}
+export interface Aggregator {
+    addRender: (event: RenderEvent) => void;
+    addLongTask: (event: LongTaskEvent) => void;
+    /** True when nothing was recorded since the last `drain()`. */
+    isEmpty: () => boolean;
+    /** Returns everything recorded since the last call, and starts a new batch. */
+    drain: () => AggregatedBatch;
+}
+export declare function createAggregator(options: AggregatorOptions): Aggregator;

package/dist/aggregate/aggregator.d.ts

@@ -0,0 +1,28 @@
+import type { AreaReport, LongTaskEvent, LongTaskReport, RenderEvent, SessionSummary } from "../types.js";
+export interface AggregatorOptions {
+    /** Renders slower than this count as slow. */
+    slowRenderMs: number;
+    /** Most distinct area/route pairs kept per batch; renders for new ones past this are dropped. */
+    maxAreas: number;
+    /** How many of the slowest renders to keep per area. */
+    worstCases: number;
+    /** `performance.now()` at session start, so worst cases report time since then. */
+    sessionStart: number;
+}
+export interface AggregatedBatch {
+    summary: SessionSummary;
+    areas: AreaReport[];
+    longTasks: LongTaskReport[];
+    longFrames: LongTaskReport[];
+    droppedAreas: number;
+}
+export interface Aggregator {
+    addRender: (event: RenderEvent) => void;
+    addLongTask: (event: LongTaskEvent) => void;
+    /** True when nothing was recorded since the last `drain()`. */
+    isEmpty: () => boolean;
+    /** Returns everything recorded since the last call, and starts a new batch. */
+    drain: () => AggregatedBatch;
+}
+export declare function createAggregator(options: AggregatorOptions): Aggregator;
+//# sourceMappingURL=aggregator.d.ts.map

package/dist/aggregate/aggregator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aggregator.d.ts","sourceRoot":"","sources":["../../src/aggregate/aggregator.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,cAAc,EAAE,WAAW,EAAE,cAAc,EAAa,MAAM,aAAa,CAAC;AAErH,MAAM,WAAW,iBAAiB;IAChC,8CAA8C;IAC9C,YAAY,EAAE,MAAM,CAAC;IACrB,iGAAiG;IACjG,QAAQ,EAAE,MAAM,CAAC;IACjB,wDAAwD;IACxD,UAAU,EAAE,MAAM,CAAC;IACnB,mFAAmF;IACnF,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,cAAc,CAAC;IACxB,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,SAAS,EAAE,cAAc,EAAE,CAAC;IAC5B,UAAU,EAAE,cAAc,EAAE,CAAC;IAC7B,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC;IACxC,WAAW,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;IAC5C,+DAA+D;IAC/D,OAAO,EAAE,MAAM,OAAO,CAAC;IACvB,+EAA+E;IAC/E,KAAK,EAAE,MAAM,eAAe,CAAC;CAC9B;AAyBD,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,GAAG,UAAU,CAoGvE"}

package/dist/aggregate/histogram.d.cts

@@ -0,0 +1,18 @@
+/**
+ * Upper bounds (ms, inclusive) of the render-duration histogram buckets, plus
+ * an implicit overflow bucket. Part of payload v1: the collector merges
+ * histograms by index, so changing these needs a new payload version.
+ */
+export declare const HISTOGRAM_BOUNDS: readonly [1, 2, 4, 8, 12, 16, 24, 33, 50, 75, 100, 150, 250, 500, 1000];
+export declare function createHistogram(): number[];
+export declare function bucketIndex(ms: number): number;
+/**
+ * Estimates a percentile (0–100) from bucket counts, interpolating linearly
+ * inside the bucket. The observed `min` and `max` narrow the bucket's range
+ * (every value lies between them): without them, durations clustered at a
+ * bucket edge, like many renders of exactly 8 ms, would be estimated from
+ * the bucket's middle instead.
+ */
+export declare function histogramPercentile(hist: readonly number[], p: number, max: number, min?: number): number;
+/** Rounds to 0.1 ms: finer precision isn't meaningful and costs payload bytes. */
+export declare function round(ms: number): number;

package/dist/aggregate/histogram.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Upper bounds (ms, inclusive) of the render-duration histogram buckets, plus
+ * an implicit overflow bucket. Part of payload v1: the collector merges
+ * histograms by index, so changing these needs a new payload version.
+ */
+export declare const HISTOGRAM_BOUNDS: readonly [1, 2, 4, 8, 12, 16, 24, 33, 50, 75, 100, 150, 250, 500, 1000];
+export declare function createHistogram(): number[];
+export declare function bucketIndex(ms: number): number;
+/**
+ * Estimates a percentile (0–100) from bucket counts, interpolating linearly
+ * inside the bucket. The observed `min` and `max` narrow the bucket's range
+ * (every value lies between them): without them, durations clustered at a
+ * bucket edge, like many renders of exactly 8 ms, would be estimated from
+ * the bucket's middle instead.
+ */
+export declare function histogramPercentile(hist: readonly number[], p: number, max: number, min?: number): number;
+/** Rounds to 0.1 ms: finer precision isn't meaningful and costs payload bytes. */
+export declare function round(ms: number): number;
+//# sourceMappingURL=histogram.d.ts.map

package/dist/aggregate/histogram.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"histogram.d.ts","sourceRoot":"","sources":["../../src/aggregate/histogram.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,YAAI,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI,CAAU,CAAC;AAExG,wBAAgB,eAAe,IAAI,MAAM,EAAE,CAE1C;AAED,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAK9C;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,SAAI,GAAG,MAAM,CAsBpG;AAED,kFAAkF;AAClF,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAExC"}

package/dist/components/RenderMonitor.d.cts

@@ -0,0 +1,19 @@
+import { type ReactNode } from "react";
+export interface RenderMonitorProps {
+    /** Names this area in reports, e.g. `"orders-table"`. Areas with the same id are reported together. */
+    id: string;
+    children?: ReactNode;
+}
+/**
+ * Measures the renders of its children and reports them under `id`.
+ *
+ * The tree it renders is the same in every mode and whether or not the
+ * session is sampled (a `<Profiler>` around two empty marker components), so
+ * switching modes or calling `initRenderPulse` late never remounts children.
+ * - Profiling mode: React's `<Profiler>` reports each commit's actual render time.
+ * - Lightweight mode: the time between the start and end markers rendering,
+ *   which brackets the children's render. Updates that start below this area
+ *   (a child's own state change) don't re-render the markers, so they aren't
+ *   seen; profiling mode catches those.
+ */
+export declare function RenderMonitor({ id, children }: RenderMonitorProps): ReactNode;

package/dist/components/RenderMonitor.d.ts

@@ -0,0 +1,20 @@
+import { type ReactNode } from "react";
+export interface RenderMonitorProps {
+    /** Names this area in reports, e.g. `"orders-table"`. Areas with the same id are reported together. */
+    id: string;
+    children?: ReactNode;
+}
+/**
+ * Measures the renders of its children and reports them under `id`.
+ *
+ * The tree it renders is the same in every mode and whether or not the
+ * session is sampled (a `<Profiler>` around two empty marker components), so
+ * switching modes or calling `initRenderPulse` late never remounts children.
+ * - Profiling mode: React's `<Profiler>` reports each commit's actual render time.
+ * - Lightweight mode: the time between the start and end markers rendering,
+ *   which brackets the children's render. Updates that start below this area
+ *   (a child's own state change) don't re-render the markers, so they aren't
+ *   seen; profiling mode catches those.
+ */
+export declare function RenderMonitor({ id, children }: RenderMonitorProps): ReactNode;
+//# sourceMappingURL=RenderMonitor.d.ts.map

package/dist/components/RenderMonitor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RenderMonitor.d.ts","sourceRoot":"","sources":["../../src/components/RenderMonitor.tsx"],"names":[],"mappings":"AAEA,OAAO,EAAgE,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAKrG,MAAM,WAAW,kBAAkB;IACjC,uGAAuG;IACvG,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAoBD;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,kBAAkB,GAAG,SAAS,CAyB7E"}

package/dist/context/device.d.cts

@@ -0,0 +1,2 @@
+import type { DeviceContext } from "../types.cjs";
+export declare function getDeviceContext(): DeviceContext;

package/dist/context/device.d.ts

@@ -0,0 +1,3 @@
+import type { DeviceContext } from "../types.js";
+export declare function getDeviceContext(): DeviceContext;
+//# sourceMappingURL=device.d.ts.map

package/dist/context/device.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"device.d.ts","sourceRoot":"","sources":["../../src/context/device.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AASjD,wBAAgB,gBAAgB,IAAI,aAAa,CAShD"}

package/dist/context/route.d.cts

@@ -0,0 +1,7 @@
+/** Default route reader: the path with numeric segments replaced, so `/orders/42` and `/orders/7` group together. */
+export declare function defaultGetRoute(): string;
+/**
+ * Wraps a route reader so it only runs when the URL changes, since it's
+ * called on every measured render.
+ */
+export declare function createRouteReader(getRoute: () => string): () => string;

package/dist/context/route.d.ts

@@ -0,0 +1,8 @@
+/** Default route reader: the path with numeric segments replaced, so `/orders/42` and `/orders/7` group together. */
+export declare function defaultGetRoute(): string;
+/**
+ * Wraps a route reader so it only runs when the URL changes, since it's
+ * called on every measured render.
+ */
+export declare function createRouteReader(getRoute: () => string): () => string;
+//# sourceMappingURL=route.d.ts.map

package/dist/context/route.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../../src/context/route.ts"],"names":[],"mappings":"AAAA,qHAAqH;AACrH,wBAAgB,eAAe,IAAI,MAAM,CAGxC;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,MAAM,GAAG,MAAM,MAAM,CAYtE"}

package/dist/core.cjs

@@ -0,0 +1,56 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/core.ts
+var core_exports = {};
+__export(core_exports, {
+  HISTOGRAM_BOUNDS: () => HISTOGRAM_BOUNDS,
+  histogramPercentile: () => histogramPercentile
+});
+module.exports = __toCommonJS(core_exports);
+
+// src/aggregate/histogram.ts
+var HISTOGRAM_BOUNDS = [1, 2, 4, 8, 12, 16, 24, 33, 50, 75, 100, 150, 250, 500, 1e3];
+function histogramPercentile(hist, p, max, min = 0) {
+  const total = hist.reduce((sum, n) => sum + n, 0);
+  if (total === 0) return 0;
+  const target = Math.max(p / 100 * total, Number.MIN_VALUE);
+  let seen = 0;
+  for (let i = 0; i < hist.length; i++) {
+    const count = hist[i] ?? 0;
+    if (count === 0) continue;
+    if (seen + count >= target) {
+      const upper = Math.min(HISTOGRAM_BOUNDS[i] ?? max, max);
+      const lower = Math.min(Math.max(i === 0 ? 0 : HISTOGRAM_BOUNDS[i - 1] ?? 0, min), upper);
+      const fraction = (target - seen) / count;
+      return round(Math.min(lower + (upper - lower) * fraction, max));
+    }
+    seen += count;
+  }
+  return round(max);
+}
+function round(ms) {
+  return Math.round(ms * 10) / 10;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  HISTOGRAM_BOUNDS,
+  histogramPercentile
+});
+//# sourceMappingURL=core.cjs.map

package/dist/core.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core.ts","../src/aggregate/histogram.ts"],"sourcesContent":["// Framework-agnostic entry: no React imports, so it's safe in Server Components,\n// route handlers, and plain Node. Everything here is also exported from the main entry.\nexport type {\n  AreaReport,\n  DeviceContext,\n  Exporter,\n  LongTaskEvent,\n  LongTaskKind,\n  LongTaskReport,\n  Mode,\n  ModeOption,\n  Payload,\n  RenderEvent,\n  RenderPhase,\n  SessionInfo,\n  SessionSummary,\n  WorstCase,\n} from \"./types.js\";\nexport { HISTOGRAM_BOUNDS, histogramPercentile } from \"./aggregate/histogram.js\";\n","/**\n * Upper bounds (ms, inclusive) of the render-duration histogram buckets, plus\n * an implicit overflow bucket. Part of payload v1: the collector merges\n * histograms by index, so changing these needs a new payload version.\n */\nexport const HISTOGRAM_BOUNDS = [1, 2, 4, 8, 12, 16, 24, 33, 50, 75, 100, 150, 250, 500, 1000] as const;\n\nexport function createHistogram(): number[] {\n  return new Array<number>(HISTOGRAM_BOUNDS.length + 1).fill(0);\n}\n\nexport function bucketIndex(ms: number): number {\n  for (let i = 0; i < HISTOGRAM_BOUNDS.length; i++) {\n    if (ms <= (HISTOGRAM_BOUNDS[i] ?? 0)) return i;\n  }\n  return HISTOGRAM_BOUNDS.length;\n}\n\n/**\n * Estimates a percentile (0–100) from bucket counts, interpolating linearly\n * inside the bucket. The observed `min` and `max` narrow the bucket's range\n * (every value lies between them): without them, durations clustered at a\n * bucket edge, like many renders of exactly 8 ms, would be estimated from\n * the bucket's middle instead.\n */\nexport function histogramPercentile(hist: readonly number[], p: number, max: number, min = 0): number {\n  const total = hist.reduce((sum, n) => sum + n, 0);\n  if (total === 0) return 0;\n\n  const target = Math.max((p / 100) * total, Number.MIN_VALUE);\n  let seen = 0;\n\n  for (let i = 0; i < hist.length; i++) {\n    const count = hist[i] ?? 0;\n    if (count === 0) continue;\n\n    if (seen + count >= target) {\n      const upper = Math.min(HISTOGRAM_BOUNDS[i] ?? max, max);\n      const lower = Math.min(Math.max(i === 0 ? 0 : (HISTOGRAM_BOUNDS[i - 1] ?? 0), min), upper);\n      const fraction = (target - seen) / count;\n      return round(Math.min(lower + (upper - lower) * fraction, max));\n    }\n\n    seen += count;\n  }\n\n  return round(max);\n}\n\n/** Rounds to 0.1 ms: finer precision isn't meaningful and costs payload bytes. */\nexport function round(ms: number): number {\n  return Math.round(ms * 10) / 10;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACKO,IAAM,mBAAmB,CAAC,GAAG,GAAG,GAAG,GAAG,IAAI,IAAI,IAAI,IAAI,IAAI,IAAI,KAAK,KAAK,KAAK,KAAK,GAAI;AAoBtF,SAAS,oBAAoB,MAAyB,GAAW,KAAa,MAAM,GAAW;AACpG,QAAM,QAAQ,KAAK,OAAO,CAAC,KAAK,MAAM,MAAM,GAAG,CAAC;AAChD,MAAI,UAAU,EAAG,QAAO;AAExB,QAAM,SAAS,KAAK,IAAK,IAAI,MAAO,OAAO,OAAO,SAAS;AAC3D,MAAI,OAAO;AAEX,WAAS,IAAI,GAAG,IAAI,KAAK,QAAQ,KAAK;AACpC,UAAM,QAAQ,KAAK,CAAC,KAAK;AACzB,QAAI,UAAU,EAAG;AAEjB,QAAI,OAAO,SAAS,QAAQ;AAC1B,YAAM,QAAQ,KAAK,IAAI,iBAAiB,CAAC,KAAK,KAAK,GAAG;AACtD,YAAM,QAAQ,KAAK,IAAI,KAAK,IAAI,MAAM,IAAI,IAAK,iBAAiB,IAAI,CAAC,KAAK,GAAI,GAAG,GAAG,KAAK;AACzF,YAAM,YAAY,SAAS,QAAQ;AACnC,aAAO,MAAM,KAAK,IAAI,SAAS,QAAQ,SAAS,UAAU,GAAG,CAAC;AAAA,IAChE;AAEA,YAAQ;AAAA,EACV;AAEA,SAAO,MAAM,GAAG;AAClB;AAGO,SAAS,MAAM,IAAoB;AACxC,SAAO,KAAK,MAAM,KAAK,EAAE,IAAI;AAC/B;","names":[]}

package/dist/core.d.cts

@@ -0,0 +1,2 @@
+export type { AreaReport, DeviceContext, Exporter, LongTaskEvent, LongTaskKind, LongTaskReport, Mode, ModeOption, Payload, RenderEvent, RenderPhase, SessionInfo, SessionSummary, WorstCase, } from "./types.cjs";
+export { HISTOGRAM_BOUNDS, histogramPercentile } from "./aggregate/histogram.cjs";

package/dist/core.d.ts

@@ -0,0 +1,3 @@
+export type { AreaReport, DeviceContext, Exporter, LongTaskEvent, LongTaskKind, LongTaskReport, Mode, ModeOption, Payload, RenderEvent, RenderPhase, SessionInfo, SessionSummary, WorstCase, } from "./types.js";
+export { HISTOGRAM_BOUNDS, histogramPercentile } from "./aggregate/histogram.js";
+//# sourceMappingURL=core.d.ts.map

package/dist/core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../src/core.ts"],"names":[],"mappings":"AAEA,YAAY,EACV,UAAU,EACV,aAAa,EACb,QAAQ,EACR,aAAa,EACb,YAAY,EACZ,cAAc,EACd,IAAI,EACJ,UAAU,EACV,OAAO,EACP,WAAW,EACX,WAAW,EACX,WAAW,EACX,cAAc,EACd,SAAS,GACV,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/core.js

@@ -0,0 +1,28 @@
+// src/aggregate/histogram.ts
+var HISTOGRAM_BOUNDS = [1, 2, 4, 8, 12, 16, 24, 33, 50, 75, 100, 150, 250, 500, 1e3];
+function histogramPercentile(hist, p, max, min = 0) {
+  const total = hist.reduce((sum, n) => sum + n, 0);
+  if (total === 0) return 0;
+  const target = Math.max(p / 100 * total, Number.MIN_VALUE);
+  let seen = 0;
+  for (let i = 0; i < hist.length; i++) {
+    const count = hist[i] ?? 0;
+    if (count === 0) continue;
+    if (seen + count >= target) {
+      const upper = Math.min(HISTOGRAM_BOUNDS[i] ?? max, max);
+      const lower = Math.min(Math.max(i === 0 ? 0 : HISTOGRAM_BOUNDS[i - 1] ?? 0, min), upper);
+      const fraction = (target - seen) / count;
+      return round(Math.min(lower + (upper - lower) * fraction, max));
+    }
+    seen += count;
+  }
+  return round(max);
+}
+function round(ms) {
+  return Math.round(ms * 10) / 10;
+}
+export {
+  HISTOGRAM_BOUNDS,
+  histogramPercentile
+};
+//# sourceMappingURL=core.js.map

package/dist/core.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/aggregate/histogram.ts"],"sourcesContent":["/**\n * Upper bounds (ms, inclusive) of the render-duration histogram buckets, plus\n * an implicit overflow bucket. Part of payload v1: the collector merges\n * histograms by index, so changing these needs a new payload version.\n */\nexport const HISTOGRAM_BOUNDS = [1, 2, 4, 8, 12, 16, 24, 33, 50, 75, 100, 150, 250, 500, 1000] as const;\n\nexport function createHistogram(): number[] {\n  return new Array<number>(HISTOGRAM_BOUNDS.length + 1).fill(0);\n}\n\nexport function bucketIndex(ms: number): number {\n  for (let i = 0; i < HISTOGRAM_BOUNDS.length; i++) {\n    if (ms <= (HISTOGRAM_BOUNDS[i] ?? 0)) return i;\n  }\n  return HISTOGRAM_BOUNDS.length;\n}\n\n/**\n * Estimates a percentile (0–100) from bucket counts, interpolating linearly\n * inside the bucket. The observed `min` and `max` narrow the bucket's range\n * (every value lies between them): without them, durations clustered at a\n * bucket edge, like many renders of exactly 8 ms, would be estimated from\n * the bucket's middle instead.\n */\nexport function histogramPercentile(hist: readonly number[], p: number, max: number, min = 0): number {\n  const total = hist.reduce((sum, n) => sum + n, 0);\n  if (total === 0) return 0;\n\n  const target = Math.max((p / 100) * total, Number.MIN_VALUE);\n  let seen = 0;\n\n  for (let i = 0; i < hist.length; i++) {\n    const count = hist[i] ?? 0;\n    if (count === 0) continue;\n\n    if (seen + count >= target) {\n      const upper = Math.min(HISTOGRAM_BOUNDS[i] ?? max, max);\n      const lower = Math.min(Math.max(i === 0 ? 0 : (HISTOGRAM_BOUNDS[i - 1] ?? 0), min), upper);\n      const fraction = (target - seen) / count;\n      return round(Math.min(lower + (upper - lower) * fraction, max));\n    }\n\n    seen += count;\n  }\n\n  return round(max);\n}\n\n/** Rounds to 0.1 ms: finer precision isn't meaningful and costs payload bytes. */\nexport function round(ms: number): number {\n  return Math.round(ms * 10) / 10;\n}\n"],"mappings":";AAKO,IAAM,mBAAmB,CAAC,GAAG,GAAG,GAAG,GAAG,IAAI,IAAI,IAAI,IAAI,IAAI,IAAI,KAAK,KAAK,KAAK,KAAK,GAAI;AAoBtF,SAAS,oBAAoB,MAAyB,GAAW,KAAa,MAAM,GAAW;AACpG,QAAM,QAAQ,KAAK,OAAO,CAAC,KAAK,MAAM,MAAM,GAAG,CAAC;AAChD,MAAI,UAAU,EAAG,QAAO;AAExB,QAAM,SAAS,KAAK,IAAK,IAAI,MAAO,OAAO,OAAO,SAAS;AAC3D,MAAI,OAAO;AAEX,WAAS,IAAI,GAAG,IAAI,KAAK,QAAQ,KAAK;AACpC,UAAM,QAAQ,KAAK,CAAC,KAAK;AACzB,QAAI,UAAU,EAAG;AAEjB,QAAI,OAAO,SAAS,QAAQ;AAC1B,YAAM,QAAQ,KAAK,IAAI,iBAAiB,CAAC,KAAK,KAAK,GAAG;AACtD,YAAM,QAAQ,KAAK,IAAI,KAAK,IAAI,MAAM,IAAI,IAAK,iBAAiB,IAAI,CAAC,KAAK,GAAI,GAAG,GAAG,KAAK;AACzF,YAAM,YAAY,SAAS,QAAQ;AACnC,aAAO,MAAM,KAAK,IAAI,SAAS,QAAQ,SAAS,UAAU,GAAG,CAAC;AAAA,IAChE;AAEA,YAAQ;AAAA,EACV;AAEA,SAAO,MAAM,GAAG;AAClB;AAGO,SAAS,MAAM,IAAoB;AACxC,SAAO,KAAK,MAAM,KAAK,EAAE,IAAI;AAC/B;","names":[]}

package/dist/export/console.d.cts

@@ -0,0 +1,3 @@
+import type { Exporter } from "../types.cjs";
+/** Logs each batch as a table, slowest areas first. Used by default when no `endpoint` is set, for local testing. */
+export declare function createConsoleExporter(): Exporter;

package/dist/export/console.d.ts

@@ -0,0 +1,4 @@
+import type { Exporter } from "../types.js";
+/** Logs each batch as a table, slowest areas first. Used by default when no `endpoint` is set, for local testing. */
+export declare function createConsoleExporter(): Exporter;
+//# sourceMappingURL=console.d.ts.map

package/dist/export/console.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"console.d.ts","sourceRoot":"","sources":["../../src/export/console.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C,qHAAqH;AACrH,wBAAgB,qBAAqB,IAAI,QAAQ,CA2BhD"}

package/dist/export/otel.d.cts

@@ -0,0 +1,34 @@
+import type { Exporter } from "../types.cjs";
+type Attributes = Record<string, string | number | boolean>;
+/**
+ * The parts of an OpenTelemetry `Meter` this exporter uses. Structurally
+ * compatible with `@opentelemetry/api`'s `Meter`, so there's no dependency on it.
+ */
+export interface OtelMeterLike {
+    createHistogram: (name: string, options?: {
+        description?: string;
+        unit?: string;
+    }) => {
+        record: (value: number, attributes?: Attributes) => void;
+    };
+    createCounter: (name: string, options?: {
+        description?: string;
+        unit?: string;
+    }) => {
+        add: (value: number, attributes?: Attributes) => void;
+    };
+}
+export interface OtelExporterOptions {
+    /** e.g. `metrics.getMeter("my-app")` from `@opentelemetry/api`. */
+    meter: OtelMeterLike;
+    /** Renders slower than this also increment `render_pulse.render.slow`. Defaults to 16. */
+    slowRenderMs?: number | undefined;
+}
+/**
+ * Records every measurement as OpenTelemetry metrics:
+ * - `render_pulse.render.duration` (histogram, ms) with `render_pulse.area`, `render_pulse.route`, `render_pulse.phase`, `render_pulse.mode`
+ * - `render_pulse.render.slow` (counter) with the same attributes
+ * - `render_pulse.longtask.duration` (histogram, ms) with `render_pulse.area`, `render_pulse.route`, `render_pulse.kind`
+ */
+export declare function createOtelExporter(options: OtelExporterOptions): Exporter;
+export {};

package/dist/export/otel.d.ts

@@ -0,0 +1,35 @@
+import type { Exporter } from "../types.js";
+type Attributes = Record<string, string | number | boolean>;
+/**
+ * The parts of an OpenTelemetry `Meter` this exporter uses. Structurally
+ * compatible with `@opentelemetry/api`'s `Meter`, so there's no dependency on it.
+ */
+export interface OtelMeterLike {
+    createHistogram: (name: string, options?: {
+        description?: string;
+        unit?: string;
+    }) => {
+        record: (value: number, attributes?: Attributes) => void;
+    };
+    createCounter: (name: string, options?: {
+        description?: string;
+        unit?: string;
+    }) => {
+        add: (value: number, attributes?: Attributes) => void;
+    };
+}
+export interface OtelExporterOptions {
+    /** e.g. `metrics.getMeter("my-app")` from `@opentelemetry/api`. */
+    meter: OtelMeterLike;
+    /** Renders slower than this also increment `render_pulse.render.slow`. Defaults to 16. */
+    slowRenderMs?: number | undefined;
+}
+/**
+ * Records every measurement as OpenTelemetry metrics:
+ * - `render_pulse.render.duration` (histogram, ms) with `render_pulse.area`, `render_pulse.route`, `render_pulse.phase`, `render_pulse.mode`
+ * - `render_pulse.render.slow` (counter) with the same attributes
+ * - `render_pulse.longtask.duration` (histogram, ms) with `render_pulse.area`, `render_pulse.route`, `render_pulse.kind`
+ */
+export declare function createOtelExporter(options: OtelExporterOptions): Exporter;
+export {};
+//# sourceMappingURL=otel.d.ts.map

package/dist/export/otel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"otel.d.ts","sourceRoot":"","sources":["../../src/export/otel.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C,KAAK,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;AAE5D;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,eAAe,EAAE,CACf,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,KAC9C;QAAE,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,UAAU,KAAK,IAAI,CAAA;KAAE,CAAC;IAClE,aAAa,EAAE,CACb,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,KAC9C;QAAE,GAAG,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,UAAU,KAAK,IAAI,CAAA;KAAE,CAAC;CAChE;AAED,MAAM,WAAW,mBAAmB;IAClC,mEAAmE;IACnE,KAAK,EAAE,aAAa,CAAC;IACrB,0FAA0F;IAC1F,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACnC;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,mBAAmB,GAAG,QAAQ,CAkCzE"}

package/dist/hooks/useRenderMonitor.d.cts

@@ -0,0 +1,9 @@
+/**
+ * Tracks the renders of the component that calls it, reported under `id`.
+ *
+ * Render counts are exact. The duration runs from the hook's call to the
+ * commit, so it also includes anything React renders after this component
+ * in the same update: an upper bound. Wrap the component in `<RenderMonitor>`
+ * when you need its own render time.
+ */
+export declare function useRenderMonitor(id: string): void;

package/dist/hooks/useRenderMonitor.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Tracks the renders of the component that calls it, reported under `id`.
+ *
+ * Render counts are exact. The duration runs from the hook's call to the
+ * commit, so it also includes anything React renders after this component
+ * in the same update: an upper bound. Wrap the component in `<RenderMonitor>`
+ * when you need its own render time.
+ */
+export declare function useRenderMonitor(id: string): void;
+//# sourceMappingURL=useRenderMonitor.d.ts.map

package/dist/hooks/useRenderMonitor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useRenderMonitor.d.ts","sourceRoot":"","sources":["../../src/hooks/useRenderMonitor.ts"],"names":[],"mappings":"AAOA;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAgBjD"}