@ogygia/devtools 0.0.0-stage → 0.11.0

package/dist/profiler/report.d.ts

@@ -0,0 +1,1404 @@
+import { Analysis, Callee, FrameCategory, FrameStat, HeapAllocator, PathNode } from "./analyze.js";
+import { DocDiff } from "./doc-diff.js";
+import { Forecast } from "./forecast.js";
+import { AwaitEdge, LoadChain, Phase, TimelineCall } from "./timeline.js";
+import { NetCall, ServerTiming, UpstreamTrace } from "./net.js";
+import { ClientWindows, InteractionCpu, WindowFn } from "./client-windows.js";
+import { Visit, VisitNav } from "./visit.js";
+import { StreamTail } from "./stream-tail.js";
+import { ByteStrip, StripKind, StripSegment } from "./byte-strip.js";
+import { MemoCandidate, Retained, SpanValueRow } from "./insights.js";
+import { RenderSteps } from "./steps.js";
+import { ContendingRequest, Contention } from "./contention.js";
+import { KeyVerdict, Lineage, LineageComponent } from "./lineage.js";
+import { HeapGrowth, Pattern, PatternKind, PatternSite } from "./patterns.js";
+import { River } from "./river.js";
+import { GcAttribution } from "./gc.js";
+import { PageScore } from "./score.js";
+import { AllocTimeline } from "./alloc.js";
+import { LedgerLine } from "./ledger.js";
+import { DrillNode } from "./drill.js";
+import { own_requests } from "./own-requests.js";
+import { IoOp } from "./async-io.js";
+import { SpanRecord } from "./span.js";
+import { IslandHazard, PageAssets, RuntimeScripts, browser_of, hazard_fix, hazard_words, inline_threshold_tune } from "@ogygia/core/insights";
+import { HoleRequestStats, HoleStat, IslandStat, OgygiaRequestStats } from "@ogygia/core/internal/server";
+/** One span name across a recording: how often, how long, what went wrong, who called it. */
+export interface SpanRow {
+  name: string;
+  count: number;
+  total_ms: number;
+  /** the wall time the spans of this name covered, overlaps counted once — `total_ms` far above
+   *  it means they ran together (a Promise.all), not one after another */
+  wall_ms: number;
+  /** SELF: the spans' time minus what their child spans covered — `ds.pass` 249 ms with
+   *  `ds.render.all` 178 and `ds.splice` 69 inside it is 2 ms of its own */
+  self_ms: number;
+  /** the median span's FAIR SHARE of the wall (`fair_shares`): what one costs when many overlap —
+   *  `p50_ms` is then its start-to-end, mostly waiting on the others */
+  share_p50_ms: number;
+  /** the most spans of this name open at one instant */
+  peak: number;
+  p50_ms: number;
+  max_ms: number;
+  errors: number;
+  open: number;
+  /** `cache` attribute tallies, when the spans carried one */
+  cache?: {
+    hit: number;
+    miss: number;
+    miss_ms: number;
+  };
+  /** distinct callers, most frequent first (at most 3) */
+  callers: string[];
+  /** other attribute keys seen (shown, not interpreted) */
+  attr_keys: string[];
+  /** THE BREAKDOWN by attribute value: for each string attribute with a handful of distinct
+   *  values (`tag`, `key`, `table`…), what each value cost — `ds.render` by tag, `db.query` by
+   *  table. `total_ms` is summed, `wall_ms` counts overlaps once. Values are capped; the rest
+   *  fold into `(N more)`. */
+  by: Record<string, {
+    value: string;
+    count: number;
+    total_ms: number;
+    wall_ms: number;
+    share_ms: number;
+    p50_ms: number;
+    max_ms: number;
+  }[]>;
+}
+/** FAIR SHARES of overlapping intervals: at every instant the wall is split evenly among the
+ *  intervals open then, so the shares add up to exactly the union's length. For 242 renders run
+ *  together, one's start-to-end (97 ms) is mostly waiting on the other 241; its share (0.8 ms) is
+ *  its part of the 185 ms they cost. Also the peak number open at once. O(n log n): the share of
+ *  [a, b] is S(b) − S(a), where S is the running integral of 1 / (number open). */
+export declare function fair_shares(ivs: readonly (readonly [number, number])[]): {
+  shares: number[];
+  peak: number;
+};
+/** Fold the recording's spans per name. */
+export declare function span_rows(spans: readonly SpanRecord[] | undefined): SpanRow[];
+export interface RequestEntry {
+  ts: number;
+  method: string;
+  path: string;
+  route: string | null;
+  status: number;
+  ms: number;
+  /** CPU ms this request burned (process-wide delta; accurate when requests don't overlap) */
+  cpu_ms: number;
+  /** how many other requests were in flight when this one started */
+  inflight: number;
+  /** total ms this request spent in outbound network calls */
+  net_ms: number;
+  net_count: number;
+  /** true when the profiler itself made this request (page mode) */
+  internal?: boolean;
+  /** a remote function call (`path` is its own address: Kit's `url` names the page that asked,
+   *  or `/` when no page did, as for a server render reading a `prerender` function) */
+  remote?: true;
+  /** what ogygia's handle added to this page (server/request-stats.ts); absent off the page path */
+  og?: OgygiaRequestStats;
+  /** `tag()` stamps from the app (tenant, locale, variant…) */
+  tags?: Record<string, string>;
+  /** `span()` counts for this request: how many, and the top-level spans' summed ms */
+  span_count?: number;
+  span_ms?: number;
+  /** a deferred hole's endpoint request: what its render cache did */
+  hole?: HoleRequestStats;
+  /** performance.now() at the request's start (the trap matches a window's timeline on it) */
+  pt?: number;
+  /** the request's query string, kept so a caught request can be replayed */
+  search?: string;
+  /** the headers the trap config asked to keep for a replay */
+  replay_headers?: Record<string, string>;
+}
+/** The page's web vitals as the profiler user's browser reported them (p50 over the visits). */
+export interface PageVitals {
+  n: number;
+  ttfb: number | null;
+  fcp: number | null;
+  lcp: number | null;
+  cls: number | null;
+  inp: number | null;
+}
+/** The cold render (the warm-up) profiled on its own: what module load + compile cost per file. */
+export interface ColdStart {
+  /** wall ms of the cold render */
+  ms: number;
+  busy_ms: number;
+  /** self ms per file in the cold render, heaviest first */
+  files: {
+    file: string;
+    category: FrameCategory;
+    ms: number;
+  }[];
+  /** the cold render's CPU by owner, grouped as the drill-down's rows are (a package, `node core`,
+   *  a function, a component): what each row cost cold */
+  owners?: {
+    label: string;
+    ms: number;
+  }[];
+  /** outbound calls the cold render made: none means its extra waiting is not new connections */
+  calls?: number;
+}
+/** What the browser reported for one island fingerprint (the runtime's hydration beacon). */
+export interface ClientIslandStat {
+  /** the island's first fingerprint (the samples of every fingerprint of the entry are merged) */
+  fp: string;
+  entry: string;
+  /** the component's name, when the server row carried it */
+  name: string;
+  /** hydrations seen */
+  n: number;
+  /** wake → `data-hydrated`, p50 and max */
+  p50_ms: number;
+  max_ms: number;
+  /** the module-load part of it (hydrate core + the island's chunk closure), p50 */
+  load_p50_ms: number;
+  /** hydrations that discarded the server DOM and re-rendered: the markup the browser found was
+   *  not the markup the server sent (a post-SSR pass, a script that edited it before wake) */
+  recovered: number;
+  /** the named first divergence — the WHY of the recovery (e.g. "an injected <style>", "scoped
+   *  web-component hydration marks", "whitespace stripped"). Absent when unnameable. */
+  reason?: string;
+}
+export interface MemSample {
+  /** ms offset from window start */
+  t: number;
+  rss: number;
+  heap_used: number;
+}
+export interface ReportMeta {
+  id: string;
+  created: number;
+  /** `trap`: a slow request the background trap caught (its `request` is the one) */
+  trigger: "window" | "page" | "request" | "trap";
+  /** trap mode: the threshold the request crossed */
+  trap_over?: number;
+  /** page mode: the cold (warm-up) render profiled on its own */
+  cold?: ColdStart;
+  /** page mode: renders served the answers that were the same in every timed render, from memory
+   *  (`calls` of them): what keeping those answers takes off, measured */
+  answers?: {
+    runs_ms: number[];
+    calls: number;
+  };
+  /** page mode: the path that was rendered */
+  page?: string;
+  /** page mode: the originally-requested path, when it redirected to `page` (trailing slash, i18n, …) */
+  redirected_from?: string;
+  /** page mode: the redirect was a prerendered page's stub (a meta refresh answered 200) */
+  redirect_stub?: true;
+  /** page mode: wall ms of the one un-profiled warm-up render (cold module load / cache fill) */
+  warmup_ms?: number;
+  /** page mode: the HTTP status the profiled renders returned (200 = a real render; 3xx/4xx = not) */
+  run_status?: number;
+  /** page mode: representative response body size in bytes (a real page is large; a redirect is tiny) */
+  run_bytes?: number;
+  /** page mode: the timed renders' Cache-Control (what the page tells the browser to keep) */
+  run_cache_control?: string;
+  /** page mode: a timed render's response set a cookie (no shared cache keeps such a page) */
+  run_sets_cookie?: true;
+  /** page mode: every render returned the same document, byte for byte */
+  same_document?: boolean;
+  /** page mode: its route says `export const prerender = true` (the nearest file deciding) —
+   *  production serves its built HTML file */
+  prerendered?: boolean;
+  /** page mode: Kit's route id of the timed renders (`/(docs)/docs/[...slug]`) */
+  run_route?: string;
+  /** page mode: the timed renders answered 200 without the app's handle seeing them: a file the
+   *  build wrote, served before the app (a prerendered page) */
+  run_static?: true;
+  /** page mode, when the renders' documents differ: what changes between the first and the last */
+  doc_diff?: DocDiff;
+  /** page mode: a plain note when the run plan was trimmed to fit the serverless budget */
+  budget_note?: string;
+  /** page mode: the server's heap was nearly full, so these renders were not made (one more could
+   *  have ended the process): its use and limit when the profile finished */
+  heap_guard?: {
+    used_mb: number;
+    limit_mb: number;
+    skipped: string[];
+  };
+  /** recorded on AWS Lambda (Amplify's SSR), where a request is billed for its whole duration */
+  lambda?: boolean;
+  /** on Lambda: the function's memory, MB (it bills memory × wall time) */
+  lambda_mb?: number;
+  /** the V8 heap limit of the instance, MB: how far a leak can grow before the process dies */
+  heap_limit_mb?: number;
+  /** the instance it ran on: ms from the process start to its first request (a cold start on
+   *  Lambda, where an instance starts for a request), Node's own startup within that, its age and
+   *  the requests it served before this one */
+  instance?: {
+    first_request_ms: number;
+    node_ms: number;
+    age_s: number;
+    requests_before: number;
+  };
+  /** page mode: each render run, ms, AS THE APP WOULD HAVE PAID IT — the profiler's own share (its
+   *  CPU frames, its part of the GC pauses) taken out; `runs_measured` is what the clock said */
+  runs?: number[];
+  /** page mode: renders another visitor of the same page overlapped — left out of `runs`, their
+   *  samples set aside (at least one render ran clean) */
+  runs_set_aside?: number;
+  runs_measured?: number[];
+  /** the profiler's own cost inside the window, measured once and kept out of every other number */
+  overhead?: {
+    cpu_ms: number;
+    gc_ms: number;
+    per_run_ms: number;
+    per_run?: number[];
+    note: string;
+  };
+  /** request mode: the profiled request */
+  request?: {
+    method: string;
+    path: string;
+    route: string | null;
+    ms: number;
+  };
+  duration_ms: number;
+  sample_interval_us: number;
+  /** requests that completed inside the recording window */
+  requests: RequestEntry[];
+  loop_delay?: {
+    p50: number;
+    p99: number;
+    max: number;
+  };
+  cpu_percent?: number;
+  elu_percent?: number;
+  rss_mb?: number;
+  node: string;
+  /** recorded on the dev server (numbers include Vite's module pipeline) */
+  dev?: boolean;
+}
+export interface UserTiming {
+  name: string;
+  count: number;
+  total_ms: number;
+  max_ms: number;
+}
+export interface GcSummary {
+  count: number;
+  total_ms: number;
+  max_ms: number;
+}
+export interface ReportExtras {
+  net: NetCall[];
+  /** the app's own spans (`span()` from ogygia/profiler) recorded during the window */
+  spans?: SpanRecord[];
+  heap: HeapAllocator[] | null;
+  /** bytes per component (the nearest component above each sampled allocation) */
+  heap_components?: {
+    name: string;
+    bytes: number;
+  }[] | null;
+  mem: MemSample[];
+  /** performance.measure() spans emitted by the app/libraries during the window */
+  measures?: UserTiming[];
+  /** precise GC pauses from PerformanceObserver (more exact than the sampler) */
+  gc?: GcSummary | null;
+  /** I/O primitives timed via async_hooks (timers, fs, dns, sockets) */
+  io?: IoOp[];
+  /** exact call count per function name, from V8 precise coverage */
+  call_counts?: Record<string, number>;
+  /** bytes of each island module / preload href (a built app; measured after the recording) */
+  weights?: Record<string, number>;
+  /** what is inside each hashed chunk: a readable source list from the build's handoff */
+  contents?: Record<string, string[]>;
+  /** each island file's rendered total and heaviest named modules (the build's handoff) */
+  heavy?: Record<string, {
+    total: number;
+    top: {
+      name: string;
+      bytes: number;
+    }[];
+  }>;
+  /** re-export barrels each island file still holds, with how many modules each brings */
+  barrels?: Record<string, {
+    name: string;
+    fanout: number;
+  }[]>;
+  /** each island entry's lines that draw differently in the browser (hydration-hazards.ts) */
+  hazards?: Record<string, IslandHazard[]>;
+  /** the visit's own hole requests from the request log (made after the recording): server ms each */
+  /** `name`: the hole's component, from its own request (a hole the profiled render did not have —
+   *  the visited page's query put it there — is named all the same) */
+  hole_requests?: {
+    id: string;
+    ms: number;
+    name?: string;
+    p?: string;
+  }[];
+  /** the visit's in-app navigations, server side: the page request each one made (by its start `t`,
+   *  the page clock) — its ms, the CPU it burned, its outbound calls */
+  nav_requests?: {
+    t: number;
+    ms: number;
+    cpu_ms: number;
+    net_ms: number;
+    net_count: number;
+    inflight?: number;
+  }[];
+  /** the visit's own document request as the server's handler held it (the request log) */
+  doc_request?: {
+    ms: number;
+  };
+  /** browser-side hydration timings joined by fingerprint (the runtime's beacon) */
+  client?: ClientIslandStat[];
+  /** the page's web vitals from the same beacon */
+  vitals?: PageVitals;
+  /** the app's own browser marks (`mark()` from ogygia/profiler/client) for the page, per name */
+  client_marks?: ClientMarkStat[];
+  /** the browser's CPU profile of the page's hydration (the profiler user's latest visit) */
+  /** `windows`: the same trace cut to each island's hydrate window and the long tasks outside them */
+  client_cpu?: {
+    analysis: Analysis;
+    at: number;
+    sample_ms: number;
+    windows?: ClientWindows;
+  };
+  /** the visit's slowest interaction, sampled: what ran while it waited, and in its handlers */
+  interaction_cpu?: InteractionCpu;
+  /** a caught request's inputs (path + query, the kept headers): the "profile it again" button */
+  replay?: {
+    path: string;
+    headers: Record<string, string>;
+  };
+  /** the browser's picture of a visit to this page (the beacon) — the one-clock timeline joins it */
+  visit?: Visit;
+  /** the modules the build shipped as two copies, each copy's chunk (the build's handoff) */
+  dupes?: {
+    name: string;
+    copies: {
+      file: string;
+      bytes: number;
+      from?: string;
+    }[];
+  }[];
+  /** the latest visit to this page on the other kind of screen (a phone's when `visit` was wide, a
+   *  wide one's when it was a phone's): what sits below the first screen, or draws nothing, differs */
+  other_screen_visit?: Visit;
+  /** the latest visit to this page from another browser engine (Safari beside Chrome): findings one
+   *  engine makes that another never does */
+  other_engine_visit?: Visit;
+  /** the rendered document as a byte strip */
+  strip?: ByteStrip;
+  /** every file the document loads at start, weighed through the app (page-assets.ts); a dev
+   *  server records why it did not weigh instead */
+  assets?: PageAssets;
+  assets_missing?: string;
+  /** calls → loads → page.data keys → islands */
+  river?: River;
+  /** who caused the GC: each pause joined to the allocations before it */
+  gc_attr?: GcAttribution;
+  /** promises created in the window (count, sampled creators) */
+  promises?: {
+    count: number;
+    top: {
+      caller: string;
+      share: number;
+    }[];
+  };
+  /** what one more render left alive after a full collection, by allocation site */
+  retained?: Retained;
+  /** when the heap grew and what ran then */
+  alloc?: AllocTimeline;
+  /** the other requests the instance answered while the render ran */
+  contention?: Contention;
+  /** which component reads which page.data key, from the sources */
+  lineage?: Lineage;
+  /** the app lines that cost the most, every cost joined per line */
+  ledger?: LedgerLine[];
+  /** the known slow shapes found on those lines, grouped */
+  patterns?: Pattern[];
+  /** one render's time as a tree that adds up: phase → owner / call → line (drill.ts) */
+  drill?: DrillNode;
+  /** one render after every fix named, estimated without counting a saving twice */
+  forecast?: Forecast;
+  /** a few more renders with a full collection after each: does the heap keep growing? */
+  growth?: HeapGrowth;
+}
+/** One `mark()` name as the profiler user's browser reported it for the page. */
+export interface ClientMarkStat {
+  name: string;
+  n: number;
+  p50_ms: number;
+  max_ms: number;
+  errors: number;
+  /** the attribute keys seen on it */
+  attr_keys: string[];
+}
+export interface RouteAgg {
+  route: string;
+  count: number;
+  p50: number;
+  p95: number;
+  max: number;
+  avg: number;
+  net_p50: number;
+}
+/** A sampled origin that is a dev tool's: `fn (vite)` — a package in the brackets, not a `file:line`. */
+export declare function dev_tool_caller(caller: string): boolean;
+/**
+ * Where inside a hot function its time lands, when one line holds the biggest share and it is not
+ * the function's own first line: that line, its code, and the function it calls there. Once V8
+ * inlines a callee its time is the caller's own — a load "burning" 85 ms is often one call in it
+ * (measured on /inferno: newestReview inlined into load, named in one run of six). No regex.
+ */
+export declare function hot_line_of(f: Pick<FrameStat, "name" | "line" | "self_ms" | "lines" | "src">, app_fns: ReadonlySet<string>): {
+  line: number;
+  ms: number;
+  code: string;
+  calls?: string;
+} | null;
+/** A render that mostly waited: on its timeline, waiting (calls, and what no hook saw) is 60% of a
+ *  render of 20 ms or more; with no timeline, the window's CPU under a quarter (the old reading). */
+export declare function mostly_waited(tl: {
+  window_ms: number;
+  wait_ms: number;
+  gap_ms: number;
+} | null | undefined, busy_pct: number): boolean;
+export interface Finding {
+  severity: "info" | "warn";
+  /** stable machine code, e.g. 'sequential-network' */
+  code: string;
+  /** one plain-text sentence */
+  message: string;
+  /** what to do about it, one sentence (a warn usually has one) */
+  fix?: string;
+  /** the report row it points at: `comp:<name>` / `fn:<key>` — the UI opens that row */
+  anchor?: string;
+  /** where in the code, when the finding is about one place */
+  file?: string;
+  line?: number;
+  /** the slow pattern (its index in the report's `patterns`) that explains this same problem */
+  pattern?: number;
+  /** the islands a browser finding is about, by fingerprint (the devtools light them up) */
+  fps?: string[];
+}
+/** A URL path with its variable segments (numbers, uuids, hashes, long tokens) folded to `:id`. */
+export declare function path_template(url: string): {
+  host: string;
+  tpl: string;
+};
+/** N+1 shapes: the same endpoint hit once per item. */
+export declare function n_plus_one(net: NetCall[], min?: number): {
+  host: string;
+  tpl: string;
+  count: number;
+  ms: number;
+}[];
+/** The plain-language bottleneck read, as structured data. The HTML verdict and
+ * the JSON report both render from this, so they never drift. */
+/** THE PAGE'S WEIGHT, as findings: the JS it runs at start (and what the biggest files hold), what
+ *  blocks the first paint, the code kept for later. From page-assets.ts — the score reads the same. */
+/** The page's own origin, from its weighed files: its islands' (always same-origin), else its first
+ *  script's. '' when nothing was weighed. */
+export declare function page_origin(pa: PageAssets | undefined): string;
+/**
+ * THE PAGE'S JS AT START, as the score and the findings both read it: the files weighed from the
+ * HTML and their imports, plus the scripts the profiler user's own browser loaded at runtime that
+ * nothing in the HTML names (runtime_scripts — a CDN library fetching its parts, a runtime's
+ * on-demand chunk). Without the second half, a page that loads its JS from a script weighed light.
+ */
+export declare function start_js(extras: Pick<ReportExtras, "assets" | "visit">): {
+  js: number;
+  js_wire: number;
+  js_files: number;
+  runtime: RuntimeScripts | null;
+  woke_early: {
+    bytes: number;
+    wire: number;
+    files: number;
+  } | null;
+  /** the ogygia runtime's on-demand parts the visit loaded at start (as its islands woke) */
+  runtime_parts: {
+    bytes: number;
+    wire: number;
+    files: number;
+  } | null;
+} | null;
+/** The modules the build shipped twice whose copies are both in files this page loads (its weighed
+ *  files and its visit's scripts), each with the bytes the second copy costs; the costliest first. */
+export declare function page_duplicates(extras: Pick<ReportExtras, "dupes" | "assets" | "visit">): {
+  name: string;
+  copies: {
+    file: string;
+    bytes: number;
+    from?: string;
+  }[];
+  extra: number;
+}[];
+/** What a browser hid, from what the report knows itself. Safari reports each of another origin's
+ *  files as 0 bytes (Timing-Allow-Origin or not): the report weighed the files the page names and
+ *  their imports, and a visit from another engine measured what scripts loaded — a hidden size takes
+ *  the weight, marked. And only Chromium says which files held the first paint: for another engine,
+ *  the files the HTML makes blocking (a head stylesheet, a classic sync script) are marked so. And a
+ *  font downloaded again takes the Vary header the weighing read (the cause, in Safari, with Origin). */
+export declare function with_hidden_filled(v: Visit, origin: string | undefined, assets: PageAssets | undefined, other: Visit | undefined): Visit;
+/** A remote function's name from its call's address (`/<appDir>/remote/<file hash>/<name>/<argument>`),
+ *  or the address when it is not one. */
+export declare function remote_function_name(path: string): string;
+export declare function derive_findings(a: Analysis, meta: ReportMeta, extras: ReportExtras): Finding[];
+/**
+ * A finding that a slow pattern already explains points at it (`pattern`, its index), so the two
+ * read as one problem: a finding and a pattern share a code line (a site, a caller line, or the
+ * function a site sits in), the row the finding opens is a site's function, or a network finding
+ * names the calls a waits-in-a-row site made. Nothing is hidden; the finding gains the link.
+ */
+export declare function link_patterns(findings: Finding[], patterns: readonly Pattern[], a: Pick<Analysis, "functions" | "components">): void;
+/** The island rows of the profiled page: the page request that recorded them (detail is on only
+ *  while the profiler records, so the internal render carries them). */
+export declare function island_rows_of(meta: ReportMeta): IslandStat[];
+/**
+ * THE ISLAND HOST WRAPPERS by name. The compiler wraps every island in a virtual
+ * `wrapper/<id>.svelte`, and Svelte names that function after the file: `_b95bfb97fab` (the id
+ * minus its first character, made an identifier). The island rows know the id (in the entry URL)
+ * and the component: this returns the `rename` hook `analyze()` takes, so the wrapper reads
+ * `ProductCard (island host)` in every table, stack and flame. Rows come from every request in
+ * the window (a page profile's own render, a trapped page, a header-profiled request).
+ */
+export declare function island_host_renamer(requests: readonly RequestEntry[]): ((name: string, url: string) => string | undefined) | undefined;
+/** What to call a hole: its component and props (`Recommendations {"forProduct":"P1"}`), else its id. */
+export declare function hole_label(h: Pick<HoleStat, "id" | "name" | "props">): string;
+/** The hole endpoint requests in the window, per hole id: hits / misses / uncached renders. */
+export declare function hole_economics(meta: ReportMeta): Map<string, {
+  id: string;
+  hit: number;
+  miss: number;
+  none: number;
+  ms: number;
+  ttl: number;
+}>;
+/** The display name of an island: its component's name when the row carries it, else the
+ *  entry's basename (`ProductCard` from `.../ProductCard.svelte`; a built facade keeps its file). */
+export declare function island_name(row: Pick<IslandStat, "entry" | "name"> | string): string;
+/**
+ * ONE ROW PER ISLAND: the tail records a row per fingerprint (a list of 48 cards is 48 props
+ * sidecars, one each), and the fingerprint is what the browser's beacon joins on — but the table
+ * and the findings speak of the island. Rows with the same entry and wake merge: copies and
+ * bytes add up, references and hints union, the first devalue culprit stands for all, and
+ * `variants` says how many fingerprints went in.
+ */
+export declare function group_islands(rows: readonly IslandStat[]): IslandStat[];
+export declare function island_js_bytes(row: IslandStat, weights: Record<string, number> | undefined): number | null;
+/**
+ * WHAT MAKING SOME ISLANDS LAKES SAVES: the bytes of their closures (each chunk once) that no other
+ * waking island on the page loads — a shared chunk (the framework's runtime) another island needs
+ * downloads anyway. `loads`: their closures, each chunk once. Null without the build's weights.
+ */
+export declare function lake_saving(them: readonly IslandStat[], rows: readonly IslandStat[], weights: Record<string, number> | undefined): {
+  loads: number;
+  saves: number;
+} | null;
+/**
+ * WHAT ONLY EACH ISLAND NEEDS: of an island's closure (its entry and chunks), the bytes no other
+ * waking island on the page uses — what dropping (or deferring) that island would really save.
+ * `island_js_bytes` counts shared chunks once per island; this counts each once, where it belongs.
+ * Keyed by entry (copies of one island are one closure). Null without the build's weights.
+ */
+export declare function island_js_unique(rows: readonly IslandStat[], weights: Record<string, number> | undefined): Map<string, number> | null;
+/** Kit-shaped findings: the load lanes and the parent() chain, universal loads, and the client
+ *  router's serialization of load data. */
+/** ms of devalue work done for Kit's copy of the server load data: each devalue function's own time,
+ *  by the share of its call paths that pass through Kit's serializer (`add_node`, data_serializer.js,
+ *  or render_response). A function with no recorded paths counts only when it is `uneval` itself. */
+export declare function kit_load_serialize_ms(a: Analysis): number;
+/** Cold vs warm per file: what the first render paid over a warm one (module load + compile). */
+export declare function cold_rows(a: Analysis, meta: ReportMeta): {
+  file: string;
+  category: FrameCategory;
+  cold_ms: number;
+  warm_ms: number;
+  extra_ms: number;
+}[];
+/** The spread of a component across runs: median of the rest against the max, and the cold first run. */
+export declare function run_spread(runs_ms: number[]): {
+  min: number;
+  median: number;
+  max: number;
+  max_run: number;
+  after: number;
+  cold: boolean;
+} | null;
+/** Do the runs climb? The page getting slower render by render — what a page that keeps memory, or
+ *  a cache that grows without a bound, does to an instance as it ages. The slope is the median of
+ *  every pair's slope (one slow run cannot tilt it), and it counts only when most pairs agree: at
+ *  least 3 of 4 later runs slower than an earlier one. A cold first run is left out (that is the
+ *  cold start, not a climb). Needs 4 runs; null when the runs do not climb. */
+export declare function run_trend(runs_ms: readonly number[]): {
+  from: number;
+  to: number;
+  slope_ms: number;
+  rise_ms: number;
+  rise_pct: number;
+  agree: number;
+  runs: number;
+} | null;
+/** Gather the ogygia signals a page score reads — the same numbers the findings above compute, so
+ *  the score and the findings never disagree. All safe when a signal is absent (no visits, no server
+ *  timing). See {@link page_score}. */
+export declare function page_score_of(meta: ReportMeta, extras: ReportExtras): PageScore;
+/** The JSON report (`?as=json`, the testing engine, the MCP tool): the written-out shape of what
+ *  `report_json` builds. The compiler checks the two against each other. */
+export type ReportJson = {
+  target: {
+    runs: number[] | null;
+    warmup_ms: number | null;
+    run_status: number | null;
+    run_bytes: number | null;
+    cache_control: string | null;
+    prerendered: string | null;
+    budget_note: string | null;
+    runs_measured: number[] | null;
+    instance: {
+      first_request_ms: number;
+      node_ms: number;
+      age_s: number;
+      requests_before: number;
+    } | null;
+    lambda: boolean;
+    request: {
+      method: string;
+      path: string;
+      route: string | null;
+      ms: number;
+    } | null;
+    redirect_stub?: boolean | undefined;
+    page: string | null;
+    redirected_from: string | null;
+  };
+  summary: {
+    window_ms: number;
+    busy_ms: number;
+    overhead: {
+      top: {
+        name: string;
+        url: string;
+        line: number;
+        self_ms: number;
+      }[];
+      cpu_ms: number;
+      gc_ms: number;
+      per_run_ms: number;
+      per_run?: number[];
+      note: string;
+    } | null;
+    busy_pct: number;
+    idle_ms: number;
+    gc_ms: number;
+    gc_sampled_ms: number;
+    verdict: string;
+    sample_count: number;
+    cpu_percent: number | null;
+    elu_percent: number | null;
+    loop_delay_ms: {
+      p50: number;
+      p99: number;
+      max: number;
+    } | null;
+    rss_mb: number | null;
+  };
+  score: PageScore;
+  findings: Finding[];
+  budget: {
+    label: string;
+    category: FrameCategory;
+    ms: number;
+    pct: number;
+  }[];
+  timeline: {
+    window_ms: number;
+    cpu_ms: number;
+    wait_ms: number;
+    unaccounted_ms: number;
+    phases: {
+      phase: Phase;
+      label: string;
+      cpu_ms: number;
+      wait_ms: number;
+    }[];
+    steps: {
+      at_ms: number;
+      ms: number;
+      pct: number;
+      kind: "wait" | "cpu" | "gap";
+      phase: Phase;
+      what: string;
+      detail: string | null;
+      file: string | null;
+      calls: {
+        label: string;
+        ms: number;
+        caller?: string;
+        callers?: string[];
+        timings?: TimelineCall["timings"];
+        body_ms?: number;
+      }[] | null;
+      within: string | null;
+    }[];
+    parallelizable: {
+      calls: string[];
+      ms: number;
+      save_ms: number;
+    }[];
+    lanes: {
+      file: string;
+      level: "error" | "page" | "layout";
+      kind: "server" | "universal";
+      t0_ms: number;
+      t1_ms: number;
+      cpu_ms: number;
+      wait_ms: number;
+      awaited_parent: boolean;
+    }[];
+    chain: LoadChain | null;
+    awaits: AwaitEdge[];
+  } | null;
+  spans: SpanRow[];
+  paths: {
+    owner: {
+      name: string;
+      file: string;
+      line: number;
+      category: FrameCategory;
+      total_ms: number;
+      calls: number | null;
+    };
+    ms: number;
+    pct_busy: number;
+    share_of_owner: number;
+    functions: {
+      name: string;
+      file: string;
+      line: number;
+      category: FrameCategory;
+      package: string | null;
+      ms: number;
+    }[];
+    tree: PathNode;
+  }[];
+  ogygia: {
+    island_rows: {
+      client: {
+        reason?: string | undefined;
+        hydrations: number;
+        p50_ms: number;
+        max_ms: number;
+        load_p50_ms: number;
+        recovered: number;
+      } | null;
+      hazards?: IslandHazard[] | undefined;
+      name: string;
+      entry: string;
+      fp: string;
+      fingerprints: number;
+      copies: number;
+      wake: string;
+      ssr_ms: number | null;
+      props_bytes: number;
+      canonical_bytes: number;
+      json: boolean;
+      devalue_culprit: string | null;
+      seed_refs: number;
+      seed_ref_keys: string[];
+      js_bytes: number | null;
+      js_only_bytes: number | null;
+      modules: string[];
+      interactivity: import("@ogygia/core/internal/server").IslandInteractivity | null;
+    }[];
+    seed: {
+      keys: import("@ogygia/core/internal/server").SeedKeyStat[];
+      whole_by: string[];
+    } | null;
+    hole_rows: {
+      id: string;
+      component: string | null;
+      props: string | null;
+      when: string;
+      hydrate: string | null;
+      max_age_s: number;
+      copies: number;
+      requests: {
+        hit: number;
+        miss: number;
+        uncached: number;
+        avg_ms: number;
+      } | null;
+    }[];
+    transform_ms: number;
+    islands: number;
+    hints: number;
+    holes: number;
+    seed_bytes: number;
+    remote_seed_bytes: number;
+    tail_bytes: number;
+    fnm_bytes: number;
+    ctx_bytes: number;
+    seed_json: boolean;
+    seed_culprit?: string | null;
+  } | null;
+  kit: {
+    uneval_ms: number;
+    etag_ms: number;
+  };
+  components: {
+    name: string;
+    instances: number | null;
+    file: string;
+    path: string;
+    line: number;
+    column: number | null;
+    self_ms: number;
+    total_ms: number;
+    per_call_ms: number | null;
+    pct_busy: number;
+    alloc_bytes: number | null;
+    markup_ms: number | null;
+    logic_ms: number | null;
+    parent: string | null;
+    runs_ms: number[] | null;
+    hot_lines: {
+      line: number;
+      ms: number;
+    }[] | null;
+    source: {
+      start: number;
+      lines: string[];
+    } | null;
+    callees: Callee[] | null;
+    stacks: {
+      ms: number;
+      frames: string[];
+    }[];
+  }[];
+  hot_functions: {
+    name: string;
+    label: string | null;
+    instances: number | null;
+    file: string;
+    path: string;
+    line: number;
+    column: number | null;
+    category: FrameCategory;
+    package: string | null;
+    self_ms: number;
+    total_ms: number;
+    per_call_ms: number | null;
+    stacks: {
+      ms: number;
+      frames: string[];
+    }[];
+    hot_lines: {
+      line: number;
+      ms: number;
+    }[] | null;
+    source: {
+      start: number;
+      lines: string[];
+    } | null;
+    callees: Callee[] | null;
+  }[];
+  files: {
+    file: string;
+    category: FrameCategory;
+    self_ms: number;
+    pct_busy: number;
+  }[];
+  network: {
+    count: number;
+    total_ms: number;
+    sequential_ms: number;
+    errors: number;
+    hosts: {
+      host: string;
+      calls: number;
+      total_ms: number;
+      p50_ms: number;
+      max_ms: number;
+      errors: number;
+    }[];
+    calls: {
+      method: string;
+      url: string;
+      host: string;
+      status: number;
+      wait_ms: number;
+      body_ms: number | null;
+      bytes: number | null;
+      transfer_bytes: number | null;
+      encoding: string | null;
+      type: string | null;
+      req_bytes: number | null;
+      req_payload: string | null;
+      route: string | null;
+      caller: string | null;
+      callers: string[] | null;
+      server_timing: ServerTiming[] | null;
+      trace: UpstreamTrace | null;
+      headers: Record<string, string> | null;
+      error: string | null;
+    }[];
+  };
+  cold: {
+    calls?: number | undefined;
+    ms: number;
+    busy_ms: number;
+    files: {
+      file: string;
+      category: FrameCategory;
+      cold_ms: number;
+      warm_ms: number;
+      extra_ms: number;
+    }[];
+  } | null;
+  browser: {
+    cpu?: {
+      components: {
+        name: string;
+        file: string;
+        self_ms: number;
+        total_ms: number;
+        instances: number | null;
+      }[];
+      hot_functions: {
+        name: string;
+        file: string;
+        line: number;
+        category: FrameCategory;
+        package: string | null;
+        self_ms: number;
+        total_ms: number;
+      }[];
+      by_island?: {
+        fp: string;
+        name: string | null;
+        ms: number;
+        top: WindowFn[];
+      }[] | undefined;
+      outside_islands?: {
+        ms: number;
+        top: WindowFn[];
+      } | undefined;
+      at: number;
+      sampled_ms: number;
+      busy_ms: number;
+    } | undefined;
+    interaction_cpu?: InteractionCpu | undefined;
+    visit?: {
+      longtasks: number;
+      islands: {
+        changed?: boolean | undefined;
+        fp: string;
+        t0: number;
+        loaded: number;
+        done: number;
+      }[];
+      firsts: {
+        fp: string;
+        t: number;
+        type: string;
+      }[];
+      shifts: number;
+      cls_by_island: {
+        [k: string]: number;
+      };
+      resource_totals?: {
+        type: string;
+        count: number;
+        transfer: number;
+        size: number;
+      }[] | undefined;
+      at: number;
+      nav: VisitNav;
+      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: number;
+      resource_bytes: number;
+    } | undefined;
+    marks?: ClientMarkStat[] | undefined;
+    n?: number | undefined;
+    ttfb?: number | null | undefined;
+    fcp?: number | null | undefined;
+    lcp?: number | null | undefined;
+    cls?: number | null | undefined;
+    inp?: number | null | undefined;
+  } | null;
+  replay: {
+    url: string;
+    path: string;
+    headers: string[];
+  } | null;
+  assets: ReportJsonAssets | {
+    missing: string;
+  } | null;
+  strip: {
+    tail?: StreamTail | undefined;
+    chunks?: {
+      end: number;
+      t: number;
+    }[] | undefined;
+    total: number;
+    by_kind: Partial<Record<StripKind, number>>;
+    shadow_count: number;
+    segments: StripSegment[];
+  } | null;
+  river: River | null;
+  memory: {
+    rss_start_mb: number;
+    rss_end_mb: number | null;
+    growth_mb: number;
+    gc: GcSummary | null;
+    gc_attribution: {
+      pauses: {
+        t_ms: number;
+        ms: number;
+        ms_measured: number;
+        kind: "other" | "minor" | "major" | "incremental" | "weak";
+        forced: boolean;
+        since_ms: number;
+        allocated_bytes: number;
+        estimated: boolean;
+        why: string;
+        running: {
+          label: string;
+          category: string;
+          file?: string;
+        } | null;
+        top: {
+          name: string;
+          component: string | null;
+          bytes: number;
+          share: number;
+        }[];
+      }[];
+      makers: {
+        name: string;
+        file: string;
+        line: number;
+        category: FrameCategory;
+        component: string | null;
+        via: string | null;
+        allocated_bytes: number;
+        share: number;
+        gc_ms: number;
+        pauses: number;
+      }[];
+      components: {
+        name: string;
+        allocated: number;
+        gc_ms: number;
+      }[];
+      count: number;
+      total_ms: number;
+      max_ms: number;
+      measured_ms: number;
+      overhead_ms: number;
+      minor: number;
+      major: number;
+      incremental: number;
+      weak: number;
+      allocated_mb: number;
+      alloc_rate_mb_s: number;
+      retained_mb?: number;
+      slices: number;
+      slice_ms: number;
+    } | null;
+    allocators: {
+      name: string;
+      file: string;
+      line: number;
+      category: FrameCategory;
+      self_bytes: number;
+      total_bytes: number;
+    }[];
+    by_component: {
+      name: string;
+      bytes: number;
+    }[];
+    samples: {
+      t_ms: number;
+      rss_mb: number;
+      heap_used_mb: number;
+    }[];
+  };
+  deopts: {
+    name: string;
+    file: string;
+    line: number;
+    category: FrameCategory;
+    self_ms: number;
+    count: number;
+    reasons: Record<string, number>;
+  }[];
+  sync_io: {
+    name: string;
+    module: string;
+    self_ms: number;
+    total_ms: number;
+    calls: number | null;
+    callers: string[];
+  }[];
+  memo_candidates: MemoCandidate[];
+  promises: {
+    count: number;
+    per_render: number;
+    top: {
+      caller: string;
+      share: number;
+    }[];
+  } | null;
+  retained: {
+    total_bytes: number;
+    render_ms: number;
+    sites: {
+      name: string;
+      file: string;
+      line: number;
+      via: string | null;
+      component: string | null;
+      bytes: number;
+      share: number;
+    }[];
+  } | null;
+  steps: RenderSteps | null;
+  stacks: {
+    window_ms: number;
+    raw_samples: number;
+    frames: {
+      name: string;
+      file: string | null;
+      category: FrameCategory;
+      parent: number;
+    }[];
+    t_ms: number[];
+    d_ms: number[];
+    leaf: number[];
+  } | null;
+  alloc: {
+    grown_mb: number;
+    period_ms: number;
+    longest_gap_ms: number;
+    window: {
+      offset_ms: number;
+      ms: number;
+    } | null;
+    bursts: {
+      t0_ms: number;
+      t1_ms: number;
+      mb: number;
+      mb_per_s: number;
+      gc_inside: boolean;
+      running: {
+        label: string;
+        category: string;
+        file?: string;
+        share: number;
+      }[];
+    }[];
+    samples: {
+      t_ms: number;
+      heap_mb: number;
+    }[];
+  } | null;
+  contention: {
+    overlap_ms: number;
+    cpu_max_ms: number;
+    busy_share: number;
+    inflight_at_start: number[];
+    per_window: {
+      n: number;
+      overlap_ms: number;
+      cpu_max_ms: number;
+    }[];
+    requests: ContendingRequest[];
+    note: string;
+  } | null;
+  lineage: {
+    keys: {
+      key: string;
+      from: string | null;
+      shipped_bytes: number;
+      load_wait_ms: number | null;
+      verdict: KeyVerdict;
+      readers: {
+        name: string;
+        island: boolean;
+      }[];
+    }[];
+    components: LineageComponent[];
+    unread: string[];
+    server_only: string[];
+    notes: string[];
+  } | null;
+  ledger: LedgerLine[] | null;
+  patterns: {
+    save_per_render_ms: number;
+    cost_per_render_ms: number;
+    kind: PatternKind;
+    title: string;
+    fix: string;
+    example?: {
+      before: string;
+      after: string;
+    };
+    sites: PatternSite[];
+    cost_ms: number;
+    alloc_bytes: number;
+    save_ms: number;
+    evidence: string;
+    wait?: boolean;
+    kept_bytes?: number;
+    requests_left?: number;
+    growth?: "grows" | "levels-off";
+    seed_bytes?: number;
+    chains?: {
+      start: number;
+      ms: number;
+    }[][];
+    naive_save_ms?: number;
+  }[] | null;
+  growth: HeapGrowth | null;
+  drill: DrillNode | null;
+  forecast: Forecast | null;
+  span_values: SpanValueRow[];
+  waiting: {
+    caller: string;
+    kind: string;
+    count: number;
+    wait_ms: number;
+  }[];
+  user_timings: {
+    name: string;
+    count: number;
+    total_ms: number;
+    avg_ms: number;
+    max_ms: number;
+  }[];
+  requests: {
+    method: string;
+    path: string;
+    route: string | null;
+    status: number;
+    ms: number;
+    cpu_ms: number;
+    wait_ms: number;
+    net_ms: number;
+    net_count: number;
+    inflight: number;
+    internal: boolean;
+    tags: Record<string, string> | null;
+    span_count: number | null;
+    span_ms: number | null;
+    hole: HoleRequestStats | null;
+  }[];
+  links: {
+    html: string;
+    json: string;
+    cpuprofile: string;
+  };
+  other_requests_ms?: number | undefined;
+  schema: string;
+  version: number;
+  engine: {
+    version: number;
+  };
+  units: {
+    time: string;
+    size: string;
+    memory_suffix_mb: boolean;
+  };
+  id: string;
+  created: number;
+  kind: "window" | "page" | "request" | "trap";
+  node: string;
+  dev: boolean;
+  sourcemapped: boolean;
+};
+/** The page's assets in the JSON report (`twice` is absent when nothing shipped twice). */
+type ReportJsonAssets = {
+  twice?: {
+    name: string;
+    copies: {
+      file: string;
+      bytes: number;
+      from?: string;
+    }[];
+    extra: number;
+  }[];
+  missed_why?: {
+    url: string;
+    why: string;
+  }[] | undefined;
+  missed?: string[] | undefined;
+  totals: {
+    js: number;
+    js_wire: number;
+    css: number;
+    css_wire: number;
+    font: number;
+    image: number;
+    wire: number;
+    lazy_js: number;
+    blocking: number;
+    blocking_count: number;
+    js_files: number;
+  };
+  html: {
+    bytes: number;
+    wire: number;
+  };
+  inline: {
+    script: number;
+    style: number;
+  };
+  files: {
+    contains?: string[] | undefined;
+    lazy?: boolean | undefined;
+    blocking?: boolean | undefined;
+    url: string;
+    kind: import("@ogygia/core/insights").AssetKind;
+    via: "script" | "img" | "modulepreload" | "stylesheet" | "island" | "preload" | "inline-import" | "static-import" | "route-node" | "runtime-phase";
+    bytes: number;
+    wire: number;
+  }[];
+  missing?: undefined;
+};
+export declare function report_json(a: Analysis, meta: ReportMeta, base: string, extras: ReportExtras): ReportJson;
+/**
+ * A complete, portable dump: everything the report needs to reconstruct the
+ * full interactive report later, on any machine. This is the artifact a user
+ * downloads from a serverless host (where reports can't be stored) and uploads
+ * to the viewer. Rendering needs no inspector, so it works everywhere.
+ */
+export interface ReportDump {
+  kind: "ogygia-profiler-dump";
+  version: 1;
+  meta: ReportMeta;
+  analysis: Analysis;
+  extras: ReportExtras;
+}
+export declare function report_dump(a: Analysis, meta: ReportMeta, extras: ReportExtras): ReportDump;
+/** Narrowing guard for an uploaded dump before we render it. */
+export declare function is_dump(x: unknown): x is {
+  meta: ReportMeta;
+  analysis: Analysis;
+  extras: ReportExtras;
+};
+export { type HoleRequestStats, type IslandHazard, type IslandStat, type OgygiaRequestStats, type SpanRecord, browser_of, hazard_fix, hazard_words, inline_threshold_tune, own_requests };