@ogygia/core 0.0.0 → 0.11.0

package/dist/insights/session-data.d.ts

@@ -0,0 +1,108 @@
+import { DevtoolsEvent } from "../events/schema.js";
+export interface SessionInteraction {
+  t: number;
+  name: string;
+  duration: number;
+  input_delay: number;
+  processing: number;
+  presentation: number;
+  id: number;
+  target: string;
+  fp: string | null;
+  el: WeakRef<Element> | null;
+}
+export interface SessionClick {
+  t: number;
+  target: string;
+  fp: string | null;
+  el: WeakRef<Element> | null;
+  /** it looked like it does something (a control, a link, a clickable role, a pointer cursor): a
+   *  click on text or a blank stretch that changes nothing is no dead click */
+  clickable?: true;
+}
+export interface SessionShift {
+  t: number;
+  value: number;
+  input: boolean;
+  fp: string | null;
+  el: WeakRef<Element> | null;
+}
+export interface SessionRequest {
+  url: string;
+  type: string;
+  t: number;
+  ms: number;
+  bytes: number;
+  status: number | null;
+  /** the server's own account (`Server-Timing`: ogygia's profiler sends ssr / cpu / net / up1-3) */
+  server?: {
+    name: string;
+    ms: number;
+    desc: string;
+  }[];
+}
+export interface SessionFrame {
+  t: number;
+  ms: number;
+  blocking: number;
+  scripts: {
+    source: string;
+    fn: string;
+    invoker: string;
+    ms: number;
+  }[];
+}
+/** A navigation as it started: where to, when, and the element that started it (the link or form, or
+ *  the input being handled then) with its island. */
+export interface SessionNav {
+  url: string;
+  t: number;
+  type: string;
+  source: string | null;
+  fp: string | null;
+}
+export interface SessionData {
+  from: number;
+  to: number;
+  interactions: SessionInteraction[];
+  longtasks: {
+    t: number;
+    ms: number;
+  }[];
+  frames: SessionFrame[];
+  shifts: SessionShift[];
+  requests: SessionRequest[];
+  mutations: {
+    fp: string | null;
+    count: number;
+    el: WeakRef<Element> | null;
+  }[];
+  /** when the DOM changed, and where (one stamp per island per batch of changes) */
+  mut_log: {
+    t: number;
+    fp: string | null;
+  }[];
+  /** every click, fast ones too */
+  clicks: SessionClick[];
+  errors: {
+    t: number;
+    message: string;
+  }[];
+  /** navigations as they started, with what started them (absent in a part saved before this field) */
+  navs?: SessionNav[];
+  heap: {
+    from: number;
+    to: number;
+  } | null;
+  events: DevtoolsEvent[];
+  cpu: unknown | null;
+  cpu_off: string | null;
+  page: string;
+  /** the documents the session crossed (a full page load mid-session), each with when it began */
+  pages: {
+    url: string;
+    t: number;
+  }[];
+  /** island fingerprint → component name, taken on each page (its islands are gone after it) */
+  names: Record<string, string>;
+}

package/dist/insights/session-insights.d.ts

@@ -0,0 +1,121 @@
+import { CpuSummary } from "./cpu.js";
+import { SessionData } from "./session-data.js";
+export type Ref = {
+  kind: "interaction";
+  i: number;
+} | {
+  kind: "click";
+  i: number;
+} | {
+  kind: "shift";
+  i: number;
+} | {
+  kind: "island";
+  fp: string;
+};
+export interface SessionFinding {
+  code: string;
+  severity: "error" | "warn" | "info";
+  message: string;
+  fix?: string;
+  refs: Ref[];
+  /** a same-origin GET the tab can profile on the server in one click (server-time findings) */
+  url?: string;
+}
+/** One island's part of the session: what was done to it, and what it asked the server. */
+export interface IslandSession {
+  clicks: number;
+  /** its interactions over 100 ms */
+  slow: {
+    target: string;
+    duration: number;
+    processing: number;
+  }[];
+  /** requests that started within 3 s after a click on it, with the server's split */
+  requests: {
+    url: string;
+    ms: number;
+    server_ms: number | null;
+    net_ms: number | null;
+    up: string | null;
+    status: number | null;
+  }[];
+  mutations: number;
+}
+/** One item on the session's one-clock timeline (ms from the session start). */
+export interface TimelineItem {
+  t0: number;
+  t1: number;
+  label: string;
+  tone: "ok" | "warn" | "bad" | "info";
+  /** a request: the server's part and, inside it, the upstream wait (ms) */
+  server?: {
+    ms: number;
+    up: number;
+  };
+  ref?: Ref;
+}
+export interface TimelineLane {
+  key: "input" | "main" | "net" | "islands" | "layout" | "errors";
+  label: string;
+  items: TimelineItem[];
+}
+/** The session on one clock, lane by lane (the Record tab draws it). Capped per lane. */
+export declare function session_timeline(s: SessionData, names: (fp: string) => string): TimelineLane[];
+export interface SessionReport {
+  duration_ms: number;
+  /** `shifts` and `cls`: the layout moving with no input (the shifts the session's CLS counts) */
+  counts: {
+    interactions: number;
+    slow: number;
+    longtasks: number;
+    longtask_ms: number;
+    requests: number;
+    request_bytes: number;
+    errors: number;
+    shifts: number;
+    cls: number;
+    mutations: number;
+    pages: number;
+  };
+  findings: SessionFinding[];
+  /** the slowest interactions, for the timeline */
+  interactions: {
+    i: number;
+    t: number;
+    name: string;
+    duration: number;
+    target: string;
+    fp: string | null;
+  }[];
+  /** each island's part: clicks, slow interactions, the requests its clicks caused (server split) */
+  by_island: Record<string, IslandSession>;
+  /** the slowest requests, with the server's own split when it sent one */
+  requests: {
+    url: string;
+    ms: number;
+    status: number | null;
+    server_ms: number | null;
+    cpu_ms: number | null;
+    net_ms: number | null;
+    up: string | null;
+  }[];
+  /** every request that answered an error status (`type`: the browser's initiator type) */
+  failed: {
+    url: string;
+    status: number;
+    type: string;
+    t: number;
+  }[];
+  /** the slowest interaction on each element the session touched, however quick (0: a click the
+   *  browser did not time, under its 16 ms floor) */
+  by_element: {
+    target: string;
+    duration: number;
+    processing: number;
+    t: number;
+    fp: string | null;
+  }[];
+  cpu: CpuSummary | null;
+}
+export declare function analyze_session(s: SessionData, names: (fp: string) => string, page_url: string): SessionReport;