@ogygia/devtools 0.0.0 → 0.11.1

package/dist/profiler/timeline.d.ts

@@ -0,0 +1,279 @@
+import { CpuProfile, FrameCategory } from "./analyze.js";
+export type Phase = "hooks" | "load" | "remote" | "render" | "ogygia" | "kit" | "other";
+export declare const PHASE_LABEL: Record<Phase, string>;
+/** The frame facts the timeline needs per profile node — what `analyze` resolved. */
+export interface FrameInfo {
+  name: string;
+  url: string;
+  line: number;
+  category: FrameCategory;
+  pkg?: string;
+}
+export interface TimelineCall {
+  /** performance.now() ms at start */
+  start: number;
+  /** ms until done (headers + body for a fetch); < 0 = never finished */
+  ms: number;
+  /** what to call it: `GET host/path` or `timer` / `file read` */
+  label: string;
+  /** 'net' (fetch / http) or an I/O primitive kind */
+  kind: string;
+  /** the function that started it, when resolved */
+  caller?: string;
+  /** the phase of the code that started it (from the caller's file); else the wait takes the
+   *  phase of whatever ran just before it */
+  phase?: Phase;
+  /** the first-party call path above the caller, resolved (`fetchStock (…)` ← `load (…)`) */
+  callers?: string[];
+  /** the upstream's own Server-Timing: what their side spent the wait on */
+  timings?: {
+    name: string;
+    ms: number;
+    desc?: string;
+  }[];
+  /** a fetch: of `ms`, the part spent reading the body after the headers came */
+  body_ms?: number;
+}
+export interface TimelineInput {
+  /** performance.now() at `Profiler.start` */
+  perf_start: number;
+  /** the request's window, performance.now() ms */
+  window: {
+    start: number;
+    end: number;
+  };
+  calls: TimelineCall[];
+  /** page mode: every run's window (for the per-run component split) */
+  runs?: {
+    start: number;
+    end: number;
+  }[];
+  /** every async resource the hooks saw (waits or not): a gap is named after what was pending */
+  pending?: {
+    start: number;
+    end: number;
+    label: string;
+    kind: string;
+  }[];
+  /** the app's `handle` functions that live outside the hooks file: name → file stem
+   *  (source-scan `handle_parts`), so their work after `resolve()` reads as hooks, not "other":
+   *  the function itself anywhere on a stack, or any code in its module on a stack nothing else
+   *  claims */
+  hooks?: ReadonlyMap<string, string>;
+  /** the profiled request's Kit route id (`/latecomer`, `/(app)/p/[id]`): a sample under ANOTHER
+   *  route's page or layout file is another request's work, set aside */
+  route?: string;
+  /** windows (performance.now() ms) whose samples are another visitor's as much as the profiled
+   *  render's (a render of the same page overlapped): set aside by time */
+  set_aside?: {
+    start: number;
+    end: number;
+  }[];
+}
+/** Which call started only once another finished: the await that serialized them. */
+export interface AwaitEdge {
+  /** the call that had to finish first */
+  from: string;
+  /** the call that started right after it */
+  to: string;
+  /** ms between the one's end and the other's start (CPU, or nothing) */
+  gap_ms: number;
+  /** where `to` was started from — the await site to look at */
+  at?: string;
+  /** the file:line chain above it, when captured */
+  callers?: string[];
+}
+/** One call as the causality graph draws it: a box on the render's clock, in a lane. */
+export interface AwaitNode {
+  label: string;
+  t0: number;
+  t1: number;
+  lane: number;
+  kind: string;
+  caller?: string;
+}
+export interface Segment {
+  /** ms from the window start */
+  t0: number;
+  t1: number;
+  kind: "cpu" | "wait" | "gap";
+  /** cpu: the owning component / function; wait: the call (or "N calls in parallel") */
+  label: string;
+  /** cpu: the leaf-most named frame when it differs from the owner (what inside it burned) */
+  detail?: string;
+  /** cpu: owner's `file:line` */
+  file?: string;
+  category: FrameCategory;
+  phase: Phase;
+  /** wait: every call in flight during the segment */
+  calls?: {
+    label: string;
+    ms: number;
+    caller?: string;
+    callers?: string[];
+    timings?: TimelineCall["timings"];
+    body_ms?: number;
+  }[];
+  /** the innermost `span()` this segment sits inside, when any */
+  within?: string;
+  /** cpu: the Kit load file on its stack (`routes/+page.server.ts`) — the load a helper in
+   *  `$lib` ran for */
+  lane?: string;
+  /** gap: the async resources that were pending across it — what the wait most likely was */
+  pending?: string[];
+}
+export interface PhaseRow {
+  phase: Phase;
+  cpu_ms: number;
+  wait_ms: number;
+  /** whose CPU it was: the owners holding a tenth or more of it, biggest first (at most 3) */
+  top?: {
+    label: string;
+    ms: number;
+  }[];
+}
+export interface ParallelGroup {
+  /** the calls, in the order they ran */
+  calls: string[];
+  /** their summed wait */
+  ms: number;
+  /** what running them together would save (sum − longest) */
+  save_ms: number;
+  /** segment indices in `segments` */
+  at: number[];
+}
+/** One Kit load function's lane: when it ran, what it cost, and whether it awaited its parent. */
+export interface LoadLane {
+  /** the load file, relative to src (`routes/hell/+page.server.ts`) */
+  file: string;
+  level: "layout" | "page" | "error";
+  /** `+page.server.ts` runs on the server only; a universal `+page.ts` runs in the browser too */
+  kind: "server" | "universal";
+  /** ms from the window start: first and last moment this load was on the CPU or waiting */
+  t0: number;
+  t1: number;
+  cpu_ms: number;
+  wait_ms: number;
+  /** Kit's `parent()` ran under this load: it awaited the layout's data before doing its own work */
+  awaited_parent: boolean;
+}
+/** The page load began only after the layout load finished — Kit runs them together unless the
+ *  page awaits `parent()` (or the layout's data is otherwise on its path). */
+export interface LoadChain {
+  layout: string;
+  page: string;
+  /** how long the page's load sat behind the layout's: the most that running them together saves */
+  serial_ms: number;
+  /** a `parent()` frame was seen under the page load (else inferred from the timing alone) */
+  explicit: boolean;
+  /** from the page load's source (set at report time): its `await parent()` line, the names that
+   *  sets, the first line reading one (null: none), and the awaits between that waited for nothing */
+  parent_use?: {
+    line: number;
+    names: string[];
+    first_use: number | null;
+    awaits_before_use: number;
+  };
+}
+export interface Timeline {
+  window_ms: number;
+  /** the app's CPU inside the window (the profiler's own frames are in `overhead_ms`, not here) */
+  cpu_ms: number;
+  wait_ms: number;
+  gap_ms: number;
+  overhead_ms: number;
+  segments: Segment[];
+  phases: PhaseRow[];
+  parallelizable: ParallelGroup[];
+  /** Kit's load functions, one lane each (absent when none ran in the window) */
+  lanes?: LoadLane[];
+  chain?: LoadChain;
+  /** THE CAUSALITY GRAPH of the waits: every call as a box in a lane, and an edge wherever a
+   *  call started only once another had finished (the await that serialized them) */
+  awaits?: {
+    nodes: AwaitNode[];
+    edges: AwaitEdge[];
+  };
+  /** WHAT RAN INSIDE each app owner: the deepest app function on the stack of its samples (an
+   *  arrow, a callback, the owner itself), with its ms. An owner is the nearest NAMED function, so
+   *  this is the only record of which of its arrows held the time. Keyed by the owner's label. */
+  inner?: Record<string, InnerFn[]>;
+}
+export interface InnerFn {
+  /** the function's name, `(anonymous)` for an arrow */
+  name: string;
+  /** its own start, `file:line` (short path) */
+  file: string;
+  ms: number;
+}
+/** The lane a load frame / caller belongs to: `{ file, level, kind }`, or null. */
+export declare function load_lane_of(text: string): Pick<LoadLane, "file" | "level" | "kind"> | null;
+/** The Kit phase of ONE frame, or null when the frame says nothing about it. */
+export declare function phase_of_frame(f: FrameInfo, hooks?: ReadonlyMap<string, string>): Phase | null;
+/** Walk a stack leaf → root; the first frame that names a phase wins (the deepest decision). */
+export declare function phase_of_stack(frames: FrameInfo[], hooks?: ReadonlyMap<string, string>): Phase;
+/** The frame a CPU segment is charged to: the deepest component, else the deepest named app
+ *  function, else the deepest dependency, else the runtime bucket the leaf is in. */
+export declare function owner_of_stack(frames: FrameInfo[]): {
+  label: string;
+  file: string;
+  category: FrameCategory;
+  detail?: string;
+};
+/**
+ * Build the timeline. `frame_of` resolves a profile node to its frame facts, `parent_of` the
+ * tree; both come from `analyze`'s own tables so the timeline agrees with every other view.
+ */
+export declare function build_timeline(profile: CpuProfile, frame_of: (id: number) => FrameInfo, parent_of: (id: number) => number | undefined, input: TimelineInput): Timeline;
+/**
+ * THE CAUSALITY GRAPH: every call (net + I/O primitives, not spans) as a box on the render's
+ * clock, laid into lanes so overlapping calls sit on different rows, and an edge from a call to
+ * the one that started right after it finished while nothing else was in flight — that start
+ * waited for that end, and `at` is the line that did the waiting. Edges are what the
+ * "awaits in a row" callouts are made of; the graph shows them with the exact await site.
+ */
+export declare function await_graph(input: TimelineInput, w0: number, w1: number): {
+  nodes: AwaitNode[];
+  edges: AwaitEdge[];
+};
+/**
+ * Awaits in a row: consecutive single-call waits on DIFFERENT calls with little CPU between them —
+ * 5 ms, or 5% of the chain's longest wait when that is more. Read off the COALESCED view
+ * (`coalesce`), where a wait chopped by microtask slivers is one block again — on the raw segments
+ * the same call reappearing after a sliver broke every chain. `at` indexes that view (the same one
+ * the UI draws).
+ *
+ * (The allowance scales: between a 1 s timer and a 700 ms call, the CPU of the server answering the
+ * page's own call to itself, or a collection, ran 3 to 9 ms run by run — the fixed 5 ms broke the
+ * chain in some runs and not others, and a 2.2 s finding came and went between two profiles of the
+ * same code. Next to waits that long, tens of ms of CPU are still nothing between.)
+ */
+export declare function find_parallelizable(t: Timeline): ParallelGroup[];
+/**
+ * READABLE SEGMENTS: the sweep is exact but a render is hundreds of slivers — every card's CPU
+ * is its own owner, and a wait is chopped by every microtask that runs inside it. For the bar and
+ * the steps, fold anything below `min_ms` into its neighbours: a run of small pieces becomes ONE
+ * segment named after what dominated it (`mostly ProductCard (+11 more)`), and a wait interrupted
+ * by small CPU slices reads as one wait again. `parts` says how many raw segments a merged one
+ * holds; the raw list stays in `segments` for the tooltip's exact numbers.
+ */
+export interface ViewSegment extends Segment {
+  parts: number;
+  /** the raw pieces that were folded in, by label, largest first (for the tooltip) */
+  inside?: {
+    label: string;
+    kind: Segment["kind"];
+    ms: number;
+  }[];
+}
+export declare function coalesce(t: Timeline, min_ms?: number): ViewSegment[];
+/** A net call's timeline label: `GET host/path` (query dropped, long paths cut). */
+export declare function label_call(method: string, url: string): string;
+/** The steps worth listing: every coalesced segment at or above `min_pct` of the window, in time
+ *  order (`i` indexes the coalesced list). */
+export declare function chain_steps(t: Timeline, min_pct?: number, max?: number): {
+  i: number;
+  seg: ViewSegment;
+  ms: number;
+  pct: number;
+}[];