@lensmcp/protocol-types 1.25.6 → 1.25.7

package/index.d.ts

@@ -20,3 +20,4 @@ export * from './lib/http-exchange.js';
 export * from './lib/pod-memory.js';
 export * from './lib/perf-rules.js';
 export * from './lib/sources.js';
+export * from './lib/page-visit.js';

package/index.js

@@ -1 +1 @@
-"use strict";export*from"./lib/schema-version.js";export*from"./lib/source-location.js";export*from"./lib/context.js";export*from"./lib/event.js";export*from"./lib/node.js";export*from"./lib/edge.js";export*from"./lib/attributes.js";export*from"./lib/producer-health.js";export*from"./lib/resources.js";export*from"./lib/tokens.js";export*from"./lib/capture-demand.js";export*from"./lib/bounded-clone.js";export*from"./lib/bounded-map.js";export*from"./lib/flood-guard.js";export*from"./lib/dashboard.js";export*from"./lib/log-query.js";export*from"./lib/error-dismissal.js";export*from"./lib/ai-content.js";export*from"./lib/http-exchange.js";export*from"./lib/pod-memory.js";export*from"./lib/perf-rules.js";export*from"./lib/sources.js";
+"use strict";export*from"./lib/schema-version.js";export*from"./lib/source-location.js";export*from"./lib/context.js";export*from"./lib/event.js";export*from"./lib/node.js";export*from"./lib/edge.js";export*from"./lib/attributes.js";export*from"./lib/producer-health.js";export*from"./lib/resources.js";export*from"./lib/tokens.js";export*from"./lib/capture-demand.js";export*from"./lib/bounded-clone.js";export*from"./lib/bounded-map.js";export*from"./lib/flood-guard.js";export*from"./lib/dashboard.js";export*from"./lib/log-query.js";export*from"./lib/error-dismissal.js";export*from"./lib/ai-content.js";export*from"./lib/http-exchange.js";export*from"./lib/pod-memory.js";export*from"./lib/perf-rules.js";export*from"./lib/sources.js";export*from"./lib/page-visit.js";

package/lib/dashboard.d.ts

@@ -11,6 +11,7 @@
  * on-demand GETs.
  */
 import type { HttpExchange } from './http-exchange.js';
+import type { PageVisitNavType, PageVisitRaw, PageVisitReadyBy, PageVisitRequest, PageVisitVitals } from './page-visit.js';
 /** Bumped only on a breaking change to the stream framing itself. */
 export declare const DASHBOARD_PROTOCOL = 1;
 /** The swimlane a flow event belongs to (mirrors `FlowArea` in `@lensmcp/core`'s flow-shape). */
@@ -521,6 +522,14 @@ export interface DashFlowDetail {
     segmentStats?: DashSegmentStats;
     /** Present when the read asked for one segment (`?segment=`): `events` then holds only that segment. */
     focus?: DashFlowSegment;
+    /**
+     * Present when the read asked for a time window (`?from=&to=`, epoch ms — a page visit's start and ready): `events`
+     * then holds only the flow's steps inside it, while `segments`/`phases` still describe the whole flow.
+     */
+    window?: {
+        from?: number;
+        to?: number;
+    };
     /**
      * Present when the flow was no longer in the live window and was read back — from the workspace's event history
      * (30 days) or the bus files. `complete: false`: older events of it may be missing.
@@ -872,12 +881,33 @@ export interface DashSummary {
  * `err:<what>` something that threw.
  */
 export type DashTouches = Record<string, number>;
+/**
+ * A run's SQL by its service's own count (node-instrumentation's `db-request-account`): every statement it ran and what
+ * they took, and how many of their events reached the lens. Each statement shape's flood bucket lets only some events
+ * through, so a run's `touches` and `sqlMs` can count a fraction of what it ran — this is the whole of it.
+ */
+export interface DashSqlAccount {
+    statements: number;
+    ms: number;
+    /** Statements whose event reached the lens — what `touches` counts (and session statements, BEGIN and the like). */
+    seen: number;
+    failed?: number;
+    /**
+     * Folded by time, not by the run's own id: a service on a tap from before `runId` that sent several calls under one
+     * request id at once can have had the accounts of two such calls swapped. Their sum is right.
+     */
+    byTime?: true;
+}
 export interface DashRouteRun {
     at: number;
     flowId?: string;
     requestId?: string;
     status?: number;
     durationMs?: number;
+    /** What its SQL statements took, summed (ms) — the statements its `sql:` touches count. */
+    sqlMs?: number;
+    /** Its SQL by its service's own count, when the service sent one — the whole of it, where `touches` may hold a part. */
+    sqlAccount?: DashSqlAccount;
     /** Who called it: another service by name, else `client`. */
     caller?: string;
     touches: DashTouches;
@@ -1091,6 +1121,201 @@ export interface DashRoutesCatalog {
     /** How far back the kept history reaches. */
     since?: number;
 }
+/** p50 / p95 over a page's kept samples, and how many it has. */
+export interface DashPageStat {
+    p50: number;
+    p95: number;
+    n: number;
+}
+/** One request of a visit, as the browser saw it, joined to the backend's run of it when that was seen. */
+export interface DashPageRequest extends PageVisitRequest {
+    /** The route that answered it (`<service> METHOD /route`, an id of catalog://routes). */
+    routeId?: string;
+    service?: string;
+    /** The server's own status and time. */
+    status?: number;
+    serverMs?: number;
+    /**
+     * SQL statements, and what they took, over its run and the cluster calls it waited on — by the services' own count
+     * where they sent one (`DashRouteRun.sqlAccount`), else what reached the lens.
+     */
+    sql?: number;
+    sqlMs?: number;
+    /** Of `sql`, how many statements' events reached the lens — only where that is fewer. */
+    sqlSeen?: number;
+    /** Key-value commands and calls outside the cluster, over the same runs. */
+    cache?: number;
+    ext?: number;
+    /** Other services' runs under its request id, inside its own run (east-west): how many, and by route (at most 10 routes). */
+    callCount?: number;
+    calls?: Array<{
+        routeId: string;
+        n: number;
+    }>;
+    /** Same method, path and query hash as an earlier request of the visit. */
+    dup?: true;
+}
+/** One visit of a page, in a few hundred bytes — the requests in full only on the newest two and the slowest. */
+export interface DashPageVisit {
+    visitId: string;
+    tabId?: string;
+    /** The pathname it opened. */
+    path: string;
+    nav: 'hard' | 'spa';
+    navType?: PageVisitNavType;
+    cause?: 'hmr';
+    redirectedFrom?: string;
+    /** The page the tab showed before (an SPA navigation): its pattern, or its path when it had none. */
+    from?: string;
+    startAt: number;
+    readyAt?: number;
+    readyBy?: PageVisitReadyBy;
+    readyMs?: number;
+    appReadyMs?: number;
+    endAt?: number;
+    flowIds: string[];
+    /** Requests it made until ready, with those past the 60 the browser lists. */
+    requests: number;
+    /** Of the listed ones, how many were joined to their backend run. */
+    joined: number;
+    /** Requests whose run has not been seen yet — joined as it arrives, given up two minutes after the visit. */
+    waiting?: number;
+    /** The same request made again in the visit (method, path and query hash). */
+    duplicates: number;
+    /** Over its joined requests (`DashPageRequest.sql`). */
+    sql: number;
+    sqlMs: number;
+    /** Of `sql`, how many statements' events reached the lens — only where that is fewer. */
+    sqlSeen?: number;
+    /** The joined requests by the service that answered them. */
+    services?: Record<string, number>;
+    commits: number;
+    renders: number;
+    renderMs: number;
+    maxCommitMs: number;
+    stormCommits: number;
+    suspenseWaits: number;
+    updates: number;
+    errors: number;
+    firstError?: string;
+    /** A request answered 5xx, the page threw, or it was never ready (`timeout`). */
+    failed?: true;
+    afterReady?: PageVisitRaw['afterReady'];
+    vitals?: PageVisitVitals;
+    longTasks?: PageVisitRaw['longTasks'];
+    heapMb?: number;
+    chunks?: PageVisitRaw['chunks'];
+    /** Its requests in full — kept for the newest two visits and the slowest. */
+    requestList?: DashPageRequest[];
+}
+/** A request the page makes, over its kept visits: `METHOD /path` with ids folded. */
+export interface DashPageUse {
+    template: string;
+    method: string;
+    path: string;
+    host?: string;
+    /** The backend route that answers it, once a run of it was joined. */
+    routeId?: string;
+    /** In how many visits, and how often per visit that made it. */
+    inVisits: number;
+    perVisit: number;
+    /** The browser's time to its response headers. */
+    p50?: number;
+    /** Calls that answered 4xx/5xx or failed on the network. */
+    failed: number;
+    /** Calls that repeated an earlier one of their visit (same method, path and query hash). */
+    duplicates: number;
+    /** SQL statements per joined call, on average. */
+    sqlPerCall?: number;
+    /** Made by the latest visit. */
+    latest: boolean;
+}
+export type DashPageChangeKind = 'new-request' | 'gone-request' | 'status' | 'failed' | 'count' | 'sql' | 'duration';
+export interface DashPageChange {
+    kind: DashPageChangeKind;
+    /** The request template it is about, when it is about one. */
+    key?: string;
+    /** One line: "now requests GET /api/orders/:id", "GET /api/x ×1 → ×3", "SQL 12 → 31 statements", "ready 420 ms → 1,310 ms". */
+    text: string;
+}
+export interface DashPageSummary {
+    /** `<app> <pattern>`. */
+    id: string;
+    /** Its newest finished page review — none until the `page` review exists (planning/pages S6). */
+    review?: DashReviewMark;
+    /** The app the Vite plugin serves (or the page's host). */
+    app: string;
+    /** The router's full match pattern. */
+    pattern: string;
+    firstSeenAt: number;
+    lastSeenAt: number;
+    visits: number;
+    hard: number;
+    spa: number;
+    /** Hard loads the dev server's hot reload caused: listed, kept out of every sample. */
+    hmr: number;
+    errors: number;
+    failedVisits: number;
+    /** Ready per population: SPA visits from the navigation (`readyMs`), hard loads from the app's entry (`appReadyMs`). */
+    ready: {
+        spa?: DashPageStat;
+        hard?: DashPageStat;
+    };
+    /** Per visit: requests, SQL statements and ms, renders and render ms, store updates. */
+    perVisit: Partial<Record<'requests' | 'sql' | 'sqlMs' | 'renders' | 'renderMs' | 'updates', DashPageStat>>;
+    /** The latest visit — not a hot reload, unless the page has nothing else — without its request list. */
+    last?: DashPageVisit;
+    /** Where its SPA visits came from (the tab's page before), most often first; at most 3. */
+    from: Array<{
+        page: string;
+        n: number;
+    }>;
+    /** The latest visit against the one before — hot reloads left out. */
+    changes: DashPageChange[];
+}
+export interface DashPageDetail extends DashPageSummary {
+    /** Newest first, at most 20; the newest two carry `requestList`. */
+    recent: DashPageVisit[];
+    /** The slowest visit kept (by its population's ready), with its requests. */
+    slowest?: DashPageVisit;
+    /** What it requests, most visits first; at most 50. */
+    uses: DashPageUse[];
+    /** The most-rendered components, over the visits that reported them; at most 20. */
+    components: Array<{
+        name: string;
+        n: number;
+        ms: number;
+        inVisits: number;
+    }>;
+    /** The most-updated store paths; at most 20. */
+    store: Array<{
+        store: string;
+        path: string;
+        n: number;
+        inVisits: number;
+    }>;
+    /** Real paths that took this pattern, newest first; at most 10. */
+    paths: string[];
+}
+/** Visits with no router pattern, by app and templated path: not pages (planning/hub decision 9). */
+export interface DashPageUnmatched {
+    app: string;
+    path: string;
+    visits: number;
+    lastSeenAt: number;
+}
+export interface DashPagesCatalog {
+    at: number;
+    /** Most recently seen first. */
+    pages: DashPageSummary[];
+    /** At most 50 paths; `visits` sums them. */
+    unmatched: {
+        visits: number;
+        paths: DashPageUnmatched[];
+    };
+    /** How far back the kept visits reach. */
+    since?: number;
+}
 /** What one AI model was asked through an endpoint, and what it cost in tokens. */
 export interface DashAiUse {
     model: string;
@@ -1478,9 +1703,50 @@ export interface DashDbSchema {
         rows: DashDbStatementStat[];
     };
     findings: DashDbFinding[];
+    /** What the findings judged — and what a size floor left out, so «no finding» is not read as «nothing there». */
+    checked?: DashDbChecked;
     /** A read that failed, in Postgres's words. */
     error?: string;
 }
+/** One database's last read by LensMCP's own checks (`db.schema`), as `db://analysis` names it beside the analyzer's runs. */
+export interface DashDbChecksSeen {
+    store: string;
+    database: string;
+    at: number;
+    findings: number;
+    byKind: Partial<Record<DashDbFinding['kind'], number>>;
+    /** {@link DashDbChecked.note}: what the checks judged. */
+    judged?: string;
+}
+/**
+ * What LensMCP's own checks of a database judged (foodguard-83). The table checks (seq-scan, dead-rows,
+ * unindexed-foreign-key) judge only tables of `floorRows` rows or more — on a development database that is often none.
+ */
+export interface DashDbChecked {
+    tables: number;
+    /** Tables at or over the floor: the ones the table checks judged. */
+    judged: number;
+    floorRows: number;
+    /** Under the floor, the most sequentially scanned — not judged, named so the floor hides nothing. */
+    belowFloor: Array<{
+        table: string;
+        rows: number;
+        seqScans: number;
+    }>;
+    indexes: number;
+    /**
+     * Foreign keys no valid index leads with; of those, the ones the check judged (a big child, a parent with deletes),
+     * and the ones under the floor whose referenced table has deletes — a cost once the child grows.
+     */
+    foreignKeys?: {
+        total: number;
+        unindexed: number;
+        judged: number;
+        atScale: number;
+    };
+    /** The above in a sentence. */
+    note: string;
+}
 export interface DashDbTableInfo {
     schema: string;
     name: string;
@@ -1512,6 +1778,8 @@ export interface DashDbIndex {
     valid: boolean;
     /** Part of a partitioned table's index (or that index itself): changed on the parent, never on its own. */
     partition?: boolean;
+    /** The primary key, unique or exclusion constraint it backs — dropping it drops the constraint. */
+    constraint?: string;
     scans: number;
     rowsRead: number;
     bytes: number;
@@ -1747,7 +2015,7 @@ export interface DashDbStatementStat {
     hitRatio?: number;
 }
 export interface DashDbFinding {
-    kind: 'unused-index' | 'duplicate-index' | 'invalid-index' | 'seq-scan' | 'dead-rows';
+    kind: 'unused-index' | 'duplicate-index' | 'invalid-index' | 'seq-scan' | 'dead-rows' | 'unindexed-foreign-key';
     severity: 'high' | 'medium' | 'low';
     table: string;
     index?: string;
@@ -1755,6 +2023,25 @@ export interface DashDbFinding {
     detail: string;
     /** The statement that would fix it — shown to copy, never run by the lens. */
     fix?: string;
+    /** An index finding: the index's own scans and size. */
+    scans?: number;
+    bytes?: number;
+    /** duplicate-index: the index that stays, and why it is enough (`backs <constraint>`, `unique`, `wider`, `the same`). */
+    kept?: {
+        index: string;
+        why: string;
+        scans: number;
+        bytes: number;
+    };
+    /** The table's inserts + updates since Postgres began counting — each index costs a write on every one. */
+    writes?: number;
+    /** unindexed-foreign-key: the constraint, and the table it references. */
+    foreignKey?: {
+        name: string;
+        columns: string[];
+        references: string;
+        onDelete: string;
+    };
 }
 /** One Redis command by its shape: the command and its key with ids folded (`GET session:*`); a script by its hash. */
 export interface DashKvCommandShape {
@@ -2158,7 +2445,7 @@ export interface DashAiRun {
      * (`files`); `external`: the external APIs the services call (`external`); `log`: one log line (its `seq`).
      */
     target: {
-        kind: 'sql' | 'route' | 'error' | 'flow' | 'ui' | 'kv' | 'queue' | 'db' | 'dbtable' | 'kvstore' | 'queuestore' | 'files' | 'external' | 'log';
+        kind: 'sql' | 'route' | 'error' | 'flow' | 'ui' | 'kv' | 'queue' | 'db' | 'dbtable' | 'kvstore' | 'queuestore' | 'files' | 'external' | 'log' | 'page';
         id: string;
         label: string;
         name?: string;

package/lib/page-visit.d.ts

@@ -0,0 +1,136 @@
+/**
+ * A page visit, as the browser measures it (planning/pages/00-plan.md §2): from navigation start (a hard load) or a
+ * pathname change (an SPA navigation) to "ready" — the first commit after the page's own requests settle — and on to
+ * its end (the next visit, `pagehide`, or a minute after ready). A visit is not a flow: it records the flows its work
+ * ran under. The tab sends one event when the visit is ready (`phase: 'ready'`) and one when it ends (`phase: 'end'`);
+ * the lens joins its requests to the backend's routes and SQL by request id and folds it into the page catalog.
+ *
+ * Field names stay clear of the redactor's secret words (key, code, session, token …): it would blank their values.
+ * No query string is ever sent — a request names its pathname and a hash of its query.
+ */
+export declare const PAGE_VISIT_KIND: "page-visit";
+/** How the visit began. A hard load: the navigation's type; an SPA navigation: the history call. */
+export type PageVisitNavType = 'navigate' | 'reload' | 'back_forward' | 'push' | 'replace' | 'pop';
+/**
+ * How ready was decided: `settled` — the first commit after the page's requests settled, with none started within the
+ * quiet window; `no-requests` — it made none (the first commit that held); `no-commit` — the requests settled and
+ * nothing committed within a second after (the last commit before); `timeout` — not ready within the cap (its open
+ * requests are named); `left` — the next visit began first.
+ */
+export type PageVisitReadyBy = 'settled' | 'no-requests' | 'no-commit' | 'timeout' | 'left';
+/** One request the page made during the visit (every `fetch`, with or without a flow). */
+export interface PageVisitRequest {
+    /** The request id the lens's fetch hook stamped (`x-request-id`): what the backend's server-request carries. */
+    rid: string;
+    /** Method. */
+    m: string;
+    /** Host + pathname (no query): `api.foodguard.localhost/registry/v1/business-profile/situation-state`. */
+    p: string;
+    /** A short hash of the query string, so two calls with different queries tell apart — never the query. */
+    qh?: string;
+    /** When it started, in ms after the visit's start. */
+    s: number;
+    /** Ms until its response headers (a streamed body does not count); absent while still open. */
+    d?: number;
+    /** HTTP status; 0 for a network failure. */
+    st?: number;
+    /** The flow the request ran under, if one was open. */
+    flowId?: string;
+    /** Started after ready (polling, a lazy panel). */
+    late?: true;
+}
+export interface PageVisitRenders {
+    commits: number;
+    /** Components rendered, summed over the commits. */
+    renders: number;
+    /** React's own render time (actualDuration), summed. */
+    renderMs: number;
+    maxCommitMs: number;
+    /** Commits that rendered more than the storm threshold. */
+    stormCommits: number;
+    mounts: number;
+    /** Commits that showed a Suspense fallback (a lazy chunk or data still loading). */
+    suspenseWaits: number;
+    /** The most-rendered components, by renders: name, renders, ms. At most 8. */
+    top: Array<{
+        name: string;
+        n: number;
+        ms: number;
+    }>;
+}
+export interface PageVisitStore {
+    updates: number;
+    /** The most-updated store paths. At most 8. */
+    top: Array<{
+        store: string;
+        path: string;
+        n: number;
+    }>;
+}
+/** The browser's own timings of a hard load (Web Vitals and friends) — on a Vite dev server, not a production build. */
+export interface PageVisitVitals {
+    ttfb?: number;
+    fcp?: number;
+    lcp?: number;
+    cls?: number;
+    inp?: number;
+    dcl?: number;
+    load?: number;
+}
+export interface PageVisitRaw {
+    kind: typeof PAGE_VISIT_KIND;
+    phase: 'ready' | 'end';
+    visitId: string;
+    /** The browser tab (the client runtime's id), so a tab's visits read in order. */
+    tabId?: string;
+    /** The app the Vite plugin serves (its project name), or the page's host. */
+    app: string;
+    /** The router's full match pattern (`/companies/:id/onboarding/chat`) — absent when no router pattern is known. */
+    pattern?: string;
+    /** The pathname the visit opened (≤ 200 characters, no query). */
+    path: string;
+    nav: 'hard' | 'spa';
+    navType?: PageVisitNavType;
+    /** A hard load the dev server's hot reload caused. */
+    cause?: 'hmr';
+    /** The pathname a `replace` before ready came from (a redirect): the visit went on. */
+    redirectedFrom?: string;
+    /** Epoch ms: navigation start (hard) or the history call (SPA). */
+    startAt: number;
+    readyAt?: number;
+    readyBy?: PageVisitReadyBy;
+    /** Ms from start to ready. */
+    readyMs?: number;
+    /** A hard load: ms from the app's entry module to ready — what the app took, without the dev server serving it. */
+    appReadyMs?: number;
+    endAt?: number;
+    /** The flows the visit's work ran under. */
+    flowIds: string[];
+    /** Up to 60 requests; the rest counted. */
+    requests: PageVisitRequest[];
+    requestsDropped?: number;
+    renders: PageVisitRenders;
+    store: PageVisitStore;
+    errors: {
+        n: number;
+        first?: string;
+    };
+    /** From ready to the end (the `end` event only). */
+    afterReady?: {
+        requests: number;
+        templates: string[];
+        renders: number;
+        updates: number;
+    };
+    vitals?: PageVisitVitals;
+    longTasks?: {
+        n: number;
+        totalMs: number;
+        maxMs: number;
+    };
+    heapMb?: number;
+    chunks?: {
+        n: number;
+        kb: number;
+    };
+}

package/lib/page-visit.js

@@ -0,0 +1 @@
+"use strict";export const PAGE_VISIT_KIND="page-visit";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lensmcp/protocol-types",
-  "version": "1.25.6",
+  "version": "1.25.7",
   "type": "module",
   "main": "./index.js",
   "module": "./index.js",