@ogygia/devtools 0.0.0-stage → 0.11.0

package/dist/profiler/ui/sort.svelte.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Reactive column sort shared by the profiler's tables (was report.ts's TABLE_SORT_JS DOM hack).
+ * Give it a getter for the rows and the initial numeric key; it owns the sort state and returns the
+ * sorted view + a click handler. Svelte runes in a `.svelte.ts` module — imported by the table
+ * islands, one instance each.
+ */
+export interface Sortable<T> {
+  readonly key: string;
+  readonly sorted: T[];
+  click(k: string): void;
+  arrow(k: string): string;
+  aria(k: string): "ascending" | "descending" | "none";
+}
+export declare function sortable<T>(rows: () => T[], initial_key: string): Sortable<T>;

package/dist/profiler/ui/sort.svelte.js

@@ -0,0 +1,37 @@
+// src/profiler/ui/sort.svelte.ts
+function sortable(rows, initial_key) {
+	let key = $state(initial_key);
+	let dir = $state("desc");
+	const sorted = $derived([...rows()].sort((a, b) => {
+		const x = Number(a[key]) || 0;
+		const y = Number(b[key]) || 0;
+		return dir === "asc" ? x - y : y - x;
+	}));
+	function click(k) {
+		if (key === k) dir = dir === "asc" ? "desc" : "asc";
+		else {
+			key = k;
+			dir = "desc";
+		}
+	}
+	/** The little arrow for a header: ▲/▼ when it's the active column, else empty. */
+	function arrow(k) {
+		return key === k ? dir === "asc" ? " ▲" : " ▼" : "";
+	}
+	/** The header's `aria-sort`: what a screen reader says the arrow means. */
+	function aria(k) {
+		return key === k ? dir === "asc" ? "ascending" : "descending" : "none";
+	}
+	return {
+		get key() {
+			return key;
+		},
+		get sorted() {
+			return sorted;
+		},
+		click,
+		arrow,
+		aria
+	};
+}
+export { sortable };

package/dist/profiler/ui/store.d.ts

@@ -0,0 +1,45 @@
+export interface StoredDump {
+  id: string;
+  page: string | null;
+  at: number;
+  label: string;
+  trigger: string;
+  /** the report's median render, ms (page mode) */
+  median: number | null;
+  /** the raw dump (`{ kind: 'ogygia-profiler-dump', meta, analysis, extras }`) */
+  dump: unknown;
+}
+export interface StoredVisit {
+  key: string;
+  page: string;
+  at: number;
+  visit: unknown;
+  snapshots: {
+    fp: string;
+    ssr: string;
+    hydrated: string;
+    final?: string;
+    from?: number;
+  }[];
+}
+/** Keep a report's dump. The newest MAX_REPORTS stay. */
+export declare function put_report(dump: {
+  meta: {
+    id: string;
+    page?: string;
+    created: number;
+    trigger: string;
+    runs?: number[];
+    request?: {
+      path: string;
+    };
+  };
+}): Promise<boolean>;
+export declare function get_report(id: string): Promise<StoredDump | null>;
+/** Every kept report, newest first, without the dumps (the list is cheap to draw). */
+export declare function list_reports(): Promise<Omit<StoredDump, "dump">[]>;
+export declare function delete_report(id: string): Promise<void>;
+/** The visits of a page this browser made, newest first. */
+export declare function list_visits(page: string, limit?: number): Promise<StoredVisit[]>;
+export declare function latest_visit(page: string): Promise<StoredVisit | null>;
+export declare function clear_all(): Promise<void>;

package/dist/profiler/ui/store.js

@@ -0,0 +1,92 @@
+// src/profiler/ui/store.ts
+/**
+* THE BROWSER STORE — the profiler's memory on an ephemeral host. Reports (their dumps) and the
+* beacon's visits live in this browser's IndexedDB, on the app's origin: a report page that the
+* server no longer has renders from here; the compare page and the history line work across
+* instances; the one-clock timeline joins a report to the visit this same browser made. The
+* runtime's beacon writes visits into the same database (runtime/beacon.ts — one schema, two
+* writers). Everything is best-effort: no IndexedDB, a private window, a full quota → empty.
+*/
+const DB_NAME = "ogygia-profiler";
+const DB_VERSION = 1;
+const MAX_REPORTS = 40;
+function open_db() {
+	return new Promise((resolve) => {
+		try {
+			if (typeof indexedDB === "undefined") return resolve(null);
+			const req = indexedDB.open(DB_NAME, DB_VERSION);
+			req.onupgradeneeded = () => {
+				const db = req.result;
+				if (!db.objectStoreNames.contains("reports")) db.createObjectStore("reports", { keyPath: "id" });
+				if (!db.objectStoreNames.contains("visits")) db.createObjectStore("visits", { keyPath: "key" });
+			};
+			req.onsuccess = () => resolve(req.result);
+			req.onerror = () => resolve(null);
+			req.onblocked = () => resolve(null);
+		} catch {
+			resolve(null);
+		}
+	});
+}
+function done(req) {
+	return new Promise((resolve) => {
+		req.onsuccess = () => resolve(req.result);
+		req.onerror = () => resolve(null);
+	});
+}
+async function with_store(name, mode, fn) {
+	const db = await open_db();
+	if (!db) return null;
+	try {
+		const out = await fn(db.transaction(name, mode).objectStore(name));
+		db.close();
+		return out;
+	} catch {
+		return null;
+	}
+}
+/** Keep a report's dump. The newest MAX_REPORTS stay. */
+async function put_report(dump) {
+	const m = dump.meta;
+	const median = m.runs?.length ? [...m.runs].sort((a, b) => a - b)[Math.floor(m.runs.length / 2)] : null;
+	const rec = {
+		id: m.id,
+		page: m.page ?? m.request?.path ?? null,
+		at: m.created,
+		label: m.page ?? m.request?.path ?? m.trigger,
+		trigger: m.trigger,
+		median,
+		dump
+	};
+	return await with_store("reports", "readwrite", async (s) => {
+		s.put(rec);
+		const keys = await done(s.getAll()) ?? [];
+		for (const old of keys.sort((a, b) => b.at - a.at).slice(MAX_REPORTS)) s.delete(old.id);
+		return true;
+	}) === true;
+}
+async function get_report(id) {
+	return await with_store("reports", "readonly", (s) => done(s.get(id))) ?? null;
+}
+/** Every kept report, newest first, without the dumps (the list is cheap to draw). */
+async function list_reports() {
+	return (await with_store("reports", "readonly", (s) => done(s.getAll())) ?? []).sort((a, b) => b.at - a.at).map(({ dump: _d, ...rest }) => rest);
+}
+async function delete_report(id) {
+	await with_store("reports", "readwrite", async (s) => {
+		s.delete(id);
+		return true;
+	});
+}
+/** The visits of a page this browser made, newest first. */
+async function list_visits(page, limit = 10) {
+	return (await with_store("visits", "readonly", (s) => done(s.getAll())) ?? []).filter((v) => v.page === page).sort((a, b) => b.at - a.at).slice(0, limit);
+}
+async function latest_visit(page) {
+	return (await list_visits(page, 1))[0] ?? null;
+}
+async function clear_all() {
+	await with_store("reports", "readwrite", async (s) => (s.clear(), true));
+	await with_store("visits", "readwrite", async (s) => (s.clear(), true));
+}
+export { clear_all, delete_report, get_report, latest_visit, list_reports, list_visits, put_report };

package/dist/profiler/visit.d.ts

@@ -0,0 +1,389 @@
+import { NavPhases, PageInteraction, PageNav } from "@ogygia/core/insights";
+import { RegionRefusal } from "@ogygia/core/internal/instruments";
+export interface VisitNav {
+  /** ms from navigation start */
+  req_start: number;
+  res_start: number;
+  res_end: number;
+  /** the browser gave the request and the first byte as 0 (Safari, a cross-origin-isolated page):
+   *  `req_start` and `res_start` are then the HTML's end, standing in — no first byte to read */
+  start_hidden?: true;
+  dom_interactive?: number;
+  dcl?: number;
+  load?: number;
+  /** the document's bytes on the wire and decoded */
+  transfer?: number;
+  size?: number;
+  /** the document came down as large as it is: sent without gzip or brotli */
+  raw?: true;
+  protocol?: string;
+  /** the steps before the first byte (ms, each only when it took time) */
+  phases?: NavPhases;
+  /** the document's own Server-Timing entries */
+  server_timing?: {
+    name: string;
+    ms: number;
+    desc?: string;
+  }[];
+}
+export interface VisitResource {
+  url: string;
+  /** css | script | font | img | fetch | other */
+  type: string;
+  start: number;
+  end: number;
+  req_start?: number;
+  res_start?: number;
+  transfer?: number;
+  size?: number;
+  blocking?: boolean;
+  /** the size is not the browser's: it hid another origin's, and the report weighed the file (never
+   *  sent by a beacon — the report sets it) */
+  weighed?: true;
+}
+export interface VisitIsland {
+  fp: string;
+  entry?: string;
+  /** wake began */
+  t0: number;
+  /** modules in hand */
+  loaded: number;
+  /** its scheduler turn came (after the module; islands hydrate one per task) */
+  turn?: number;
+  /** `data-hydrated` set */
+  done: number;
+  /** its effects had run (a microtask after `hydrate()`): the end of its own work, when later */
+  fx?: number;
+  recovered?: boolean;
+  /** the island's markup changed between the server and the hydrated DOM */
+  changed?: boolean;
+  /** another script edited it before it woke; the runtime put the server markup back */
+  healed?: boolean;
+  ssr_bytes?: number;
+  /** a recovered island whose arrived markup had Svelte's block markers unpaired [openers, closers]:
+   *  rewritten on the way */
+  markers?: [number, number];
+}
+export interface VisitRegion {
+  fp: string;
+  entry?: string;
+  /** its `wake` attribute (none on a default, wake-at-load island) */
+  wake?: string;
+  /** a deferred hole */
+  defer?: boolean;
+  hydrated?: boolean;
+  /** it threw while it loaded or mounted: the error */
+  failed?: string;
+  /** a failed island's wake → its failure (page clock) */
+  failed_span?: [number, number];
+  /** when the failed island's hydrate step began (page clock): from here to the failure it held the thread */
+  failed_turn?: number;
+  /** document px */
+  top: number;
+  height: number;
+  /** it drew nothing on the visitor's screen: no box of its own nor a child's */
+  hidden?: true;
+  /** …and never draws: no text, only `hidden` marker elements (it is there for its effects) */
+  headless?: true;
+}
+export interface VisitShift {
+  t: number;
+  value: number;
+  /** the island whose node moved, when one did */
+  fp?: string;
+  /** the element that moved, told briefly */
+  tag?: string;
+  /** [x, y, w, h] before and after, in viewport px */
+  from?: [number, number, number, number];
+  to?: [number, number, number, number];
+}
+export interface Visit {
+  page: string;
+  /** epoch ms of navigation start */
+  at: number;
+  nav: VisitNav;
+  /** (`lcp_replaced`: its element was taken out while its island stayed — rendered again) */
+  paints: {
+    fcp?: number;
+    lcp?: number;
+    lcp_fp?: string;
+    lcp_url?: string;
+    lcp_tag?: string;
+    lcp_replaced?: true;
+    lcp_lazy?: true;
+    lcp_priority?: "high" | "low";
+    held?: {
+      outcome: "arrived" | "input" | "cap" | "none";
+      resources: number;
+      waited_ms: number;
+    };
+  };
+  resources: VisitResource[];
+  /** every file by type, when `resources` lists only some (the first 200, the blocking ones first) */
+  resource_totals?: {
+    type: string;
+    count: number;
+    transfer: number;
+    size: number;
+  }[];
+  /** how many files the page loaded in all */
+  resources_all?: number;
+  longtasks: {
+    t: number;
+    ms: number;
+  }[];
+  /** `frames`: the browser has no long-task timing — the long tasks are frames drawn 50 ms+ late */
+  longtasks_from?: "frames";
+  /** `boxes`: the browser has no layout-shift timing — the shifts are islands' boxes changing as they woke */
+  shifts_from?: "boxes";
+  islands: VisitIsland[];
+  /** the first interaction inside an island: fingerprint, when, what kind */
+  firsts: {
+    fp: string;
+    t: number;
+    type: string;
+  }[];
+  shifts: VisitShift[];
+  marks?: {
+    name: string;
+    t0?: number;
+    ms: number;
+  }[];
+  /** every region on the page as the visit ended (where it sits, how it wakes, whether it woke) */
+  regions?: VisitRegion[];
+  /** the vitals as of this message */
+  vitals?: {
+    ttfb?: number;
+    fcp?: number;
+    lcp?: number;
+    cls?: number;
+    inp?: number;
+  };
+  /** main-thread ms per script URL (long animation frames, from the page's start) */
+  scripts?: {
+    url: string;
+    ms: number;
+    count: number;
+  }[];
+  /** the page's origin as the browser had it */
+  origin?: string;
+  /** entry types the visiting browser cannot observe (Safari: `layout-shift`, `longtask`): what
+   *  they would measure is unknown, not zero */
+  unsupported?: string[];
+  /** Svelte's hydration warnings (dev) */
+  warnings?: {
+    code: string;
+    message: string;
+    file?: string;
+    fp?: string;
+  }[];
+  /** holes whose answer never came, by island id (the report's hole rows name them) */
+  holes_failed?: {
+    id: string;
+    reason: RegionRefusal | "error";
+    final_path?: string;
+    message?: string;
+    attempts: number;
+  }[];
+  /** files a preload fetched and something else downloaded again: the preload went unused */
+  /** (`vary`: a font's Vary header, from the report's own weighing — never sent by a beacon) */
+  /** `hole`: the URL is a hole the runtime asked for (its preload is ogygia's own) */
+  preload_misses?: {
+    url: string;
+    type: string;
+    bytes: number;
+    as: string;
+    crossorigin: string | null;
+    vary?: string;
+    hole?: true;
+  }[];
+  /** the `@font-face` rules behind the fonts it fetched: family, font-display, the fetched files */
+  font_faces?: {
+    family: string;
+    display: string;
+    urls: string[];
+  }[];
+  /** images whose pixels are 4× or more what their box shows (the screen counted), files ≥ 50 KB */
+  images_oversized?: {
+    url: string;
+    natural: [number, number];
+    shown: [number, number];
+    dpr: number;
+    bytes: number;
+    fp?: string;
+  }[];
+  /** preloads (image, font, stylesheet) nothing on the page used 3 s after load */
+  preloads_unused?: {
+    url: string;
+    as: string;
+    bytes: number;
+  }[];
+  /** text files of 4 KB or more sent without gzip or brotli, the largest first */
+  uncompressed?: {
+    url: string;
+    type: string;
+    bytes: number;
+  }[];
+  /** images more than a screen and a half down, not lazy, 20 KB or more, fetched before load ended */
+  images_eager_below?: {
+    url: string;
+    top: number;
+    bytes: number;
+    fp?: string;
+  }[];
+  /** shown images the browser could hold no room for (computed aspect-ratio `auto`); empty: none */
+  images_unsized?: string[];
+  /** long frames (50 ms or more) that began while the page scrolled, with their two biggest scripts */
+  scroll_jank?: {
+    start: number;
+    ms: number;
+    scripts: {
+      url: string;
+      fn: string;
+      invoker: string;
+      ms: number;
+    }[];
+  }[];
+  /** scripts that forced style and layout (5 ms or more): their window, the forced ms, file, function */
+  forced_layout?: {
+    start: number;
+    end: number;
+    ms: number;
+    url: string;
+    fn: string;
+  }[];
+  /** the page's size in elements, when 1,500 or more (depth 0: past 60,000, only counted) */
+  dom?: {
+    nodes: number;
+    depth: number;
+    deepest: string;
+    widest: {
+      at: string;
+      children: number;
+    };
+    islands: {
+      fp: string;
+      nodes: number;
+    }[];
+  };
+  /** islands whose own file failed to load and fell back to their stable name */
+  entry_fallbacks?: {
+    entry: string;
+    src: string;
+    recovered: boolean;
+  }[];
+  /** content-named files (`/immutable/`) the browser fetched again: revalidated (a 304), or
+   *  downloaded in full on a reload. `entry`: the island whose file it is; `runtime`: the runtime's */
+  refetched?: {
+    url: string;
+    how: "revalidated" | "downloaded";
+    bytes: number;
+    ms: number;
+    entry?: string;
+    hole?: string;
+    runtime?: boolean;
+  }[];
+  /** the slowest interaction (INP's), by phase, with the scripts of the long frames around it */
+  interaction?: PageInteraction;
+  /** the in-app navigations (router body swaps): start, page fetched, styles in, swap committed */
+  navs?: PageNav[];
+  /** holes whose first answer came: fetch start and swap (page time), and whether below the fold */
+  holes_answered?: {
+    id: string;
+    n: number;
+    start: number;
+    t: number;
+    below_fold: boolean;
+    left?: number;
+    first?: number;
+    end?: number;
+    queue?: number;
+    render?: number;
+    batch?: number;
+    p?: string;
+  }[];
+  /** batch requests that carried fewer holes than they were sent for (each then fetched alone) */
+  hole_batches?: {
+    sent: number;
+    delivered: number;
+    status: number;
+    refused?: "redirected" | "document";
+    final_url?: string;
+    ids: string[];
+  }[];
+  /** a server transform's restore gone wrong: a host upgraded first (`late`), or not Svelte's (`mismatch`) */
+  restores?: {
+    kind: "late" | "mismatch";
+    host: string;
+    t: number;
+    diff?: string;
+    island?: string;
+  }[];
+  viewport?: [number, number];
+  /** the devtools dock was open as the document loaded, from this page-clock time */
+  dock_open_at?: number;
+  ua?: string;
+}
+/** A beacon body's `visit` → a bounded Visit, or null when it is not one. */
+export declare function parse_visit(page: unknown, raw: unknown): Visit | null;
+/** Two records of the SAME visit (same page, same navigation start) folded into one. The runtime's
+ *  beacon and the app's `mark()` client can be two module instances on one page, each posting its
+ *  own half (islands here, marks there); a visit is also posted early and again on hide. Arrays
+ *  union by identity, the later record's navigation and paints win where it has them. */
+export declare function merge_visits(a: Visit, b: Visit): Visit;
+export interface ClockBar {
+  id: string;
+  lane: string;
+  label: string;
+  t0: number;
+  t1: number;
+  /** what colours it: server-<phase> | ttfb | download | css | script | font | img | fetch | other | task | island-load | island-hydrate | first */
+  kind: string;
+  critical?: boolean;
+  detail?: string;
+  fp?: string;
+  blocking?: boolean;
+}
+export interface ClockLane {
+  name: string;
+  /** server | document | network | main | islands | holes */
+  group: string;
+  bars: ClockBar[];
+}
+export interface OneClock {
+  /** the clock's end, ms after navigation start */
+  end: number;
+  lanes: ClockLane[];
+  marks: {
+    label: string;
+    t: number;
+    kind: string;
+  }[];
+  /** the bars on the critical path to first paint and to LCP, in order */
+  critical: {
+    id: string;
+    label: string;
+    t0: number;
+    t1: number;
+    why: string;
+  }[];
+  /** the server's render window, placed so it ends at the first byte (null: no server timeline) */
+  server_at: {
+    t0: number;
+    t1: number;
+    clipped: boolean;
+  } | null;
+  notes: string[];
+}
+/** Lay a visit out on one clock next to the server's render of the same page. `phases` is the
+ *  server timeline's phase split (each phase's CPU + wait, in order); `names` maps an island's
+ *  fingerprint to its component name. */
+export declare function one_clock(visit: Visit, server: {
+  window_ms: number;
+  phases: {
+    phase: string;
+    label?: string;
+    cpu_ms: number;
+    wait_ms: number;
+  }[];
+} | null, names?: Record<string, string>, hole_names?: Record<string, string>): OneClock;