react-render-pulse 0.0.0-stage → 1.0.1

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,319 @@
-# 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)
+
+**Find the React components that slow your app down — on real users' devices.**
+
+React DevTools shows how your app performs on your machine. react-render-pulse shows how it performs for your users: it measures named areas of your component tree in production, summarizes the timings in the browser, and sends small batches to an endpoint you control. You get render counts, slow renders, p50/p75/p95 and the slowest renders per area and route, plus long tasks blamed on the area that was rendering, by device class and app version.
+
+- About **10 µs per measured render** in lightweight mode, and **3.6 kB** (brotli) for the client
+- **Privacy-friendly:** no user IDs, IP addresses, page text, input values or query strings
+- **Never breaks your app:** every internal error is caught; missing browser APIs are handled
+- React 18 and 19, ESM and CommonJS, fully typed, `"use client"` ready for Next.js
+
+📖 **Docs:** https://amalmktk.github.io/react-render-pulse/
+
+**Contents:** [Install](#install) · [Quick start](#quick-start) · [How it works](#how-it-works) · [Collecting results](#collecting-results) · [API](#api) · [Modes](#modes) · [Frameworks](#frameworks) · [What gets sent](#what-gets-sent) · [Performance](#performance) · [Limitations](#limitations)
+
+## Install
+
+```bash
+npm install react-render-pulse
+```
+
+React 18 or 19 is a peer dependency. There are no other runtime dependencies.
+
+## Quick start
+
+**1. Start it once,** in the browser, before your app renders:
+
+```tsx
+// src/main.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 instead
+  sampleRate: 0.1, // 10% of page loads
+  appVersion: import.meta.env.VITE_APP_VERSION, // compare releases
+});
+
+createRoot(document.getElementById("root")!).render(<App />);
+```
+
+**2. Wrap the areas you care about.** Areas can be nested:
+
+```tsx
+import { RenderMonitor } from "react-render-pulse";
+
+export function OrdersPage() {
+  return (
+    <RenderMonitor id="orders-page">
+      <Filters />
+      <RenderMonitor id="orders-table">
+        <OrdersTable />
+      </RenderMonitor>
+    </RenderMonitor>
+  );
+}
+```
+
+Or track a single component with the hook:
+
+```tsx
+import { useRenderMonitor } from "react-render-pulse";
+
+function PriceChart() {
+  useRenderMonitor("price-chart");
+  return <Chart />;
+}
+```
+
+**3. Try it.** Without an `endpoint`, use the page, then switch tabs: the batch is logged to the console as a table, slowest areas first. With an `endpoint`, it's `POST`ed there; see [Collecting results](#collecting-results).
+
+`<RenderMonitor>` adds no DOM elements and never remounts its children, in any mode, whether or not the session is sampled.
+
+## How it works
+
+```
+ <RenderMonitor> / useRenderMonitor ──► in-memory aggregator ──► batch ──► your endpoint ──► storage ──► viewer / SQL
+        render timings                   per area + route:        sent on page hide        (react-render-pulse-collector)
+ PerformanceObserver ──► long tasks      histogram, counts,       (sendBeacon) and every
+   and long animation frames,            worst cases              3 minutes (fetch keepalive)
+   blamed on the area rendering
+```
+
+1. **Sample:** once per page load, decide whether to measure (`sampleRate`). Unsampled sessions do almost nothing.
+2. **Measure:** time each monitored area's renders (see [Modes](#modes)) and observe long tasks.
+3. **Aggregate:** keep counts, a 16-bucket histogram and the 5 slowest renders per area + route, never raw events. Memory stays flat.
+4. **Send:** when the page is hidden, and every 3 minutes while it's open. Batches are trimmed to 60 KB, sent with `sendBeacon` (falling back to `fetch` with `keepalive`), and retried on `429`/`5xx`.
+
+Full details: [Architecture](https://amalmktk.github.io/react-render-pulse/guide/architecture).
+
+## Collecting results
+
+Batches need somewhere to go. You can use the companion packages, your own endpoint, or OpenTelemetry.
+
+**With [`react-render-pulse-collector`](https://www.npmjs.com/package/react-render-pulse-collector)**, a standard `Request` → `Response` handler that validates and stores batches. On Next.js:
+
+```ts
+// app/api/render-pulse/route.ts
+import { createCollector } from "react-render-pulse-collector";
+import { postgresStorage } from "react-render-pulse-collector/postgres";
+
+const collect = createCollector({ storage: postgresStorage({ url: process.env.DATABASE_URL! }) });
+
+export const POST = collect;
+export const OPTIONS = collect;
+```
+
+It also runs on Vercel, Netlify, Cloudflare Workers and Express, and stores to Postgres or a JSON Lines file.
+
+**Read them with [`react-render-pulse-viewer`](https://www.npmjs.com/package/react-render-pulse-viewer):**
+
+```bash
+npx react-render-pulse-viewer report --db "$DATABASE_URL" --since 7d   # terminal tables
+npx react-render-pulse-viewer serve --db "$DATABASE_URL"               # web viewer on 127.0.0.1:4173
+```
+
+**Or query Postgres yourself.** Each batch is one row with the payload as `jsonb`:
+
+```sql
+SELECT a->>'id' AS area, a->>'route' AS route,
+       sum((a->>'renders')::int) AS renders,
+       round(100.0 * sum((a->>'slow')::int) / nullif(sum((a->>'renders')::int), 0), 1) AS slow_pct
+FROM render_pulse_batches b
+CROSS JOIN LATERAL jsonb_array_elements(b.payload->'areas') AS a
+WHERE b.received_at > now() - interval '7 days'
+GROUP BY 1, 2
+ORDER BY slow_pct DESC NULLS LAST;
+```
+
+**Or send to OpenTelemetry** with `createOtelExporter` (below). No collector is needed.
+
+Step-by-step guide, more SQL, and troubleshooting: [Collecting results](https://amalmktk.github.io/react-render-pulse/guide/collecting-results).
+
+## API
+
+### `initRenderPulse(options?)`
+
+Starts measuring. Call it once, in the browser, before your app renders. Calling it again replaces the previous setup. On the server it does nothing.
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `endpoint` | `string` | — | Where batches are `POST`ed. Without one, batches only go to `exporters` and the console. |
+| `sampleRate` | `number` (0–1) | `1` | Fraction of page loads that measure anything, decided once per page load. |
+| `mode` | `"auto" \| "lightweight" \| "profiling"` | `"auto"` | How renders are measured. See [Modes](#modes). |
+| `slowRenderMs` | `number` | `16` | Renders slower than this count as slow (one frame at 60 Hz). |
+| `longTaskMs` | `number` | `50` | Shorter long tasks and long animation frames are ignored. |
+| `appVersion` | `string` | — | Your app's version, for comparing releases. |
+| `getRoute` | `() => string` | path with numeric segments → `:id` | The current route, ideally a template like `/orders/:id`. |
+| `flushIntervalMs` | `number` | `180000` | Also send this often while the page is open. `0` sends only when it's hidden. |
+| `maxPayloadBytes` | `number` | `60000` | Largest batch; bigger ones are trimmed. Capped at 65536. |
+| `maxAreas` | `number` | `200` | Most area + route pairs per batch. Capped at 1000. |
+| `worstCases` | `number` | `5` | Slowest renders kept per area per batch. Capped at 50. |
+| `exporters` | `Exporter[]` | — | Receive measurements and batches, e.g. `createOtelExporter`. |
+| `debug` | `boolean` | `true` without `endpoint` | Log each batch to the console, and internal errors as warnings. |
+
+Returns `{ sampled, mode, flush(), destroy() }`:
+
+- `sampled`: whether this page load measures anything.
+- `mode`: the current mode; in `"auto"` it changes to `"profiling"` once React's profiling build is detected.
+- `flush()`: sends a batch now and returns it, or `null` if nothing was measured.
+- `destroy()`: stops observing and sending. Monitors keep rendering their children.
+
+### `<RenderMonitor id children />`
+
+Measures the renders of its children as one area named `id`. Areas with the same `id` are reported together. Nested areas are reported separately, and an outer area's time includes its inner ones.
+
+### `useRenderMonitor(id)`
+
+Measures the component that calls it. Render counts are exact. The duration runs from the hook to the commit, so it's an upper bound that can include components rendered after it in the same update.
+
+### Exporters
+
+An exporter receives data as it's measured:
+
+```ts
+interface Exporter {
+  onRender?: (event: RenderEvent) => void; // every measured render
+  onLongTask?: (event: LongTaskEvent) => void; // every long task / long animation frame
+  onFlush?: (payload: Payload) => void; // every batch
+}
+```
+
+Built in:
+
+- `createConsoleExporter()` logs each batch as a table. It's used automatically when `debug` is on.
+- `createOtelExporter({ meter, slowRenderMs? })` from `react-render-pulse/otel` records OpenTelemetry metrics: `render_pulse.render.duration` and `render_pulse.longtask.duration` (histograms, ms) and `render_pulse.render.slow` (counter), with area, route, phase and mode attributes.
+
+```ts
+import { metrics } from "@opentelemetry/api";
+import { createOtelExporter } from "react-render-pulse/otel";
+
+initRenderPulse({ exporters: [createOtelExporter({ meter: metrics.getMeter("my-app") })] });
+```
+
+### Entry points
+
+| Import | Contents |
+| --- | --- |
+| `react-render-pulse` | `initRenderPulse`, `RenderMonitor`, `useRenderMonitor`, `createConsoleExporter`, `HISTOGRAM_BOUNDS`, `histogramPercentile`, and all types. Marked `"use client"`. |
+| `react-render-pulse/core` | Types, `HISTOGRAM_BOUNDS`, `histogramPercentile`. No React; safe in servers and Server Components. |
+| `react-render-pulse/otel` | `createOtelExporter`. |
+
+Types: `Payload`, `AreaReport`, `LongTaskReport`, `SessionInfo`, `SessionSummary`, `DeviceContext`, `WorstCase`, `RenderEvent`, `LongTaskEvent`, `Exporter`, `Mode`, `ModeOption`, `RenderPhase`, `RenderPulseOptions`, `RenderPulse`, `RenderMonitorProps`.
+
+Full reference: [Client API](https://amalmktk.github.io/react-render-pulse/api/client).
+
+## Modes
+
+|  | Lightweight | Profiling |
+| --- | --- | --- |
+| How it measures | Two marker components around each area time its render | React's `<Profiler>` reports each commit's render time |
+| Needs | Any production build | React's profiling build |
+| Sees updates that start inside an area | No: wrap the component that owns the state, or use `useRenderMonitor` in it | Yes |
+| Cost | ~10 µs per measured render | About the same as a bare `<Profiler>`, which is the profiling build's own cost |
+| Use for | Every production user | A sampled group or staging |
+
+`mode: "auto"` (the default) starts in lightweight mode and switches to profiling mode when React's profiling build is detected. To enable the profiling build:
+
+```ts
+// vite.config.ts: `vite build --mode profiling`
+export default defineConfig(({ mode }) => ({
+  plugins: [react()],
+  resolve: { alias: mode === "profiling" ? { "react-dom/client": "react-dom/profiling" } : {} },
+}));
+```
+
+```bash
+next build --profile   # Next.js
+```
+
+More: [Modes](https://amalmktk.github.io/react-render-pulse/guide/modes).
+
+## Frameworks
+
+**Vite / any SPA:** call `initRenderPulse` in your entry file before `createRoot(...).render(...)`.
+
+**Next.js App Router:** use `instrumentation-client.ts` at the project root, which runs before hydration. `<RenderMonitor>` can be used directly in Server Components, because the package is marked `"use client"`.
+
+```ts
+// instrumentation-client.ts
+import { initRenderPulse } from "react-render-pulse";
+
+initRenderPulse({
+  endpoint: "/api/render-pulse",
+  getRoute: () => location.pathname.replace(/^\/orders\/[^/]+/, "/orders/[id]"),
+});
+```
+
+**Next.js Pages Router:** call it at the top level of `pages/_app.tsx`, inside `if (typeof window !== "undefined")`.
+
+**React Router:** report route patterns with `matchRoutes`:
+
+```ts
+getRoute: () => {
+  const pattern = (matchRoutes(routes, router.state.location) ?? [])
+    .map((m) => m.route.path ?? "")
+    .filter(Boolean)
+    .join("/")
+    .replace(/\/+/g, "/");
+  return pattern.startsWith("/") ? pattern : `/${pattern}`;
+},
+```
+
+Full setups, with working example apps: [Frameworks](https://amalmktk.github.io/react-render-pulse/guide/frameworks) · [examples/](https://github.com/Amalmktk/react-render-pulse/tree/main/examples).
+
+## What gets sent
+
+One JSON object per batch (trimmed here):
+
+```json
+{
+  "v": 1,
+  "session": { "id": "5f0c9a1e-…", "seq": 1, "mode": "lightweight", "route": "/orders", "appVersion": "2.4.0" },
+  "device": { "memoryGb": 4, "cores": 8, "connection": "4g", "viewport": "390x844" },
+  "summary": { "renders": 42, "slowRenders": 5, "longTasks": 3, "longTaskMs": 400 },
+  "areas": [
+    { "id": "orders-table", "route": "/orders", "renders": 42, "slow": 5, "p50": 6.1, "p75": 11.8, "p95": 38.2, "max": 61.2, "hist": [] }
+  ],
+  "longTasks": [{ "area": "orders-table", "route": "/orders", "count": 3, "maxMs": 212 }]
+}
+```
+
+- **Never collected:** user IDs, IP addresses, cookies, page text, input values, query strings.
+- **The session id** is random per page load, held in memory only, and can't identify a user.
+- **Routes** come from `location.pathname` via `getRoute`. The default only replaces numeric segments, so normalize UUIDs, usernames or slugs in `getRoute`.
+
+Every field: [What we collect](https://amalmktk.github.io/react-render-pulse/guide/what-we-collect).
+
+## Performance
+
+Measured in Chromium with a benchmark that re-renders a whole app (8 monitored areas) per update, in paired A/B blocks:
+
+| Mode | Added per measured render | Accuracy (known 2 / 8 / 20 ms components) |
+| --- | --- | --- |
+| Lightweight (production build) | 0.006–0.014 ms | 2.0 / 8.0 / 20.0 ms |
+| Profiling (profiling build) | ~0.07–0.08 ms, the same as a bare `<Profiler>` | 2.0 / 8.0 / 20.1 ms |
+
+The client is 3.6 kB brotli (`initRenderPulse` + `RenderMonitor` + `useRenderMonitor`). CI fails a pull request that exceeds the overhead or size budget. Method and reproduction: [Performance](https://amalmktk.github.io/react-render-pulse/guide/performance).
+
+## Limitations
+
+- Lightweight mode doesn't see updates that start below an area, such as a child's own state change. Monitor the component that owns the state, or use profiling mode for those sessions.
+- `useRenderMonitor` durations are an upper bound. Use `<RenderMonitor>` around the component for its own render time.
+- Long tasks are observed only where the browser supports them: Chromium for long tasks and long animation frames. Other browsers still report render timings.
+- Profiling mode needs React's profiling build, which is slower than the regular build. Ship it to a sample, not everyone.
+
+## Related packages
+
+- [`react-render-pulse-collector`](https://www.npmjs.com/package/react-render-pulse-collector): validates and stores batches (Postgres, JSON file, custom)
+- [`react-render-pulse-viewer`](https://www.npmjs.com/package/react-render-pulse-viewer): terminal report and web viewer
+
+## 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":[]}