@fusion.dev/helix-diagnostics 0.138.0 → 0.140.0

package/dist/report.d.ts

@@ -109,6 +109,63 @@ export type Identified = Omit<Finding, 'decidedBy' | 'severity'>;
 export declare const CATEGORIES: readonly ['assist', 'configuration', 'coverage', 'findings', 'performance', 'runtime', 'usage'];
 /** A kind of telemetry. */
 export type Category = (typeof CATEGORIES)[number];
+/**
+ * What the components cost on a page, by tag, where a project asked for it.
+ */
+export interface PerformanceReport {
+    /**
+     * What this browser could measure. Layout shift and long tasks are
+     * Chromium's, so elsewhere their numbers are absent, never zero.
+     */
+    measured: {
+        layoutShift: boolean;
+        longTasks: boolean;
+    };
+    /** Each tag rendered on the page. */
+    tags: Record<string, {
+        /** How many long tasks, of 50 ms or more, one of its elements' first updates ran in. */
+        longTasks: number;
+        /**
+         * Its elements' first updates, in milliseconds: how many, the median,
+         * the 95th percentile, and the slowest. Each is the element's own
+         * update, from `willUpdate` to `updated`, so time spent waiting behind
+         * other elements is not counted.
+         */
+        render: {
+            count: number;
+            max: number;
+            p50: number;
+            p95: number;
+        };
+        /** The layout shift its elements moved, summed as the browser scores it. */
+        shift: number;
+    }>;
+}
+/**
+ * A runtime event as a run holds it: what `@fusion.dev/helix-core` reported
+ * as the library ran, such as a selectable table with no `row-key`, one entry
+ * per distinct event on the page.
+ */
+export interface RuntimeEntry {
+    /** How many times it was reported on this page. */
+    count: number;
+    /**
+     * Its identity across runs: the kind, the tag, and the sentence with its
+     * numbers left out, so a table drawing 3,000 rows and one drawing 3,200 are
+     * one event.
+     */
+    fingerprint: string;
+    /** What went wrong, as core names it, stable across versions. */
+    kind: string;
+    /** `error` for a failure, `warn` for a mistake in how the library is used. */
+    level: 'error' | 'warn';
+    /** The sentence core prints, which says what to do. */
+    message: string;
+    /** Whether core printed it as it happened; where it did not, the console sink does. */
+    printed: boolean;
+    /** The tag of the element it happened on, where there is one. */
+    tag?: string;
+}
 /** Where a run was declared to happen. Undeclared is never sent. */
 export type Environment = 'ci' | 'development' | 'production';
 /** A sheet the collector could not read, and the reason. */
@@ -188,8 +245,20 @@ export interface Configuration {
     console: {
         coverage: 'info' | 'off';
         findings: Severity | 'off';
+        /** What the components cost, by tag, which is measured where this is on. */
+        performance: 'info' | 'off';
+        /** The runtime events core left to diagnostics to print. */
+        runtime: 'warn' | 'off';
         usage: 'debug' | 'off';
     };
+    /** What `@fusion.dev/helix-core` does itself. */
+    core: {
+        /**
+         * Whether core prints each runtime warning as it happens. Off, diagnostics
+         * prints them in its own group, at the `console.runtime` level.
+         */
+        warnings: boolean;
+    };
     /** How much detail goes with what is sent. */
     detail: {
         evidence: 'full' | 'none' | 'selector';
@@ -204,6 +273,13 @@ export interface Configuration {
             sample: number;
         };
     };
+    /** Where `initDiagnostics()` hands each run, beside the console. */
+    sinks: {
+        /** The overlay on the page. */
+        overlay: boolean;
+        /** The relay, `helix diagnostics`: off, on at its own address, or at this one. */
+        relay: boolean | string;
+    };
     /** Each override in effect, from the file or the call. */
     overrides: Array<{
         kind: Kind;
@@ -235,6 +311,16 @@ export interface Report {
     configuration: Configuration;
     coverage: Coverage;
     findings: Finding[];
+    /**
+     * What the components cost, by tag. Present only where the project asked,
+     * with `console.performance` or `send.performance`.
+     */
+    performance?: PerformanceReport;
+    /**
+     * What the library reported going wrong as it ran on this page, from its
+     * first load: one entry per distinct event, counted.
+     */
+    runtime: RuntimeEntry[];
     /**
      * The project's own name and labels, as its configuration gives them. The
      * key is never written into a report.

package/dist/runtime.d.ts

@@ -0,0 +1,31 @@
+import type { RuntimeEntry } from './report.js';
+/** The key core reports each event to. */
+export declare const RUNTIME_SLOT: unique symbol;
+/** The key core keeps the events it reported under, the first two hundred. */
+export declare const RUNTIME_LOG: unique symbol;
+/**
+ * The kinds a finding already reports, which the console and the overlay leave
+ * out: two copies of Helix on a page is the `duplicate-registration` finding.
+ */
+export declare const AS_FINDINGS: ReadonlySet<string>;
+/** An event as core reports it, read without importing core. */
+export interface Heard {
+    detail?: unknown;
+    kind: string;
+    level?: 'error' | 'warn';
+    message: string;
+    tag?: string | undefined;
+}
+/** The events core has kept so far. */
+export declare const logged: () => Heard[];
+/** One entry per distinct event, counted as each is heard. */
+export interface Tally {
+    /** Counts one event; `printed` says whether core printed it. */
+    add(event: unknown, printed: boolean): void;
+    /** The entries so far. Copies: counting goes on after they are read. */
+    entries(): RuntimeEntry[];
+}
+/** Starts a count. */
+export declare const tally: () => Tally;
+/** The entries a reader is shown: those no finding reports already. */
+export declare const shownRuntime: (entries: readonly RuntimeEntry[]) => RuntimeEntry[];

package/dist/runtime.js

@@ -0,0 +1,39 @@
+import { runtimeFingerprint } from './identity.js';
+export const RUNTIME_SLOT = Symbol.for('fusion.dev/helix/runtime');
+export const RUNTIME_LOG = Symbol.for('fusion.dev/helix/runtime-log');
+export const AS_FINDINGS = new Set(['duplicate-registration']);
+const isHeard = (value) => typeof value === 'object' &&
+    value !== null &&
+    typeof value.kind === 'string' &&
+    typeof value.message === 'string';
+export const logged = () => {
+    const log = globalThis[RUNTIME_LOG];
+    return Array.isArray(log) ? log.filter(isHeard) : [];
+};
+export const tally = () => {
+    const entries = new Map();
+    return {
+        add(event, printed) {
+            if (!isHeard(event)) {
+                return;
+            }
+            const fingerprint = runtimeFingerprint(event.kind, event.tag, event.message);
+            const known = entries.get(fingerprint);
+            if (known) {
+                known.count += 1;
+                return;
+            }
+            entries.set(fingerprint, {
+                count: 1,
+                fingerprint,
+                kind: event.kind,
+                level: event.level === 'error' ? 'error' : 'warn',
+                message: event.message,
+                printed,
+                ...(event.tag === undefined ? {} : { tag: event.tag }),
+            });
+        },
+        entries: () => [...entries.values()].map((one) => ({ ...one })),
+    };
+};
+export const shownRuntime = (entries) => entries.filter((one) => !AS_FINDINGS.has(one.kind));

package/dist/schedule.d.ts

@@ -0,0 +1,57 @@
+/**
+ * When `initDiagnostics()` runs: debounced, idle, and bounded by its own cost.
+ *
+ * - **After a change**, once changes stop for `quiet` milliseconds, or after
+ *   `longest` milliseconds whatever keeps changing: a page that never stops,
+ *   such as a carousel adding slides, would otherwise never be judged.
+ * - **In an idle moment**, at most `idle` milliseconds later.
+ * - **Never sooner than `gap` after the last run, nor sooner than `factor`
+ *   times its duration**, so a slow page is judged less often.
+ * - **Never in a hidden tab**: a change there waits for the tab to be shown.
+ * - **Never when nothing changed** since the last run.
+ *
+ * The browser's hooks are passed in, so a spec drives it with small numbers
+ * and a pretend tab.
+ */
+/** How long each wait is, in milliseconds. */
+export interface Timing {
+    /** How long changes must stop for before a run. */
+    quiet: number;
+    /** The longest an idle callback may wait. */
+    idle: number;
+    /** The least time between the end of one run and the start of the next. */
+    gap: number;
+    /** The least time between runs, as a multiple of the last run's duration. */
+    factor: number;
+    /** The longest a change waits for the page to go quiet. */
+    longest: number;
+}
+/** The shipped timing. */
+export declare const TIMING: Timing;
+/** What the schedule asks of the browser. */
+export interface Browser {
+    /** Whether the tab is hidden now. */
+    hidden(): boolean;
+    /** Calls `then` once in an idle moment, at most `timeout` later; returns a cancel. */
+    idle(then: () => void, timeout: number): () => void;
+    /** The time now, in milliseconds. */
+    now(): number;
+    /** Calls `then` when the tab is next shown; returns a removal. */
+    shown(then: () => void): () => void;
+}
+/** The browser's own hooks, with a timer where a browser has no idle callback. */
+export declare const browser: () => Browser;
+/** A schedule: told of changes, it decides when `run` runs. */
+export interface Schedule {
+    /** Something changed: a run follows, as the schedule allows. */
+    poke(): void;
+    /** Ends it: nothing more runs. */
+    stop(): void;
+}
+/**
+ * A schedule for `run`, which returns how long it took in milliseconds.
+ *
+ * One run at a time, and a change during a run is a change after it: the run
+ * that follows sees it.
+ */
+export declare const schedule: (run: () => number, timing?: Timing, on?: Browser) => Schedule;

package/dist/schedule.js

@@ -0,0 +1,84 @@
+export const TIMING = { factor: 20, gap: 2000, idle: 3000, longest: 10000, quiet: 1000 };
+export const browser = () => ({
+    hidden: () => globalThis.document?.visibilityState === 'hidden',
+    idle: (then, timeout) => {
+        if (typeof globalThis.requestIdleCallback === 'function') {
+            const id = globalThis.requestIdleCallback(then, { timeout });
+            return () => globalThis.cancelIdleCallback(id);
+        }
+        const id = setTimeout(then, 1);
+        return () => clearTimeout(id);
+    },
+    now: () => globalThis.performance?.now() ?? Date.now(),
+    shown: (then) => {
+        const listener = () => {
+            if (globalThis.document?.visibilityState !== 'hidden') {
+                globalThis.document?.removeEventListener('visibilitychange', listener);
+                then();
+            }
+        };
+        globalThis.document?.addEventListener('visibilitychange', listener);
+        return () => globalThis.document?.removeEventListener('visibilitychange', listener);
+    },
+});
+export const schedule = (run, timing = TIMING, on = browser()) => {
+    let dirty = false;
+    let since = Number.POSITIVE_INFINITY;
+    let live = true;
+    let ended = Number.NEGATIVE_INFINITY;
+    let last = 0;
+    let cancel;
+    let quiet;
+    let wait;
+    const go = () => {
+        cancel = undefined;
+        if (!live || !dirty) {
+            return;
+        }
+        if (on.hidden()) {
+            cancel = on.shown(settle);
+            return;
+        }
+        const rest = Math.max(timing.gap, timing.factor * last) - (on.now() - ended);
+        if (rest > 0) {
+            wait = setTimeout(go, rest);
+            return;
+        }
+        cancel = on.idle(() => {
+            cancel = undefined;
+            if (!live || !dirty) {
+                return;
+            }
+            dirty = false;
+            since = Number.POSITIVE_INFINITY;
+            last = run();
+            ended = on.now();
+            if (dirty) {
+                settle();
+            }
+        }, timing.idle);
+    };
+    const settle = () => {
+        if (!live) {
+            return;
+        }
+        clearTimeout(quiet);
+        clearTimeout(wait);
+        cancel?.();
+        cancel = undefined;
+        quiet = setTimeout(go, Math.min(timing.quiet, Math.max(0, since + timing.longest - on.now())));
+    };
+    return {
+        poke: () => {
+            dirty = true;
+            since = Math.min(since, on.now());
+            settle();
+        },
+        stop: () => {
+            live = false;
+            clearTimeout(quiet);
+            clearTimeout(wait);
+            cancel?.();
+        },
+    };
+};

package/dist/usage.d.ts

@@ -1,6 +1,8 @@
 import type { Answered, Located } from './collect.js';
 import type { Published } from './manifest.js';
-import type { Usage } from './report.js';
+import { type Page } from './page.js';
+import type { PerformanceReport, RuntimeEntry, Usage } from './report.js';
+import { type Heard } from './runtime.js';
 /** The element counts, before the stylesheets add theirs. */
 type Counted = Pick<Usage, 'axes' | 'composed' | 'slots' | 'tags'>;
 /**
@@ -10,7 +12,7 @@ type Counted = Pick<Usage, 'axes' | 'composed' | 'slots' | 'tags'>;
  */
 export declare const loadedVersions: () => string[];
 /** The elements in the page now, counted once each. */
-export declare const walk: (from: Document) => Counted;
+export declare const walk: (from: Document, page?: Page) => Counted;
 /**
  * The counts for the tags a manifest lists, and the rest apart as `unlisted`.
  *
@@ -22,7 +24,15 @@ export declare const listed: (counted: Counted, tags: Map<string, Published>) =>
 export interface Watcher {
     /** The counts so far. A copy: counting goes on after it is read. */
     counts(): Counted;
-    /** Stops counting, and gives the slot back to whatever held it before. */
+    /** What the components cost so far, where the watcher was asked to measure. */
+    performance(): PerformanceReport | undefined;
+    /**
+     * The runtime events reported on this page from its first load, one entry
+     * per distinct event: the ones core kept from before the watcher started,
+     * and the ones heard since.
+     */
+    runtime(): RuntimeEntry[];
+    /** Stops counting, and gives the slots back to whatever held them before. */
     stop(): void;
 }
 /**
@@ -40,7 +50,27 @@ export interface Watcher {
  * Two watchers on one page both count: a second one keeps the first's
  * listener and calls it too.
  */
-export declare const watch: (from?: Document) => Watcher;
+export declare const watch: (from?: Document, { onRender, onRuntime, performance, quiet, }?: {
+    /**
+     * Called as each Helix element renders for the first time, after it is
+     * counted: how `initDiagnostics()` hears that the page changed when an
+     * element upgrades without adding anything to the DOM.
+     */
+    onRender?: ((element: Element) => void) | undefined;
+    /** Called with each runtime event core reports, after it is counted. */
+    onRuntime?: ((event: Heard) => void) | undefined;
+    /**
+     * Whether to measure what the components cost, from now on: each
+     * element's first update, and the layout shift and long tasks the browser
+     * reports.
+     */
+    performance?: boolean | undefined;
+    /**
+     * Whether core should leave each runtime event for diagnostics to print,
+     * asked as each arrives: `core.warnings: false`.
+     */
+    quiet?: (() => boolean) | undefined;
+}) => Watcher;
 /**
  * The parts and hooks a page's stylesheets reach for, where the manifest or
  * the element's own styles say they exist. A dead one is a finding and is not

package/dist/usage.js

@@ -1,4 +1,7 @@
 import { parts, targets } from './analyze.js';
+import { OVERLAY, pageOf } from './page.js';
+import { measure } from './performance.js';
+import { logged, RUNTIME_SLOT, tally as tallyRuntime } from './runtime.js';
 const SLOT = Symbol.for('fusion.dev/helix/usage');
 const AXES = ['emphasis', 'material', 'separation', 'tone'];
 const bump = (into, key, by = 1) => {
@@ -19,7 +22,7 @@ export const loadedVersions = () => {
 };
 const tally = (counted, element) => {
     const tag = element.localName;
-    if (!tag.startsWith('helix-')) {
+    if (!tag.startsWith('helix-') || tag === OVERLAY) {
         return;
     }
     const root = element.getRootNode();
@@ -42,20 +45,11 @@ const tally = (counted, element) => {
         }
     }
 };
-const everyElement = (from, visit, depth = 0) => {
-    if (depth > 32) {
-        return;
-    }
-    for (const element of from.querySelectorAll('*')) {
-        visit(element);
-        if (element.shadowRoot) {
-            everyElement(element.shadowRoot, visit, depth + 1);
-        }
-    }
-};
-export const walk = (from) => {
+export const walk = (from, page = pageOf(from)) => {
     const counted = empty();
-    everyElement(from, (element) => tally(counted, element));
+    for (const element of page.elements) {
+        tally(counted, element);
+    }
     return counted;
 };
 export const listed = (counted, tags) => {
@@ -76,7 +70,7 @@ export const listed = (counted, tags) => {
         unlisted,
     };
 };
-export const watch = (from = document) => {
+export const watch = (from = document, { onRender, onRuntime, performance, quiet, } = {}) => {
     const counted = empty();
     const seen = new WeakSet();
     const see = (element) => {
@@ -91,20 +85,48 @@ export const watch = (from = document) => {
     const listener = (element) => {
         if (live) {
             see(element);
+            onRender?.(element);
         }
         if (typeof before === 'function') {
             before(element);
         }
     };
     store[SLOT] = listener;
-    everyElement(from, see);
+    for (const element of pageOf(from).elements) {
+        see(element);
+    }
+    const heard = tallyRuntime();
+    for (const event of logged()) {
+        heard.add(event, true);
+    }
+    const beforeRuntime = store[RUNTIME_SLOT];
+    const hear = (event) => {
+        let silent = false;
+        if (live) {
+            silent = quiet?.() === true;
+            heard.add(event, !silent);
+            onRuntime?.(event);
+        }
+        if (typeof beforeRuntime === 'function' && beforeRuntime(event) === true) {
+            silent = true;
+        }
+        return silent;
+    };
+    store[RUNTIME_SLOT] = hear;
+    const measured = performance ? measure() : undefined;
     return {
         counts: () => structuredClone(counted),
+        performance: () => measured?.results(),
+        runtime: () => heard.entries(),
         stop: () => {
             live = false;
+            measured?.stop();
             if (store[SLOT] === listener) {
                 store[SLOT] = before;
             }
+            if (store[RUNTIME_SLOT] === hear) {
+                store[RUNTIME_SLOT] = beforeRuntime;
+            }
         },
     };
 };

package/dist/version.d.ts

@@ -6,4 +6,4 @@
  * release, so the two never disagree; a spec beside this holds them to it.
  * Nothing else in the running code knows which release it is.
  */
-export declare const VERSION = "0.138.0";
+export declare const VERSION = "0.140.0";

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = '0.138.0';
+export const VERSION = '0.140.0';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix-diagnostics",
   "description": "Finds the Helix mistakes that are valid CSS: dead parts, misnamed hooks, two copies of the library.",
-  "version": "0.138.0",
+  "version": "0.140.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -33,7 +33,7 @@
   },
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "devDependencies": {
-    "@fusion.dev/helix-testing": "0.138.0",
+    "@fusion.dev/helix-testing": "0.140.0",
     "@types/bun": "^1.3.0"
   },
   "homepage": "https://fusion.dev",