@ogygia/devtools 0.0.0-stage → 0.11.0

package/dist/profiler/span.d.ts

@@ -0,0 +1,90 @@
+import { CallerSite } from "./net.js";
+export type SpanAttrs = Record<string, string | number | boolean>;
+export interface SpanRecord {
+  id: number;
+  name: string;
+  /** performance.now() at start */
+  start: number;
+  /** duration; -1 while running (an `open` span at the end of a recording keeps -1) */
+  ms: number;
+  attrs?: SpanAttrs;
+  /** the thrown error's message, when `fn` threw / the handle was `fail`ed */
+  error?: string;
+  /** never ended before the recording stopped */
+  open?: boolean;
+  /** the enclosing span's id, when nested */
+  parent?: number;
+  /** resolved at report time from `caller_site` (same as an outbound call's) */
+  caller?: string;
+  caller_site?: CallerSite;
+  /** the page render that ran it, when known */
+  route: string | null;
+  path: string | null;
+}
+/** What the profiler host installs while a recording runs. */
+export interface SpanRecorder {
+  begin(name: string, attrs?: SpanAttrs): SpanRecord;
+  /** run `fn` with `s` as the current span (nesting); the host binds it to its async context */
+  within<T>(s: SpanRecord, fn: () => T): T;
+  end(s: SpanRecord, attrs?: SpanAttrs, error?: unknown): void;
+  tag(key: string, value: string): void;
+}
+/** The profiler host installs a recorder for a recording; `null` uninstalls. */
+export declare function set_span_recorder(r: SpanRecorder | null): void;
+/** Whether a recorder is installed (tests / the host). */
+export declare function span_recording(): boolean;
+/** A span opened by hand (`span.start`) for what a callback cannot wrap: a stream, an event. */
+export interface SpanHandle {
+  /** add or change an attribute while the span runs */
+  set(key: string, value: string | number | boolean): void;
+  /** close it; ending twice is a no-op */
+  end(attrs?: SpanAttrs): void;
+  /** close it as failed */
+  fail(error: unknown): void;
+}
+/**
+ * Run `fn` as a named span. Sync in, sync out; a promise in, a promise out — the wrapper never
+ * changes the shape of what it wraps. A throw (or rejection) is recorded on the span and rethrown.
+ * `attrs` is a plain record, or a function of the result for what is only known afterwards
+ * (`(r) => ({ cache: r.fromCache ? 'hit' : 'miss', rows: r.length })`). Reserved keys the report
+ * reads: `cache` ('hit' | 'miss'), `rows`, `bytes`, `key`; anything else is carried and shown.
+ */
+export declare function span<T>(name: string, fn: () => T, attrs?: SpanAttrs | ((result: Awaited<T>) => SpanAttrs | undefined)): T;
+export declare namespace span {
+  export var start: (name: string, attrs?: SpanAttrs) => SpanHandle;
+}
+/** Stamp the current request with `key = value` (string, number or boolean; kept to 64 chars, at
+ *  most 16 keys). Shown on the request's log row and in the report; the dashboard splits the
+ *  slowest routes by any tag. A no-op outside a recording, and always on the client. */
+export declare function tag(key: string, value: string | number | boolean): void;
+/**
+ * INSTRUMENT a function once, so every call is a `span` — for a renderer or a client you call
+ * from many places and cannot wrap at each site: a design system's `renderToString`, a database
+ * client's `query`, an SDK method.
+ *
+ * Two forms:
+ *   • `instrument(fn, name, attrs?)` returns a wrapped function (an ESM import is read-only, so
+ *     bind the result: `const renderToString = instrument(renderToStringCore, 'ds.render')`).
+ *   • `instrument(obj, 'method', name, attrs?)` patches the method in place (a client instance,
+ *     a prototype) and returns a function that restores it.
+ *
+ * `attrs` gets the result AND the call's arguments, so a span can carry the tag it rendered or
+ * the bytes it produced: `(html, tag) => ({ tag, bytes: html.length })`. Sync in, sync out; a
+ * promise in, a promise out; `this` preserved. Outside a recording the wrapper is one `if`.
+ *
+ * ```ts
+ * import { instrument } from '@ogygia/devtools/profiler';
+ * import { renderToString as core } from '@acme/design-system/hydrate';
+ * const renderToString = instrument(core, 'ds.render', (r, tag) => ({ tag, bytes: r.html.length }));
+ * ```
+ */
+/** The attrs callback of `instrument`: the result, then the call's arguments. Declared method-style
+ *  so a callback naming fewer arguments than the function takes (`(r, tag) => …` for a two-argument
+ *  renderer) is accepted, and so it never narrows the wrapped signature. `NoInfer` wraps the whole
+ *  callback, not its rest argument: on the rest tuple alone it made a shorter callback a tuple-length
+ *  mismatch, so the `(r, tag) => …` form above did not type-check. */
+export type InstrumentAttrs<A extends unknown[], R> = NoInfer<{
+  bivariant(result: Awaited<R>, ...args: A): SpanAttrs | undefined;
+}["bivariant"]>;
+export declare function instrument<A extends unknown[], R>(fn: (...args: A) => R, name: string, attrs?: InstrumentAttrs<A, R>): (...args: A) => R;
+export declare function instrument<T extends object, K extends keyof T>(target: T, method: K, name: string, attrs?: T[K] extends ((...args: infer A) => infer R) ? InstrumentAttrs<A, R> : never): () => void;

package/dist/profiler/span.js

@@ -0,0 +1,109 @@
+import { register_profiler_file } from "./frames.js";
+// src/profiler/span.ts
+register_profiler_file();
+let recorder = null;
+/** The profiler host installs a recorder for a recording; `null` uninstalls. */
+function set_span_recorder(r) {
+	recorder = r;
+}
+/** Whether a recorder is installed (tests / the host). */
+function span_recording() {
+	return recorder !== null;
+}
+const NOOP_HANDLE = {
+	set() {},
+	end() {},
+	fail() {}
+};
+const is_thenable = (v) => !!v && typeof v.then === "function";
+/**
+* Run `fn` as a named span. Sync in, sync out; a promise in, a promise out — the wrapper never
+* changes the shape of what it wraps. A throw (or rejection) is recorded on the span and rethrown.
+* `attrs` is a plain record, or a function of the result for what is only known afterwards
+* (`(r) => ({ cache: r.fromCache ? 'hit' : 'miss', rows: r.length })`). Reserved keys the report
+* reads: `cache` ('hit' | 'miss'), `rows`, `bytes`, `key`; anything else is carried and shown.
+*/
+function span(name, fn, attrs) {
+	const r = recorder;
+	if (r === null) return fn();
+	const s = r.begin(name, typeof attrs === "function" ? void 0 : attrs);
+	const finish = (result, error) => {
+		let extra;
+		if (typeof attrs === "function" && error === void 0) try {
+			extra = attrs(result);
+		} catch {}
+		r.end(s, extra, error);
+	};
+	let out;
+	try {
+		out = r.within(s, fn);
+	} catch (e) {
+		finish(void 0, e ?? /* @__PURE__ */ new Error("span failed"));
+		throw e;
+	}
+	if (is_thenable(out)) return out.then((v) => {
+		finish(v);
+		return v;
+	}, (e) => {
+		finish(void 0, e ?? /* @__PURE__ */ new Error("span failed"));
+		throw e;
+	});
+	finish(out);
+	return out;
+}
+/** Open a span by hand; close it with `end` / `fail`. Nesting: spans started while another span's
+*  `fn` runs record it as their parent; a bare `span.start` at the top level has none. */
+span.start = function start(name, attrs) {
+	const r = recorder;
+	if (r === null) return NOOP_HANDLE;
+	const s = r.begin(name, attrs);
+	let done = false;
+	return {
+		set(key, value) {
+			(s.attrs ??= {})[key] = value;
+		},
+		end(extra) {
+			if (done) return;
+			done = true;
+			r.end(s, extra);
+		},
+		fail(error) {
+			if (done) return;
+			done = true;
+			r.end(s, void 0, error ?? /* @__PURE__ */ new Error("span failed"));
+		}
+	};
+};
+/** Stamp the current request with `key = value` (string, number or boolean; kept to 64 chars, at
+*  most 16 keys). Shown on the request's log row and in the report; the dashboard splits the
+*  slowest routes by any tag. A no-op outside a recording, and always on the client. */
+function tag(key, value) {
+	const r = recorder;
+	if (r === null || !key) return;
+	r.tag(String(key).slice(0, 64), String(value).slice(0, 64));
+}
+function instrument(...args) {
+	if (typeof args[0] === "function") {
+		const [fn, name, attrs] = args;
+		return wrap_call(fn, name, attrs);
+	}
+	const [target, method, name, attrs] = args;
+	const original = target[method];
+	if (typeof original !== "function") throw new Error(`instrument: ${String(method)} is not a function`);
+	target[method] = wrap_call(original, name, attrs);
+	return () => {
+		target[method] = original;
+	};
+}
+function wrap_call(fn, name, attrs) {
+	const wrapped = function(...a) {
+		if (recorder === null) return fn.apply(this, a);
+		return span(name, () => fn.apply(this, a), attrs ? (result) => attrs(result, ...a) : void 0);
+	};
+	try {
+		Object.defineProperty(wrapped, "name", { value: fn.name || name });
+		Object.defineProperty(wrapped, "length", { value: fn.length });
+	} catch {}
+	return wrapped;
+}
+export { instrument, set_span_recorder, span, span_recording, tag };

package/dist/profiler/stacks.d.ts

@@ -0,0 +1,43 @@
+import { FrameCategory, StackIndex } from "./analyze.js";
+export interface RangeRow {
+  /** the frame's name */
+  name: string;
+  file?: string;
+  category: FrameCategory;
+  /** ms the frame was the leaf (running itself) inside the range */
+  self_ms: number;
+  /** ms the frame was anywhere on the stack inside the range */
+  total_ms: number;
+}
+export interface RangeSummary {
+  t0: number;
+  t1: number;
+  /** CPU inside the range (idle samples excluded) */
+  cpu_ms: number;
+  idle_ms: number;
+  /** by self time, desc */
+  self: RangeRow[];
+  /** by inclusive time, desc — the owners of the range */
+  total: RangeRow[];
+  /** the components on the stacks in the range, by inclusive time */
+  components: RangeRow[];
+}
+/** What ran between `t0` and `t1` (ms from the window's start): self and inclusive time per
+ *  frame, the components among them. A sample that straddles an edge counts by its overlap. */
+export declare function range_hot(index: StackIndex, t0: number, t1: number, limit?: number): RangeSummary;
+export interface StackAt {
+  t: number;
+  /** the sample's length */
+  ms: number;
+  /** the stack, outermost first; empty when idle */
+  frames: {
+    name: string;
+    file?: string;
+    category: FrameCategory;
+  }[];
+}
+/** The stack at instant `t` (ms from the window's start). */
+export declare function stack_at(index: StackIndex, t: number): StackAt | null;
+/** The CPU of the window as `bins` equal slices: ms of CPU per slice, for a density strip.
+ *  `by`: 'all' for any frame; a category to count only samples whose leaf is that category. */
+export declare function density(index: StackIndex, bins?: number, by?: "all" | FrameCategory): number[];

package/dist/profiler/stacks.js

@@ -0,0 +1,107 @@
+// src/profiler/stacks.ts
+const round2 = (n) => Math.round(n * 100) / 100;
+/** the first sample index whose end reaches `t` (binary search on the sorted starts) */
+function first_at(index, t) {
+	let lo = 0;
+	let hi = index.t.length;
+	while (lo < hi) {
+		const mid = lo + hi >> 1;
+		if (index.t[mid] + index.d[mid] < t) lo = mid + 1;
+		else hi = mid;
+	}
+	return lo;
+}
+/** What ran between `t0` and `t1` (ms from the window's start): self and inclusive time per
+*  frame, the components among them. A sample that straddles an edge counts by its overlap. */
+function range_hot(index, t0, t1, limit = 30) {
+	const self = /* @__PURE__ */ new Map();
+	const total = /* @__PURE__ */ new Map();
+	let cpu = 0;
+	let idle = 0;
+	const seen = [];
+	for (let i = first_at(index, t0); i < index.t.length; i++) {
+		const s = index.t[i];
+		if (s > t1) break;
+		const e = s + index.d[i];
+		const ms = Math.min(e, t1) - Math.max(s, t0);
+		if (ms <= 0) continue;
+		const leaf = index.leaf[i];
+		if (leaf < 0) {
+			idle += ms;
+			continue;
+		}
+		cpu += ms;
+		self.set(leaf, (self.get(leaf) ?? 0) + ms);
+		seen.length = 0;
+		for (let f = leaf; f >= 0; f = index.frames[f].p) {
+			if (seen.includes(f)) continue;
+			seen.push(f);
+			total.set(f, (total.get(f) ?? 0) + ms);
+		}
+	}
+	const row = (f) => {
+		const fr = index.frames[f];
+		return {
+			name: fr.n,
+			...fr.f ? { file: fr.f } : {},
+			category: fr.c,
+			self_ms: round2(self.get(f) ?? 0),
+			total_ms: round2(total.get(f) ?? 0)
+		};
+	};
+	const by_self = [...self.keys()].sort((a, b) => self.get(b) - self.get(a)).slice(0, limit).map(row);
+	const by_total = [...total.keys()].sort((a, b) => total.get(b) - total.get(a));
+	const components = by_total.filter((f) => index.frames[f].c === "component").slice(0, limit).map(row);
+	return {
+		t0: round2(t0),
+		t1: round2(t1),
+		cpu_ms: round2(cpu),
+		idle_ms: round2(idle),
+		self: by_self,
+		total: by_total.slice(0, limit).map(row),
+		components
+	};
+}
+/** The stack at instant `t` (ms from the window's start). */
+function stack_at(index, t) {
+	const i = first_at(index, t);
+	if (i >= index.t.length || index.t[i] > t) return null;
+	const frames = [];
+	for (let f = index.leaf[i]; f >= 0; f = index.frames[f].p) {
+		const fr = index.frames[f];
+		frames.push({
+			name: fr.n,
+			...fr.f ? { file: fr.f } : {},
+			category: fr.c
+		});
+	}
+	frames.reverse();
+	return {
+		t: round2(index.t[i]),
+		ms: round2(index.d[i]),
+		frames
+	};
+}
+/** The CPU of the window as `bins` equal slices: ms of CPU per slice, for a density strip.
+*  `by`: 'all' for any frame; a category to count only samples whose leaf is that category. */
+function density(index, bins = 200, by = "all") {
+	const out = Array.from({ length: bins }, () => 0);
+	const w = index.window_ms || 1;
+	for (let i = 0; i < index.t.length; i++) {
+		const leaf = index.leaf[i];
+		if (leaf < 0) continue;
+		if (by !== "all" && index.frames[leaf].c !== by) continue;
+		const s = index.t[i];
+		const e = s + index.d[i];
+		let b0 = Math.floor(s / w * bins);
+		const b1 = Math.min(bins - 1, Math.floor(e / w * bins));
+		if (b0 < 0) b0 = 0;
+		for (let b = b0; b <= b1; b++) {
+			const bs = b / bins * w;
+			const be = (b + 1) / bins * w;
+			out[b] += Math.max(0, Math.min(e, be) - Math.max(s, bs));
+		}
+	}
+	return out.map(round2);
+}
+export { density, range_hot, stack_at };

package/dist/profiler/standalone.d.ts

@@ -0,0 +1,27 @@
+/**
+ * STANDALONE REPORT — one HTML file that opens from disk, islands and all.
+ *
+ * The report page is an ogygia document: server markup, a runtime `<script type="module" src>`,
+ * `<ogygia-region entry="…">` islands whose chunks are `import()`ed by URL, stylesheet links. None
+ * of that survives `file://`. This turns it into a single file:
+ *
+ *   • every stylesheet link becomes a `<style>`;
+ *   • every JS chunk the page can reach (the runtime, each island entry, and everything they
+ *     import, transitively) is fetched once, its relative imports rewritten to bare `og:<path>`
+ *     specifiers, and shipped as a `data:` URL in ONE import map — dynamic `import('og:…')` from
+ *     the runtime resolves through the map, so islands hydrate exactly as on the server;
+ *   • the runtime script is inlined as a module; modulepreload hints are dropped (nothing to fetch);
+ *   • island `entry` attributes are rewritten to their `og:` keys.
+ *
+ * Pure: the caller supplies `load(url)` (a self-fetch in the profiler host, a map in tests). Dev
+ * servers are refused upstream — their module graph is Vite's, not a bundle.
+ */
+export interface StandaloneOptions {
+  /** the report page's own URL (relative hrefs resolve against it) */
+  page_url: string;
+  /** fetch a same-origin asset by absolute URL; `null` when it cannot be read */
+  load: (url: string) => Promise<string | null>;
+  /** refuse past this many bytes of inlined assets (a runaway graph) */
+  max_bytes?: number;
+}
+export declare function build_standalone(html: string, opts: StandaloneOptions): Promise<string>;

package/dist/profiler/standalone.js

@@ -0,0 +1,98 @@
+// src/profiler/standalone.ts
+const STYLESHEET_RE = /<link\b[^>]*\brel=["']stylesheet["'][^>]*>/gi;
+const MODULEPRELOAD_RE = /<link\b[^>]*\brel=["']modulepreload["'][^>]*>/gi;
+const HREF_RE = /\bhref=["']([^"']+)["']/i;
+const MODULE_SCRIPT_RE = /<script\b([^>]*\btype=["']module["'][^>]*)\bsrc=["']([^"']+)["']([^>]*)><\/script>/gi;
+const ENTRY_ATTR_RE = /(<ogygia-region\b[^>]*\bentry=["'])([^"']+)(["'])/gi;
+/** a static or dynamic import of a RELATIVE specifier inside a built chunk — quoted, or a
+*  template literal with no interpolation (Vite emits `import(\`./chunks/x.js\`)`) */
+const IMPORT_RE = /((?:\bfrom|\bimport)\s*\(?\s*)(["'`])(\.{1,2}\/[^"'`$]+)\2/g;
+/** any other relative chunk path in a string: Vite's `__vite__mapDeps` preload list. Pointed at
+*  the same keys so a preload link never resolves against the document (a `file://` fetch). */
+const DEP_STRING_RE = /(["'])(\.{1,2}\/[^"'`\s]+\.(?:js|css))\1/g;
+/** The import-map key for a chunk. An absolute URL with a `//` authority on purpose: the runtime's
+*  `island_module_url` hands an `entry` with a URL scheme through untouched (a bare `og:/x` would
+*  be resolved against the document and lose the scheme), and a `data:` module can import an
+*  absolute URL where it cannot import a relative one. */
+const key_of = (u) => `og://chunks${u.pathname}`;
+async function build_standalone(html, opts) {
+	const base = new URL(opts.page_url);
+	const max = opts.max_bytes ?? 12582912;
+	let bytes = 0;
+	const chunks = /* @__PURE__ */ new Map();
+	const missing = [];
+	const fetch_text = async (u) => {
+		const text = await opts.load(u.href);
+		if (text === null) {
+			missing.push(u.pathname);
+			return null;
+		}
+		bytes += text.length;
+		if (bytes > max) throw new Error(`standalone report would exceed ${Math.round(max / 1048576)} MB of inlined assets`);
+		return text;
+	};
+	/** rewrite a chunk's relative imports to `og:` keys and pull those chunks in too */
+	const add_chunk = async (u) => {
+		const key = key_of(u);
+		if (chunks.get(key) !== void 0) return key;
+		chunks.set(key, "");
+		const src = await fetch_text(u);
+		if (src === null) return key;
+		const deps = [];
+		const rewritten = src.replace(IMPORT_RE, (_, lead, q, spec) => {
+			const dep = new URL(spec, u);
+			deps.push(dep);
+			return `${lead}${q}${key_of(dep)}${q}`;
+		}).replace(DEP_STRING_RE, (_, q, spec) => {
+			const dep = new URL(spec, u);
+			if (spec.endsWith(".js")) deps.push(dep);
+			return `${q}${key_of(dep)}${q}`;
+		});
+		chunks.set(key, rewritten);
+		for (const dep of deps) await add_chunk(dep);
+		return key;
+	};
+	const sheets = [];
+	for (const m of html.matchAll(STYLESHEET_RE)) {
+		const href = HREF_RE.exec(m[0])?.[1];
+		if (href) sheets.push({
+			tag: m[0],
+			url: new URL(href, base)
+		});
+	}
+	for (const s of sheets) {
+		const css = await fetch_text(s.url);
+		html = html.replace(s.tag, css === null ? "" : `<style data-standalone="${s.url.pathname}">${css.replaceAll("</style", "<\\/style")}</style>`);
+	}
+	html = html.replace(MODULEPRELOAD_RE, "");
+	const scripts = [];
+	for (const m of html.matchAll(MODULE_SCRIPT_RE)) scripts.push({
+		tag: m[0],
+		attrs: (m[1] + " " + m[3]).replace(/\s+/g, " ").trim(),
+		url: new URL(m[2], base)
+	});
+	for (const s of scripts) {
+		const key = await add_chunk(s.url);
+		const code = chunks.get(key) ?? "";
+		html = html.replace(s.tag, `<script type="module" ${s.attrs.replace(/\btype=["']module["']/i, "").trim()} data-standalone="${s.url.pathname}">${code.replaceAll("<\/script", "<\\/script")}<\/script>`);
+		chunks.delete(key);
+	}
+	const entries = [];
+	html = html.replace(ENTRY_ATTR_RE, (_, open, href, close) => {
+		const u = new URL(href, base);
+		entries.push(u);
+		return `${open}${key_of(u)}${close}`;
+	});
+	for (const u of entries) await add_chunk(u);
+	const imports = {};
+	for (const [key, code] of chunks) {
+		if (!code) continue;
+		imports[key] = "data:text/javascript;base64," + Buffer.from(code, "utf8").toString("base64");
+	}
+	const map = `<script type="importmap">${JSON.stringify({ imports }).replaceAll("<\/script", "<\\/script")}<\/script>`;
+	const note = `<!-- ogygia profiler · standalone report · ${Object.keys(imports).length} chunks inlined${missing.length ? ` · missing: ${missing.join(", ")}` : ""} -->`;
+	const at = html.search(/<script\b/i);
+	html = at === -1 ? html.replace(/<\/head>/i, `${map}</head>`) : html.slice(0, at) + map + html.slice(at);
+	return html.replace(/<\/head>/i, `<meta name="ogygia-standalone" content="1">${note}</head>`);
+}
+export { build_standalone };

package/dist/profiler/steps.d.ts

@@ -0,0 +1,39 @@
+import { Timeline } from "./timeline.js";
+import { StackIndex } from "./analyze.js";
+export interface RenderStep {
+  i: number;
+  t0: number;
+  t1: number;
+  ms: number;
+  kind: "cpu" | "wait";
+  /** cpu: the component / function that ran; wait: what the server waited for */
+  label: string;
+  category: string;
+  file?: string;
+  /** cpu: the leaf that burned inside it, when it differs */
+  detail?: string;
+  /** wait: every call in flight, with its own length */
+  calls?: {
+    label: string;
+    ms: number;
+  }[];
+  /** wait: the innermost span the wait sat inside */
+  within?: string;
+  /** the render so far, at the step's end */
+  at_ms: number;
+  cpu_so_far_ms: number;
+  /** the stack at the step's middle, outermost first (from the index; absent when it has none) */
+  stack?: string[];
+  /** small consecutive steps folded into this one: how many */
+  folded?: number;
+}
+export interface RenderSteps {
+  steps: RenderStep[];
+  window_ms: number;
+  cpu_ms: number;
+  wait_ms: number;
+  /** the step the render spent the longest in */
+  longest: number;
+}
+/** `max` steps at most: the smallest consecutive steps fold into their neighbour, counted. */
+export declare function render_steps(t: Timeline, stacks?: StackIndex, max?: number): RenderSteps | undefined;

package/dist/profiler/steps.js

@@ -0,0 +1,74 @@
+import { stack_at } from "./stacks.js";
+// src/profiler/steps.ts
+const round2 = (n) => Math.round(n * 100) / 100;
+/** `max` steps at most: the smallest consecutive steps fold into their neighbour, counted. */
+function render_steps(t, stacks, max = 80) {
+	const segs = t.segments.filter((s) => s.kind === "cpu" || s.kind === "wait" || s.kind === "gap");
+	if (!segs.length) return void 0;
+	const merged = [];
+	for (const s of segs) {
+		const kind = s.kind === "gap" ? "wait" : s.kind;
+		const label = s.kind === "gap" ? s.pending?.length ? s.pending.slice(0, 3).join(", ") : "nothing on the CPU, nothing named in flight" : s.label;
+		const last = merged[merged.length - 1];
+		if (last && last.kind === kind && last.label === label && kind === "cpu" && Math.abs(last.t1 - s.t0) < .05) {
+			last.t1 = s.t1;
+			if (!last.detail && s.detail) last.detail = s.detail;
+			continue;
+		}
+		merged.push({
+			...s,
+			kind,
+			label,
+			folded: 0
+		});
+	}
+	while (merged.length > max) {
+		let min_i = 0;
+		for (let i = 1; i < merged.length; i++) if (merged[i].t1 - merged[i].t0 < merged[min_i].t1 - merged[min_i].t0) min_i = i;
+		const victim = merged[min_i];
+		const into = min_i > 0 ? merged[min_i - 1] : merged[min_i + 1];
+		if (!into) break;
+		if (min_i > 0) into.t1 = victim.t1;
+		else into.t0 = victim.t0;
+		into.folded += 1 + victim.folded;
+		merged.splice(min_i, 1);
+	}
+	let cpu = 0;
+	let wait = 0;
+	let longest = 0;
+	return {
+		steps: merged.map((s, i) => {
+			const ms = s.t1 - s.t0;
+			if (s.kind === "cpu") cpu += ms;
+			else wait += ms;
+			if (ms > merged[longest].t1 - merged[longest].t0) longest = i;
+			const mid = (s.t0 + s.t1) / 2;
+			const at = s.kind === "cpu" && stacks ? stack_at(stacks, mid) : null;
+			return {
+				i,
+				t0: round2(s.t0),
+				t1: round2(s.t1),
+				ms: round2(ms),
+				kind: s.kind,
+				label: s.label,
+				category: s.category,
+				...s.file ? { file: s.file } : {},
+				...s.detail ? { detail: s.detail } : {},
+				...s.calls?.length ? { calls: s.calls.map((c) => ({
+					label: c.label,
+					ms: round2(c.ms)
+				})) } : {},
+				...s.within ? { within: s.within } : {},
+				at_ms: round2(s.t1),
+				cpu_so_far_ms: round2(cpu),
+				...at && at.frames.length ? { stack: at.frames.map((f) => f.name) } : {},
+				...s.folded ? { folded: s.folded } : {}
+			};
+		}),
+		window_ms: t.window_ms,
+		cpu_ms: round2(cpu),
+		wait_ms: round2(wait),
+		longest
+	};
+}
+export { render_steps };

package/dist/profiler/storage/index.d.ts

@@ -0,0 +1,87 @@
+/**
+ * PROFILER STORAGE — where finished reports live. By default the profiler keeps them in the
+ * instance's memory (and the browser keeps its own copies), which is all a single long-lived
+ * server needs. But on an ephemeral host (Amplify, Vercel, Netlify) the instance that recorded a
+ * report is often gone before the report page is opened, and a team wants every teammate's
+ * recordings in one place. A `ProfilerStore` is the seam for that: point the profiler at one and
+ * every report is written there and read back from there, across instances and across a restart.
+ *
+ * The contract is deliberately tiny — put, get, list, delete a report, and (optionally) put and list
+ * visit rows, which carry a server window's requests across instances — so a backend is a few
+ * dozen lines. Adapters ship for
+ * SQLite (a file, or `:memory:`), Redis and Postgres; a custom one is any object of this shape.
+ *
+ *   // src/hooks.server.ts
+ *   import { setProfilerStore } from '@ogygia/devtools/profiler/storage';
+ *   import { sqliteStore } from '@ogygia/devtools/profiler/storage/sqlite';
+ *   setProfilerStore(sqliteStore('.ogygia/profiles.db'));
+ *
+ * A report is stored as its portable dump (the same JSON the `.ogp` export and the agent view are
+ * built from): `meta` + `analysis` + `extras`, plus a few summary columns for the list. Nothing
+ * here is encrypted — a store is trusted infrastructure the profiler owner runs; share links stay
+ * the encrypted path for anything that leaves it.
+ */
+/** One report as a store holds it: summary columns for the list, and the portable dump as JSON. */
+export interface ProfilerRecord {
+  id: string;
+  /** epoch ms the report was created */
+  created: number;
+  /** the profiled page (page mode), else null */
+  page: string | null;
+  /** `window` | `page` | `request` | `trap` */
+  trigger: string;
+  /** a human label for the list (the page, or the request path) */
+  label: string;
+  /** the median render in ms (page mode), else null — shown in the list */
+  median: number | null;
+  /** the portable dump as a JSON string: `{ kind, version, meta, analysis, extras }` */
+  dump: string;
+}
+/** What the list needs — every column of a record except the (large) dump. */
+export type ProfilerSummary = Omit<ProfilerRecord, "dump">;
+/** One visit row, as a store holds it: today, one request of a server window, written by whichever
+ *  instance served it and listed together under the window's `page` key. Optional to support. */
+export interface ProfilerVisitRecord {
+  /** unique per row (it starts with `page`) */
+  key: string;
+  page: string;
+  /** epoch ms */
+  at: number;
+  /** the visit payload as a JSON string */
+  visit: string;
+}
+/**
+ * The storage contract. Report methods are required; visit methods are optional (with a store that
+ * omits them, a server window sees only its own instance's requests). All async so a network
+ * backend fits; a memory or SQLite
+ * store just resolves immediately.
+ */
+export interface ProfilerStore {
+  /** Called once before first use — create tables, connect, etc. Optional. */
+  init?(): Promise<void> | void;
+  /** Write (or overwrite) a report. */
+  putReport(rec: ProfilerRecord): Promise<void> | void;
+  /** Read a report's full dump JSON, or null when absent. */
+  getReport(id: string): Promise<string | null> | string | null;
+  /** The most recent reports (summaries), newest first. */
+  listReports(limit?: number): Promise<ProfilerSummary[]> | ProfilerSummary[];
+  /** Remove a report. */
+  deleteReport(id: string): Promise<void> | void;
+  /** Keep at most `keep` reports, dropping the oldest — the store's own LRU, called after a put. */
+  prune?(keep: number): Promise<void> | void;
+  putVisit?(rec: ProfilerVisitRecord): Promise<void> | void;
+  listVisits?(page: string, limit?: number): Promise<ProfilerVisitRecord[]> | ProfilerVisitRecord[];
+  /** Release connections. Optional. */
+  close?(): Promise<void> | void;
+  /** A name for the dashboard ("sqlite", "redis", "postgres", "memory"). */
+  readonly kind: string;
+}
+/** An in-memory store — a Map with an LRU cap. The profiler without a store keeps reports in its own
+ *  memory already, so this adds nothing there; it is for tests and a model for a custom store.
+ *  Nothing survives a restart. */
+export declare function memoryStore(cap?: number): ProfilerStore;
+/** Pull the summary columns off a record for storing them alongside the dump. */
+export declare function recordColumns(rec: ProfilerRecord): ProfilerSummary;
+export declare function setProfilerStore(store: ProfilerStore): void;
+/** The store set by {@link setProfilerStore}, if any — read by the profiler host on mount. */
+export declare function getProfilerStore(): ProfilerStore | undefined;