@ogygia/devtools 0.0.0 → 0.11.1

package/dist/profiler/client-windows.d.ts

@@ -0,0 +1,49 @@
+import { Analysis, CpuProfile, FrameCategory } from "./analyze.js";
+import { Visit } from "./visit.js";
+export interface WindowFn {
+  name: string;
+  file: string;
+  line: number | null;
+  category: FrameCategory;
+  self_ms: number;
+  total_ms: number;
+}
+export interface ClientWindows {
+  /** per island fingerprint: CPU inside its hydrate window, and the functions that took it */
+  islands: Record<string, {
+    ms: number;
+    top: WindowFn[];
+  }>;
+  /** the long tasks that overlapped no island's hydrate window */
+  outside: {
+    ms: number;
+    top: WindowFn[];
+  };
+}
+/** The profile with every sample outside `spans` (ms, the page clock) turned idle. */
+export declare function window_profile(p: CpuProfile, spans: readonly (readonly [number, number])[]): CpuProfile;
+/** THE SLOWEST INTERACTION'S TWO SPANS, analyzed: what ran while its input waited, and what its
+ *  handlers ran (the island's own code, by its source-mapped name — the long frames only name the
+ *  event dispatcher it came through). A span too short for the sampler says nothing. */
+export interface InteractionCpu {
+  /** the interaction's start (the page clock): which interaction of the visit this is */
+  t: number;
+  /** the frames went through a source map (their lines are the source's) */
+  mapped: boolean;
+  wait: {
+    ms: number;
+    top: WindowFn[];
+  } | null;
+  handler: {
+    ms: number;
+    top: WindowFn[];
+  } | null;
+}
+export declare function interaction_windows(profile: CpuProfile, spans: {
+  t: number;
+  wait: readonly [number, number];
+  handler: readonly [number, number];
+}, run: (p: CpuProfile) => Analysis): InteractionCpu;
+/** Each island's hydrate window and the long tasks outside them, analyzed. `run` is the report's
+ *  own analysis (its resolver, renamer and chunk categories). */
+export declare function client_windows(profile: CpuProfile, visit: Visit, run: (p: CpuProfile) => Analysis): ClientWindows;

package/dist/profiler/client-windows.js

@@ -0,0 +1,95 @@
+// src/profiler/client-windows.ts
+/** a slice this short says nothing a sampler (~10 ms) can back up */
+const MIN_WINDOW_MS = 20;
+const MAX_WINDOWS = 16;
+const NOT_CODE = /* @__PURE__ */ new Set([
+	"idle",
+	"gc",
+	"v8",
+	"profiler"
+]);
+/** The profile with every sample outside `spans` (ms, the page clock) turned idle. */
+function window_profile(p, spans) {
+	const samples = p.samples ?? [];
+	const deltas = p.timeDeltas ?? [];
+	let t_us = p.startTime;
+	const out = samples.map((sample, i) => {
+		t_us += deltas[i] ?? 0;
+		const t = t_us / 1e3;
+		let inside = false;
+		for (const [a, b] of spans) if (t >= a && t <= b) {
+			inside = true;
+			break;
+		}
+		return inside ? sample : 2;
+	});
+	return {
+		...p,
+		samples: out
+	};
+}
+function top_of(a) {
+	return a.functions.filter((f) => !NOT_CODE.has(f.category) && f.self_ms >= 1).sort((x, y) => y.self_ms - x.self_ms).slice(0, 3).map((f) => ({
+		name: f.label && f.name.startsWith("(anonymous") ? f.label : f.name,
+		file: f.url,
+		line: f.line || null,
+		category: f.category,
+		self_ms: f.self_ms,
+		total_ms: f.total_ms
+	}));
+}
+function interaction_windows(profile, spans, run) {
+	let mapped = false;
+	const one = (s) => {
+		if (s[1] - s[0] < MIN_WINDOW_MS) return null;
+		const a = run(window_profile(profile, [s]));
+		mapped ||= a.sourcemapped;
+		return {
+			ms: Math.round(a.busy_ms * 10) / 10,
+			top: top_of(a)
+		};
+	};
+	const wait = one(spans.wait);
+	const handler = one(spans.handler);
+	return {
+		t: spans.t,
+		mapped,
+		wait,
+		handler
+	};
+}
+/** Each island's hydrate window and the long tasks outside them, analyzed. `run` is the report's
+*  own analysis (its resolver, renamer and chunk categories). */
+function client_windows(profile, visit, run) {
+	const end = (i) => Math.max(i.done, i.fx ?? 0);
+	const windows = visit.islands.map((i) => ({
+		fp: i.fp,
+		from: i.turn ?? i.loaded,
+		to: end(i)
+	})).filter((w) => w.to - w.from >= MIN_WINDOW_MS).sort((x, y) => y.to - y.from - (x.to - x.from)).slice(0, MAX_WINDOWS);
+	const islands = {};
+	for (const w of windows) {
+		const a = run(window_profile(profile, [[w.from, w.to]]));
+		islands[w.fp] = {
+			ms: Math.round(a.busy_ms * 10) / 10,
+			top: top_of(a)
+		};
+	}
+	const outside = visit.longtasks.filter((t) => !visit.islands.some((i) => t.t < end(i) && t.t + t.ms > (i.turn ?? i.loaded))).map((t) => [t.t, t.t + t.ms]);
+	let out = {
+		ms: 0,
+		top: []
+	};
+	if (outside.length) {
+		const a = run(window_profile(profile, outside));
+		out = {
+			ms: Math.round(a.busy_ms * 10) / 10,
+			top: top_of(a)
+		};
+	}
+	return {
+		islands,
+		outside: out
+	};
+}
+export { client_windows, interaction_windows, window_profile };

package/dist/profiler/client.d.ts

@@ -0,0 +1,40 @@
+/**
+ * `mark` — the browser twin of `span`: name a stretch of the visitor's time the server profile
+ * cannot see (a design system's CDN components hydrating, a widget booting, a font arriving) and
+ * the report shows it next to the islands' own hydration times, for the page.
+ *
+ *   • `mark(name, fn)` times a function or the promise it returns; `mark(name, promise)` times a
+ *     promise you already hold. A throw or rejection is recorded (`error: true`) and rethrown.
+ *   • `mark.event(name, type, target?)` times until an event fires — a web-components runtime's
+ *     "all hydrated" event, a widget's `ready` — from the call (or from navigation start with
+ *     `{ from: 'navigation' }`).
+ *   • `mark.start(name)` opens one by hand; `end(attrs?)` closes it. `{ from: 'navigation' }` on
+ *     either measures from the page's start instead of the call.
+ *
+ * Cost: nothing without the profiler's beacon tag in the document (the profiler puts it there
+ * for its own logged-in user only) — one `querySelector` on the first call, then a boolean. With
+ * it, one entry in a batch sent when the page is idle or hides. Never a request per mark.
+ *
+ * ```ts
+ * import { mark } from '@ogygia/devtools/profiler/client';
+ * mark.event('ds.hydrate', 'components-ready');         // the design system's runtime: every component hydrated
+ * await mark('widget.boot', () => widget.init(), { version: '3' });
+ * ```
+ */
+export type MarkAttrs = Record<string, string | number | boolean>;
+export interface MarkHandle {
+  /** close it; ending twice is a no-op */
+  end(attrs?: MarkAttrs): void;
+}
+declare function mark_event(name: string, type: string, target?: EventTarget | null, opts?: {
+  from?: "call" | "navigation";
+  attrs?: MarkAttrs;
+}): Promise<void>;
+declare function mark_start(name: string, attrs?: MarkAttrs, opts?: {
+  from?: "call" | "navigation";
+}): MarkHandle;
+export declare const mark: (<T>(name: string, work: (() => T) | PromiseLike<T>, attrs?: MarkAttrs) => T) & {
+  event: typeof mark_event;
+  start: typeof mark_start;
+};
+export {};

package/dist/profiler/client.js

@@ -0,0 +1,82 @@
+// src/profiler/client.ts
+const BEACON_KEY = Symbol.for("ogygia.beacon");
+const page_beacon = () => globalThis[BEACON_KEY];
+const waiting = [];
+let retrying = false;
+function beacon_mark(...args) {
+	if (typeof document === "undefined") return;
+	const b = page_beacon();
+	if (b) {
+		for (const w of waiting.splice(0)) b.beacon_mark(...w);
+		b.beacon_mark(...args);
+		return;
+	}
+	if (waiting.length < 400) waiting.push(args);
+	if (retrying) return;
+	retrying = true;
+	let tries = 0;
+	const retry = () => {
+		const later = page_beacon();
+		if (later) {
+			retrying = false;
+			for (const w of waiting.splice(0)) later.beacon_mark(...w);
+		} else if (++tries < 40) setTimeout(retry, 250);
+		else {
+			retrying = false;
+			waiting.length = 0;
+		}
+	};
+	setTimeout(retry, 250);
+}
+const now = () => typeof performance !== "undefined" && performance.now ? performance.now() : Date.now();
+const is_thenable = (v) => !!v && typeof v.then === "function";
+function mark_impl(name, work, attrs) {
+	const t0 = now();
+	const done = (error) => beacon_mark(name, now() - t0, error ? {
+		...attrs,
+		error: true
+	} : attrs, t0);
+	let out;
+	try {
+		out = typeof work === "function" ? work() : work;
+	} catch (e) {
+		done(true);
+		throw e;
+	}
+	if (is_thenable(out)) return out.then((v) => {
+		done();
+		return v;
+	}, (e) => {
+		done(true);
+		throw e;
+	});
+	done();
+	return out;
+}
+function mark_event(name, type, target = typeof document !== "undefined" ? document : null, opts = {}) {
+	if (!target) return Promise.resolve();
+	const t0 = opts.from === "navigation" ? 0 : now();
+	return new Promise((resolve) => {
+		target.addEventListener(type, () => {
+			beacon_mark(name, now() - t0, opts.attrs, t0);
+			resolve();
+		}, { once: true });
+	});
+}
+function mark_start(name, attrs, opts = {}) {
+	const t0 = opts.from === "navigation" ? 0 : now();
+	let ended = false;
+	return { end(extra) {
+		if (ended) return;
+		ended = true;
+		beacon_mark(name, now() - t0, extra ? {
+			...attrs,
+			...extra
+		} : attrs, t0);
+	} };
+}
+const mark = Object.assign(mark_impl, {
+	event: mark_event,
+	start: mark_start
+});
+export { mark };

package/dist/profiler/compare.d.ts

@@ -0,0 +1,308 @@
+import { Analysis } from "./analyze.js";
+import { ReportMeta } from "./report.js";
+import { GcAttribution } from "./gc.js";
+import { Pattern, PatternKind } from "./patterns.js";
+import { LedgerLine } from "./ledger.js";
+import { DrillNode } from "./drill.js";
+import { Forecast } from "./forecast.js";
+import { Phase } from "./timeline.js";
+import { VitalMove, VitalMove as VitalMove$1, vitals_moved } from "@ogygia/core/insights";
+export interface DeltaRow {
+  /** the identity both sides were matched on (unique in its list: what a view keys rows by —
+   *  two anonymous functions in one file share a name and a file) */
+  key: string;
+  name: string;
+  /** where it lives (b's, else a's) */
+  file: string;
+  line: number;
+  a_self: number;
+  b_self: number;
+  d_self: number;
+  a_total: number;
+  b_total: number;
+  d_total: number;
+  a_calls: number | null;
+  b_calls: number | null;
+  /** only in one side */
+  only?: "a" | "b";
+}
+export interface SummaryRow {
+  label: string;
+  a: number;
+  b: number;
+  d: number;
+  unit: "ms" | "n" | "%" | "KB" | "MB";
+}
+/** one allocation line before and after: what it allocated and the pause time it caused */
+export interface GcMakerDelta {
+  name: string;
+  caller: string | null;
+  component: string | null;
+  a_mb: number;
+  b_mb: number;
+  d_mb: number;
+  a_gc_ms: number;
+  b_gc_ms: number;
+  d_gc_ms: number;
+  only?: "a" | "b";
+}
+export interface Comparison {
+  a: {
+    id: string;
+    label: string;
+    created: number;
+  };
+  b: {
+    id: string;
+    label: string;
+    created: number;
+  };
+  summary: SummaryRow[];
+  phases: {
+    phase: Phase;
+    label: string;
+    a: number;
+    b: number;
+    d: number;
+  }[];
+  components: DeltaRow[];
+  functions: DeltaRow[];
+  findings: {
+    added: string[];
+    gone: string[];
+  };
+  /** the paths to fix, matched by their owner: what each path cost before and after */
+  paths: PathDelta[];
+  /** the garbage makers, matched by line: what each allocated and the GC it caused, before and after */
+  gc_makers: GcMakerDelta[];
+  /** the slow patterns, matched by kind (and library): which a change fixed, which it introduced */
+  patterns: PatternDelta[];
+  /** DID THE FIX PAY: what the patterns that went away or got better were expected to save, per
+   *  render, against how much faster the median render actually got (page mode, both sides) */
+  fix_check?: {
+    predicted_ms: number;
+    measured_ms: number;
+    verdict: "as-expected" | "less" | "more";
+    /** B ran after A on the heap A filled (`order`): its render reads slow, the measured saving low */
+    skewed?: true;
+  };
+  /** the costly app lines, matched by file + code (an edit above them moves the number, not the
+   *  code), per render on each side: what the change did to each */
+  lines: LineDelta[];
+  /** WHERE ONE RENDER'S TIME MOVED: the drill-down rows that changed, deepest cause only */
+  drill?: DrillDelta[];
+  /** THE RUN ORDER TRAP: both ran on one server, and the earlier one saw every render keep memory
+   *  alive — the later one ran on a fuller heap (more GC, slower allocation), so part of its
+   *  difference is the order, not the code */
+  order?: {
+    earlier: "a" | "b";
+    kept_mb: number;
+    requests_between: number;
+  };
+  /** the render took the same time on both sides (within the runs' own spread): CPU moves between
+   *  patterns and lines are V8 charging the time elsewhere (inlining differs run to run), so they
+   *  read `shifted`, not fixed or worse */
+  render_same?: {
+    a_ms: number;
+    b_ms: number;
+    noise_ms: number;
+  };
+}
+export interface LineDelta {
+  file: string;
+  /** the line number in b (a's when the line is gone) */
+  line: number;
+  code: string;
+  /** CPU per render (own + inside libraries), ms */
+  a_ms: number;
+  b_ms: number;
+  d_ms: number;
+  /** bytes made per render */
+  a_bytes: number;
+  b_bytes: number;
+  /** bytes kept alive per render */
+  a_kept: number;
+  b_kept: number;
+  status: "fixed" | "new" | "better" | "worse" | "same" | "shifted";
+}
+/** With the render unchanged, a CPU row's fixed / new / better / worse is where V8 charged the time. */
+export declare function mark_shifted(cmp: Comparison): Comparison;
+/** The two ledgers side by side. Keyed by file + the code on the line: code that changed reads as
+ *  one line gone and another new (the fix), code that did not keeps its row though its number moved. */
+export declare function line_deltas(a?: readonly LedgerLine[], b?: readonly LedgerLine[], ra?: number, rb?: number): LineDelta[];
+/** A report against the previous profile of its page, cut for the top of the report: the render's
+ *  change, the drill rows that really moved (inlining shifts left out), the order trap, the fix check */
+export interface Since {
+  prev: string;
+  a_ms?: number;
+  b_ms?: number;
+  /** the render took the same time within the runs' own spread */
+  same?: boolean;
+  moved: DrillDelta[];
+  order?: Comparison["order"];
+  fix_check?: Comparison["fix_check"];
+  /** the page score then and now, and the categories that moved it most */
+  score?: {
+    a: number;
+    b: number;
+    a_grade: string;
+    b_grade: string;
+    moved: {
+      key: string;
+      label: string;
+      a: number;
+      b: number;
+    }[];
+  };
+  /** what changed in the page's JS between the two builds (both weighed): the files behind a JS move */
+  assets?: import("@ogygia/core/insights").AssetsDiff;
+  /** the browser's findings fixed and new (both reports with a visit), as `code (islands)` */
+  browser?: {
+    fixed: string[];
+    added: string[];
+  };
+  /** which islands changed file between the two builds (what a returning visitor downloads again) */
+  islands?: IslandFilesDiff;
+  /** the browser's vitals that moved (each report's own visit), and for TTFB / FCP / LCP the part
+   *  of it that moved most — "LCP 1.2 s → 2.6 s: its download 300 → 1700 ms" */
+  vitals?: VitalMove$1[];
+}
+/**
+ * WHAT A DEPLOY COSTS A RETURNING VISITOR. Each island's file is named by its content, so between two
+ * profiles of one page an island either KEPT its file (a returning visitor's cache still serves it) or
+ * MOVED to a new one (downloaded again). Islands keyed by identity (`entry`), files by location
+ * (`module_url`); `bytes` weighs a moved island's new file when the second build weighed it.
+ * `all_moved`: every island moved — when their code did not all change, the build's names are not
+ * stable (SvelteKit bakes its version, the build time by default, into its client chunk: pin
+ * `kit.version.name`). Null when there is nothing to compare (a page without islands, or a build from
+ * before content hashing, where a file's name never moved).
+ */
+export interface IslandFilesDiff {
+  moved: {
+    name: string;
+    bytes: number | null;
+  }[];
+  kept: number;
+  /** the moved files' bytes, where weighed */
+  bytes: number;
+  all_moved: boolean;
+}
+export declare function island_files_diff(a: readonly {
+  entry: string;
+  name: string;
+  module_url: string;
+}[], b: readonly {
+  entry: string;
+  name: string;
+  module_url: string;
+}[], weight?: (url: string) => number | undefined): IslandFilesDiff | null;
+export interface DrillDelta {
+  /** the row's place in the render, top down: `load functions › +page.server.ts › GET api/x` */
+  path: string[];
+  kind: DrillNode["kind"];
+  at?: string;
+  a_ms: number;
+  b_ms: number;
+  d_ms: number;
+  /** that side had no row of its own, only an "N more" fold: its ms is the fold's, an upper bound */
+  upto?: "a" | "b";
+  /** a wait, a gap, or a line under one: clock time, never re-attributed by inlining */
+  waiting?: boolean;
+  /** `shifted`: the render took the same time on both sides, so a CPU row's move is V8 charging the
+   *  time to another function (inlining differs run to run), not a change */
+  status: "fixed" | "new" | "better" | "worse" | "shifted";
+}
+/** One server for both (its start, from each report's time and the server's age then, within the
+ *  length of a profile; and it had served more requests by the later one), and the earlier report
+ *  saw each render keep 8 MB+ alive: the later one inherited the fuller heap. */
+export declare function order_of(a: {
+  meta: ReportMeta;
+  patterns?: readonly Pattern[];
+}, b: {
+  meta: ReportMeta;
+  patterns?: readonly Pattern[];
+}): Comparison["order"];
+/**
+ * THE DRILL-DOWNS SIDE BY SIDE: every row of one render's tree matched by its place (phase › load
+ * file › who › line), and the rows that moved — only the DEEPEST of a chain: a row whose moved
+ * children carry most (70 %) of its move is left out, so the list names the cause (the call, the
+ * line), not every level above it. Both trees are one render, so no per-render division.
+ */
+export declare function drill_deltas(a: DrillNode | undefined, b: DrillNode | undefined): DrillDelta[];
+export interface PatternDelta {
+  /** the title as the newer report words it (the older one's when it is gone) */
+  title: string;
+  kind: PatternKind;
+  /** measured cost on each side (CPU + GC, or waiting for a wait pattern), ms per render */
+  a_ms: number;
+  b_ms: number;
+  d_ms: number;
+  /** what fixing it was expected to save, each side, ms per render */
+  a_save: number;
+  b_save: number;
+  a_sites: number;
+  b_sites: number;
+  /** fixed: gone in b · new: only in b · better / worse: cost moved by a fifth and 2 ms or more · same */
+  status: "fixed" | "new" | "better" | "worse" | "same" | "shifted";
+  wait?: boolean;
+}
+export declare function pattern_deltas(a?: readonly Pattern[], b?: readonly Pattern[], ra?: number, rb?: number): PatternDelta[];
+/**
+ * WHAT THE CHANGE PROMISED, COUNTED THE FORECAST'S WAY: the older report's forecast parts that got
+ * done — a part whose fix (or one it covers) went away counts whole, one that shrank by its share,
+ * work for unread data when the newer report no longer has it — added with the same overlap rules
+ * and caps as the forecast itself. The forecast was held to account against fixed pages; this is
+ * the same arithmetic for the fix you actually made.
+ */
+/**
+ * HOW MUCH OF EACH OLDER PATTERN IS STILL THERE, BY ITS OWN SITES: the share of its cost on sites
+ * whose code the newer report still flags with the same kind (matched by the code, not the line
+ * number an edit above moves). "Waits in a row" in both reports can be two different sets of calls —
+ * the chains fixed, a new one between the batches — and its title alone would say it only shrank.
+ */
+export declare function still_there(a: readonly Pattern[] | undefined, b: readonly Pattern[] | undefined): Map<string, number>;
+/** The patterns a change fixed or shrank, their expected saving summed, against the median render's
+ *  measured change. A saving well under the prediction usually moved somewhere (another line got
+ *  slower) or drowned in run-to-run noise; well over it, the fix removed more than the pattern saw. */
+export declare function fix_check_of(patterns: readonly PatternDelta[], a: ReportMeta, b: ReportMeta, fa?: Forecast, fb?: Forecast, left?: Map<string, number>): Comparison["fix_check"];
+export interface PathDelta {
+  owner: string;
+  file: string;
+  line: number;
+  a_ms: number;
+  b_ms: number;
+  d_ms: number;
+  a_fns: string[];
+  b_fns: string[];
+  only?: "a" | "b";
+}
+export declare function compare_reports(a: {
+  meta: ReportMeta;
+  analysis: Analysis;
+  findings: string[];
+  gc?: GcAttribution;
+  patterns?: Pattern[];
+  ledger?: LedgerLine[];
+  drill?: DrillNode;
+  forecast?: Forecast;
+}, b: {
+  meta: ReportMeta;
+  analysis: Analysis;
+  findings: string[];
+  gc?: GcAttribution;
+  patterns?: Pattern[];
+  ledger?: LedgerLine[];
+  drill?: DrillNode;
+  forecast?: Forecast;
+}): Comparison;
+/** Page-mode reports grouped by page, oldest first, with each run's median — the history line. */
+export declare function page_history(metas: ReportMeta[], score_of?: (id: string) => number | undefined): {
+  page: string;
+  points: {
+    id: string;
+    created: number;
+    median: number;
+    score?: number;
+  }[];
+}[];
+export { type VitalMove, vitals_moved };