@fusion.dev/helix-diagnostics 0.139.0 → 0.140.0

package/README.md

@@ -49,6 +49,13 @@ so React's strict mode and hot module replacement start nothing twice.
   counts them and opens a list of each finding with its evidence. Hover over a
   finding, or focus it, to outline the element it is about. The badge shows
   only while the page has findings.
+- **Hears what the library reports as it runs**, such as a selectable table
+  with no `row-key`, and lists each event in the run, the badge, and the relay.
+  Core still prints each one as it happens, with the stack it happened in. Set
+  `core: { warnings: false }` to have diagnostics print them in its group
+  instead.
+- **Measures what the components cost, where you ask**: each tag's first
+  updates, layout shift, and long tasks. See [Performance](#performance).
 - **Hands each run to your app**: the `onReport` option, `subscribe()` on the
   handle it returns, and a `helix-diagnostics` event on `document`.
 
@@ -72,7 +79,7 @@ throws stops neither the others nor the console.
 | `onReport` | Called with each run |
 | `duplicates` | `duplicateRegistrations` from `@fusion.dev/helix-core` |
 | `file` | Your project's `helix-diagnostics.json`, imported |
-| Any setting below | `rules`, `console`, `sinks`, `send`, `detail`, `environments`, `project` |
+| Any setting below | `rules`, `console`, `core`, `sinks`, `send`, `detail`, `environments`, `project` |
 
 The handle has `active`, `latest`, `run()`, `subscribe()`, and `stop()`. An
 end-to-end test reaches it at `globalThis[Symbol.for('fusion.dev/helix/diagnostics')]`
@@ -163,6 +170,13 @@ A report is one run, in one shape for every sink, versioned by `schema`:
   `integrity`, or `guideline`), an `owner` (`consumer`, or `helix` for a fault
   in the library), a `fingerprint` that stays the same from one run to the next
   for the same fault, and the rule's own text as evidence.
+- **`performance`**: what the components cost, by tag, where you asked for it.
+  See [Performance](#performance).
+- **`runtime`**: what the library reported going wrong as it ran on the page,
+  from its first load. One entry per distinct event, with its `kind`, its
+  `tag`, the sentence that says what to do, how many times it was reported,
+  and whether core printed it. A `fingerprint` stays the same from one run to
+  the next, with the numbers in the sentence left out.
 - **`usage`**: the Helix elements on the page by tag, the axes set on them
   (`emphasis`, `material`, `separation`, and `tone`), the named slots filled,
   the elements Helix renders inside other Helix elements, and the parts and
@@ -188,9 +202,11 @@ works on it:
 | A finding at `error` | `console.error` |
 | A finding at `warn` | `console.warn` |
 | A finding at `info` | `console.info` |
+| A runtime event core left to diagnostics | `console.warn`, or `console.error` for a failure |
 | Stylesheets that could not be read | `console.warn` |
 | Coverage, and findings turned off | `console.info` |
 | Usage | `console.debug`, hidden at the default level |
+| Performance, where you asked for it | `console.info`, when the measures change |
 
 ## Finding kinds
 
@@ -216,6 +232,58 @@ for another route.
 attributes, `aria-*`, `data-*`, and the prefixes frameworks write are never
 findings. The markup Helix renders inside its own components is Helix's.
 
+## Runtime events
+
+Helix reports these itself as it runs, through one channel in
+`@fusion.dev/helix-core`. Each is printed in the console as it happens, and
+diagnostics counts it by kind and tag. None fails a CI job.
+
+| Kind | Means |
+| --- | --- |
+| `duplicate-registration` | Two copies of Helix are on the page. Also the finding of the same name |
+| `fullscreen-refused` | The browser refused fullscreen, usually in a frame without `allow="fullscreen"` |
+| `max-past-fold` | An avatar group's `max` is past the number its fold is written for |
+| `min-out-of-range` | A rating's `min` is not a score between 0 and its `max` |
+| `misplaced-handler` | A React `on` prop names an event that another element dispatches |
+| `missing-layout` | The three.js graph driver could not load `d3-force-3d` |
+| `missing-row-key` | A selectable data table has no `row-key`, so it knows each row by its place |
+| `missing-stencil-parts` | A graph stencil names parts its shape does not have |
+| `missing-trigger` | A tooltip's `for` names no element in its own tree |
+| `negative-value` | An area chart was given a negative number, which it draws as none |
+| `not-a-graph` | `connectGraph` was given an element that is not a graph frame |
+| `picture-in-picture-refused` | The browser refused picture in picture |
+| `removed-callback` | A React prop is a callback that was removed and never ran from JSX |
+| `solid-handler-syntax` | A React prop uses Solid's `on:` syntax |
+| `stencil-regions-unused` | A graph stencil's regions could not be used |
+| `stencil-without-inside` | A graph stencil has no inside to place the notes in |
+| `too-many-rows` | A data table is drawing more rows at once than it stays responsive to |
+| `two-default-operators` | A filter field marks more than one operator as its default |
+| `unknown-event` | A React `on` prop names an event that no element dispatches |
+| `unlinked-trigger` | A tooltip's trigger does not name it in `aria-describedby` |
+| `unsettled-window` | A virtualized list's box has no height of its own |
+| `untold-trigger` | A slotted trigger is a plain element, which cannot carry `aria-expanded` |
+| `wrapped-trigger` | A tooltip wraps its trigger, so its text reaches no screen reader |
+
+## Performance
+
+Diagnostics measures what the components cost only where you ask for it. Set
+`console: { performance: 'info' }` to print the measures in DevTools, or
+`send: { performance: true }` to keep them in each run, for your app, the
+relay, and the CI file. For each tag rendered on the page, it measures:
+
+- **First updates**: each element's own first update, from `willUpdate` to
+  `updated`, as a count, a median, a 95th percentile, and the slowest. Time an
+  element spends waiting behind other elements is not counted.
+- **Layout shift**: the shift its elements moved, summed as the browser scores
+  it. A shift that follows a press or a keystroke is left out.
+- **Long tasks**: how many tasks of 50 ms or more one of its first updates ran
+  in.
+
+Core times each first update only while diagnostics is measuring, so a page
+that has not asked pays one property read per element. Layout shift and long
+tasks are measured in Chromium only. Elsewhere `measured` says so, and their
+numbers are left out.
+
 ## Configure it
 
 Every setting can be given in three places, and a later place wins, field by
@@ -250,6 +318,9 @@ diagnose({
 | `console.findings` | `error`, `warn`, `info`, or `off`: the lowest severity printed | `info` |
 | `console.coverage` | `info` or `off` | `info` |
 | `console.usage` | `debug` or `off` | `debug` |
+| `console.runtime` | `warn` or `off`: the runtime events core left to diagnostics | `warn` |
+| `console.performance` | `info` or `off`: what the components cost, which is measured where this is on | `off` |
+| `core.warnings` | `true` or `false`: whether core prints each runtime event as it happens | `true` |
 | `sinks.overlay` | `true` or `false`, for the badge in development | `true` |
 | `sinks.relay` | `true`, `false`, or an address on a local host, such as `http://127.0.0.1:7417` | `false` |
 | `send.<category>` | `true` or `false`, for `findings`, `usage`, `coverage`, `configuration`, `runtime`, `performance`, and `assist` | all on but `performance` |

package/dist/ci.js

@@ -1,5 +1,6 @@
 import { mkdirSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
+import { shownRuntime } from './runtime.js';
 const RANK = { error: 3, info: 1, warn: 2 };
 const counted = (count, noun) => `${count} ${noun}${count === 1 ? '' : 's'}`;
 export const ciSink = (runs, { file, failOn = 'error' }) => {
@@ -17,8 +18,17 @@ export const ciSink = (runs, { file, failOn = 'error' }) => {
     const of = (severity) => all.filter(({ finding }) => finding.severity === severity).length;
     const failing = failOn === 'never' ? [] : all.filter(({ finding }) => RANK[finding.severity] >= RANK[failOn]);
     const unread = runs.reduce((total, run) => total + run.coverage.unreadable.length, 0);
+    const events = new Map();
+    for (const run of runs) {
+        for (const entry of shownRuntime(run.runtime ?? [])) {
+            const event = events.get(entry.fingerprint) ?? { entry, pages: new Set() };
+            event.pages.add(run.run.page ?? '(no page)');
+            events.set(entry.fingerprint, event);
+        }
+    }
     const lines = [
         `helix diagnostics: ${counted(runs.length, 'run')}, ${counted(of('error'), 'error')}, ${counted(of('warn'), 'warning')}, ${of('info')} info` +
+            (events.size > 0 ? `, ${events.size} runtime` : '') +
             (unread > 0 ? `, ${counted(unread, 'unreadable stylesheet')}` : '') +
             `. Written to ${file}.`,
     ];
@@ -26,5 +36,9 @@ export const ciSink = (runs, { file, failOn = 'error' }) => {
         const where = [...pages].sort();
         lines.push(`  ${finding.severity} ${finding.kind}: ${finding.subject}`, `    ${finding.message}`, `    on ${where.slice(0, 5).join(', ')}${where.length > 5 ? `, and ${where.length - 5} more` : ''}`);
     }
+    for (const { entry, pages } of events.values()) {
+        const where = [...pages].sort();
+        lines.push(`  runtime ${entry.kind}${entry.tag ? ` <${entry.tag}>` : ''}`, `    ${entry.message}`, `    on ${where.slice(0, 5).join(', ')}${where.length > 5 ? `, and ${where.length - 5} more` : ''}`);
+    }
     return { code: failing.length > 0 ? 1 : 0, summary: lines.join('\n') };
 };

package/dist/config.d.ts

@@ -4,6 +4,8 @@ import { type Rules } from './rules.js';
 export interface Config {
     /** The lowest level each category prints at in the console, or `off`. */
     console?: Partial<Configuration['console']>;
+    /** What `@fusion.dev/helix-core` does itself: whether it prints its runtime warnings. */
+    core?: Partial<Configuration['core']>;
     /** How much detail goes with what is sent. */
     detail?: Partial<Configuration['detail']>;
     /** Where sending happens. Production takes `{ sample }`, from 0 to 1. */
@@ -33,8 +35,13 @@ export declare const DEFAULTS: {
     readonly console: {
         readonly coverage: 'info';
         readonly findings: 'info';
+        readonly performance: 'off';
+        readonly runtime: 'warn';
         readonly usage: 'debug';
     };
+    readonly core: {
+        readonly warnings: true;
+    };
     readonly detail: {
         readonly evidence: 'full';
         readonly hookValues: true;

package/dist/config.js

@@ -2,7 +2,14 @@ import { nearest } from './manifest.js';
 import { CATEGORIES } from './report.js';
 import { checkRules } from './rules.js';
 export const DEFAULTS = {
-    console: { coverage: 'info', findings: 'info', usage: 'debug' },
+    console: {
+        coverage: 'info',
+        findings: 'info',
+        performance: 'off',
+        runtime: 'warn',
+        usage: 'debug',
+    },
+    core: { warnings: true },
     detail: { evidence: 'full', hookValues: true, pages: 'patterns' },
     environments: { ci: true, development: true, production: false },
     send: {
@@ -32,8 +39,11 @@ const ALLOWED = {
     console: {
         coverage: ['info', 'off'],
         findings: ['error', 'warn', 'info', 'off'],
+        performance: ['info', 'off'],
+        runtime: ['warn', 'off'],
         usage: ['debug', 'off'],
     },
+    core: { warnings: [true, false] },
     detail: {
         evidence: ['full', 'selector', 'none'],
         hookValues: [true, false],
@@ -123,6 +133,7 @@ export const resolveConfig = (file, call) => {
     return {
         configuration: {
             console: merged('console', { ...DEFAULTS.console }),
+            core: merged('core', { ...DEFAULTS.core }),
             detail: merged('detail', { ...DEFAULTS.detail }),
             environments: merged('environments', { ...DEFAULTS.environments }),
             sinks: merged('sinks', { ...DEFAULTS.sinks }),

package/dist/console.d.ts

@@ -9,9 +9,11 @@
  * | A finding at `error` | `console.error` | The CSS does nothing where it was written |
  * | A finding at `warn` | `console.warn` | Worth fixing, and the page works |
  * | A finding at `info` | `console.info` | Advice |
+ * | A runtime event core left to diagnostics | `console.warn`, or `console.error` for a failure | The library was used wrong as it ran |
  * | Unreadable stylesheets | `console.warn` | The run could not see part of the page |
  * | Coverage, overrides, a clean run | `console.info` | What the run looked at |
  * | Usage | `console.debug` | For whoever studies usage, hidden at the default level |
+ * | Performance, where asked for | `console.info` | What the components cost, by tag |
  *
  * **All of it in one group**, headed by the counts, so a page with other logs
  * keeps a run together and a clean run collapses to one line.

package/dist/console.js

@@ -1,3 +1,4 @@
+import { shownRuntime } from './runtime.js';
 const entry = (finding) => {
     const by = finding.decidedBy === 'shipped' ? '' : ` (${finding.severity}, set by the ${finding.decidedBy})`;
     const lines = [`${finding.kind}${by}: ${finding.subject}`, finding.message];
@@ -16,16 +17,18 @@ export const report = (result, to = console, { shown, } = {}) => {
     const warnings = bySeverity('warn');
     const off = configuration.silenced.reduce((total, one) => total + one.count, 0);
     const missed = coverage.sheets - coverage.read;
+    const runtime = shownRuntime(result.runtime);
     const counts = [
         counted(errors, 'error'),
         counted(warnings, 'warning'),
         `${bySeverity('info')} info`,
+        ...(runtime.length > 0 ? [`${runtime.length} runtime`] : []),
         ...(off > 0 ? [`${off} turned off`] : []),
     ];
-    const heading = findings.length === 0 && off === 0
+    const heading = findings.length === 0 && off === 0 && runtime.length === 0
         ? 'helix diagnostics: no findings'
         : `helix diagnostics: ${counts.join(', ')}`;
-    if (errors + warnings > 0 || missed > 0) {
+    if (errors + warnings + runtime.length > 0 || missed > 0) {
         to.group(heading);
     }
     else {
@@ -64,6 +67,34 @@ export const report = (result, to = console, { shown, } = {}) => {
             to.info(`${counted(before, 'finding')} printed before, on this page, and not again`);
         }
     }
+    if (levels.runtime !== 'off') {
+        for (const one of runtime) {
+            if (one.printed || shown?.has(one.fingerprint)) {
+                continue;
+            }
+            shown?.add(one.fingerprint);
+            to[one.level](`${one.kind}${one.tag ? ` <${one.tag}>` : ''}: ${one.message}`);
+        }
+    }
+    if (levels.performance !== 'off' && result.performance) {
+        const { measured, tags } = result.performance;
+        const rows = Object.entries(tags)
+            .sort(([, a], [, b]) => b.render.p95 - a.render.p95)
+            .slice(0, 10);
+        const lines = rows.map(([tag, one]) => `${tag}: ${one.render.p50} ms median, ${one.render.p95} ms p95, ${one.render.max} ms slowest, of ${counted(one.render.count, 'first update')}` +
+            (measured.layoutShift && one.shift > 0 ? `; ${one.shift} layout shift` : '') +
+            (measured.longTasks && one.longTasks > 0 ? `; ${counted(one.longTasks, 'long task')}` : ''));
+        const key = `performance ${result.run.page ?? ''} ${lines.join('|')}`;
+        if (rows.length > 0 && !shown?.has(key)) {
+            shown?.add(key);
+            to.info([
+                `performance: ${counted(Object.keys(tags).length, 'tag')} measured, slowest first` +
+                    (measured.layoutShift ? '' : '. Layout shift is not measured in this browser') +
+                    (measured.longTasks ? '' : '. Long tasks are not measured in this browser'),
+                ...lines,
+            ].join('\n'));
+        }
+    }
     if (levels.usage !== 'off') {
         const { counted: how, hooks, parts, tags, unlisted } = result.usage;
         const sum = (counts) => Object.values(counts).reduce((total, one) => total + Object.keys(one).length, 0);

package/dist/diagnose.js

@@ -5,6 +5,7 @@ import { identify } from './identity.js';
 import { index, lintFor, versionsOf } from './manifest.js';
 import { pageOf } from './page.js';
 import { applyRules, overridesOf } from './rules.js';
+import { logged, tally } from './runtime.js';
 import { listed, loadedVersions, styled, walk } from './usage.js';
 import { VERSION } from './version.js';
 const runId = () => globalThis.crypto?.randomUUID?.() ??
@@ -24,6 +25,20 @@ export const diagnose = (options) => {
     const lints = tiers.map((tier) => ({ lint: lintFor(tier) }));
     const tags = index(lints);
     const counted = watcher ? watcher.counts() : walk(document_, walked);
+    const runtime = watcher
+        ? watcher.runtime()
+        : (() => {
+            const kept = tally();
+            for (const event of logged()) {
+                kept.add(event, true);
+            }
+            return kept.entries();
+        })();
+    const reported = runtime
+        .filter((one) => one.kind === 'duplicate-registration' && one.tag !== undefined)
+        .map((one) => one.tag);
+    const twice = duplicates ?? (reported.length > 0 ? () => reported : undefined);
+    const measured = watcher?.performance();
     const seen = loadedVersions();
     const manifests = versionsOf(lints);
     const byVersion = versionSkew(manifests, seen);
@@ -34,7 +49,7 @@ export const diagnose = (options) => {
         : applyRules([
             ...analyze(located, tags, document_, answered, used, readers),
             ...markup(tags, document_, walked),
-            ...registrations(document_, duplicates, walked),
+            ...registrations(document_, twice, walked),
         ].map((one) => identify(one, tags)), file?.rules, call.rules);
     const path = page ?? globalThis.location?.pathname;
     const shownPage = path === undefined || detail.pages === 'none'
@@ -59,6 +74,8 @@ export const diagnose = (options) => {
             ...(environment === undefined ? {} : { environment }),
             ...(shownPage === undefined ? {} : { page: shownPage }),
         },
+        ...(measured === undefined ? {} : { performance: measured }),
+        runtime,
         schema: 1,
         usage: {
             ...listed(counted, tags),

package/dist/identity.d.ts

@@ -30,5 +30,11 @@ export declare const normalize: (subject: string) => string;
  * seen twice, which is how a reader thinks of it.
  */
 export declare const fingerprintOf: (finding: Pick<Raw, 'kind' | 'subject' | 'tag'>) => string;
+/**
+ * A runtime event's identity across runs: its kind, its tag, and its sentence
+ * with each run of digits read as one, so a count in the sentence is not part
+ * of what the event is.
+ */
+export declare const runtimeFingerprint: (kind: string, tag: string | undefined, message: string) => string;
 /** A finding with its category, owner, family, and fingerprint. */
 export declare const identify: (finding: Raw, tags: Map<string, Published>) => Identified;

package/dist/identity.js

@@ -37,6 +37,7 @@ const hash = (text) => {
     return (4294967296 * (2097151 & two) + (one >>> 0)).toString(16).padStart(14, '0');
 };
 export const fingerprintOf = (finding) => hash(`${finding.kind}\u0000${finding.tag}\u0000${normalize(finding.subject)}`);
+export const runtimeFingerprint = (kind, tag, message) => hash(`runtime\u0000${kind}\u0000${tag ?? ''}\u0000${message.replace(/\d[\d,.]*/g, '#')}`);
 export const identify = (finding, tags) => ({
     ...finding,
     category: CATEGORY[finding.kind],

package/dist/init.js

@@ -2,6 +2,7 @@ import { checkConfig, LOCAL, resolveConfig } from './config.js';
 import { report as print } from './console.js';
 import { diagnose } from './diagnose.js';
 import { overlayOn } from './overlay.js';
+import { shownRuntime } from './runtime.js';
 import { schedule } from './schedule.js';
 import { loadedVersions, watch } from './usage.js';
 export const INSTANCE = Symbol.for('fusion.dev/helix/diagnostics');
@@ -53,14 +54,15 @@ export const initDiagnostics = (options = {}) => {
 };
 const start = (options, page) => {
     const { cdn = CDN, duplicates, environment, file, onReport, page: route, tiers, ...call } = options;
-    let configuration;
+    let resolved;
     try {
-        configuration = resolveConfig(file, call).configuration;
+        resolved = resolveConfig(file, call);
     }
     catch (error) {
         once(`settings ${messageOf(error)}`, () => console.error(`helix diagnostics: not started. ${messageOf(error)}`));
         return inert();
     }
+    const { configuration } = resolved;
     const host = globalThis.location?.hostname ?? '';
     if (environment === undefined && !LOCAL.test(host)) {
         once(`host ${host}`, () => console.info(`helix diagnostics: not running on ${host || 'this page'}, which is no local host, with no environment declared. Pass \`environment\` to run here.`));
@@ -78,11 +80,13 @@ const start = (options, page) => {
         duplicates,
         environment,
         file,
+        measure: resolved.send.performance.on || configuration.console.performance !== 'off',
         onReport,
         page,
         route,
         sinks: configuration.sinks,
         tiers,
+        warnings: configuration.core.warnings,
     });
 };
 const running = (given) => {
@@ -90,6 +94,7 @@ const running = (given) => {
     const production = environment === 'production';
     const development = environment === undefined || environment === 'development';
     let file = given.file;
+    let warnings = given.warnings;
     let overlay;
     const relay = production ? undefined : sinks.relay === true ? RELAY : sinks.relay || undefined;
     let relayed = false;
@@ -164,7 +169,7 @@ const running = (given) => {
         deliver('the helix-diagnostics event', () => page.dispatchEvent(new CustomEvent('helix-diagnostics', { detail: run })));
         if (sinks.overlay && development) {
             deliver('the overlay', () => {
-                if (overlay || run.findings.length > 0) {
+                if (overlay || run.findings.length > 0 || shownRuntime(run.runtime).length > 0) {
                     overlay ??= overlayOn(page);
                     overlay.show(run);
                 }
@@ -251,6 +256,7 @@ const running = (given) => {
                     try {
                         checkConfig(served, 'file');
                         file = served;
+                        warnings = resolveConfig(file, call).configuration.core.warnings;
                     }
                     catch (error) {
                         once(`relay settings ${messageOf(error)}`, () => console.error(`helix diagnostics: the settings the relay served were not used. ${messageOf(error)}`));
@@ -262,7 +268,12 @@ const running = (given) => {
             .catch((error) => once('no relay', () => console.warn(`helix diagnostics: no relay at ${relay} (${messageOf(error)}). Start it with \`helix diagnostics\`, or turn \`sinks.relay\` off.`)));
     }
     const plan = schedule(runNow);
-    const watcher = watch(page, { onRender: () => plan.poke() });
+    const watcher = watch(page, {
+        onRender: () => plan.poke(),
+        onRuntime: () => plan.poke(),
+        performance: given.measure,
+        quiet: () => !warnings,
+    });
     const poke = () => plan.poke();
     const observer = typeof MutationObserver === 'function'
         ? new MutationObserver((records) => {

package/dist/overlay.js

@@ -1,5 +1,6 @@
 import { matchable } from './analyze.js';
 import { OVERLAY } from './page.js';
+import { shownRuntime } from './runtime.js';
 const STYLE = `
 :host {
   all: initial;
@@ -228,30 +229,40 @@ export const overlayOn = (page) => {
             badge.focus();
         }
     });
-    const point = (finding) => {
-        const target = finding ? locate(finding, page) : null;
+    const point = (target, severity) => {
         if (!target) {
             outline.hidden = true;
             return;
         }
         const box = target.getBoundingClientRect();
-        outline.style.borderColor = `var(--${finding?.severity})`;
+        outline.style.borderColor = `var(--${severity})`;
         outline.style.insetBlockStart = `${box.top - 3}px`;
         outline.style.insetInlineStart = `${box.left - 3}px`;
         outline.style.blockSize = `${box.height + 2}px`;
         outline.style.inlineSize = `${box.width + 2}px`;
         outline.hidden = false;
     };
+    const follow = (item, target, severity) => {
+        item.addEventListener('mouseenter', () => point(target(), severity));
+        item.addEventListener('focus', () => point(target(), severity));
+        item.addEventListener('mouseleave', () => point(null));
+        item.addEventListener('blur', () => point(null));
+    };
     const show = (run) => {
         const findings = run.findings;
+        const runtime = shownRuntime(run.runtime);
         const of = (severity) => findings.filter((one) => one.severity === severity).length;
-        const worst = of('error') > 0 ? 'error' : of('warn') > 0 ? 'warn' : 'info';
-        const counts = ['error', 'warn', 'info']
-            .filter((severity) => of(severity) > 0)
-            .map((severity) => counted(of(severity), severity))
-            .join(', ');
-        badge.hidden = findings.length === 0;
-        if (findings.length === 0) {
+        const failed = runtime.some((one) => one.level === 'error');
+        const worst = of('error') > 0 || failed ? 'error' : of('warn') > 0 || runtime.length > 0 ? 'warn' : 'info';
+        const counts = [
+            ...['error', 'warn', 'info']
+                .filter((severity) => of(severity) > 0)
+                .map((severity) => counted(of(severity), severity)),
+            ...(runtime.length > 0 ? [`${runtime.length} runtime`] : []),
+        ].join(', ');
+        const total = findings.length + runtime.length;
+        badge.hidden = total === 0;
+        if (total === 0) {
             open(false);
         }
         dot.style.background = `var(--${worst})`;
@@ -267,10 +278,21 @@ export const overlayOn = (page) => {
             if (finding.origin) {
                 item.append(make('span', 'where', `in ${finding.origin.sheet}`), make('pre', undefined, finding.origin.cssText));
             }
-            item.addEventListener('mouseenter', () => point(finding));
-            item.addEventListener('focus', () => point(finding));
-            item.addEventListener('mouseleave', () => point(undefined));
-            item.addEventListener('blur', () => point(undefined));
+            follow(item, () => locate(finding, page), finding.severity);
+            return item;
+        }), ...runtime.map((one) => {
+            const item = make('li');
+            item.tabIndex = 0;
+            const head = make('span', 'kind');
+            head.append(make('span', one.level, `${one.level} `), document.createTextNode(one.kind));
+            item.append(head);
+            if (one.tag) {
+                item.append(make('code', 'subject', `<${one.tag}>`));
+            }
+            item.append(worded(one.message), make('span', 'where', one.count === 1
+                ? 'Reported by Helix as the page ran'
+                : `Reported by Helix ${one.count} times as the page ran`));
+            follow(item, () => (one.tag ? page.querySelector(one.tag) : null), one.level);
             return item;
         }));
     };

package/dist/performance.d.ts

@@ -0,0 +1,34 @@
+import type { PerformanceReport } from './report.js';
+/** The key `@fusion.dev/helix-core` hands each first update's timing to. */
+export declare const RENDER_SLOT: unique symbol;
+/** A measure as the page holds it, until a run reads it. */
+export interface Measurer {
+    /** The measures so far. A copy: measuring goes on after it is read. */
+    results(): PerformanceReport;
+    /** Stops measuring, and gives the slot back to whatever held it before. */
+    stop(): void;
+}
+/**
+ * The tag of the Helix element a node belongs to: the node itself, or the
+ * nearest Helix element above it, through shadow roots.
+ */
+export declare const helixOf: (node: Node | null | undefined) => string | undefined;
+/** The value at a fraction of the way through sorted numbers, by nearest rank. */
+export declare const percentile: (sorted: readonly number[], fraction: number) => number;
+/** A layout-shift entry's part, as this reads it. */
+interface Shift {
+    hadRecentInput?: boolean;
+    sources?: ReadonlyArray<{
+        node?: Node | null | undefined;
+    }>;
+    value: number;
+}
+/**
+ * Shares one shift's score out among the Helix elements its sources belong
+ * to, an equal share each. A shift a reader caused, by typing or pressing, is
+ * no fault of the page's, which is how the browser scores it too.
+ */
+export declare const shares: (shift: Shift) => Map<string, number>;
+/** Starts measuring, from now on, and the layout shift and long tasks the browser kept from before. */
+export declare const measure: () => Measurer;
+export {};

package/dist/performance.js

@@ -0,0 +1,121 @@
+import { OVERLAY } from './page.js';
+export const RENDER_SLOT = Symbol.for('fusion.dev/helix/render');
+const KEPT = 1000;
+export const helixOf = (node) => {
+    let at = node;
+    while (at) {
+        if (at.nodeType === 1) {
+            const tag = at.localName;
+            if (tag.startsWith('helix-') && tag !== OVERLAY) {
+                return tag;
+            }
+        }
+        at = at.parentNode ?? at.host ?? null;
+    }
+    return undefined;
+};
+export const percentile = (sorted, fraction) => sorted.length === 0
+    ? 0
+    : (sorted[Math.min(sorted.length - 1, Math.ceil(fraction * sorted.length) - 1)] ?? 0);
+const tenth = (value) => Math.round(value * 10) / 10;
+const thousandth = (value) => Math.round(value * 1000) / 1000;
+export const shares = (shift) => {
+    const out = new Map();
+    const sources = shift.sources ?? [];
+    if (shift.hadRecentInput || sources.length === 0) {
+        return out;
+    }
+    const each = shift.value / sources.length;
+    for (const source of sources) {
+        const tag = helixOf(source.node);
+        if (tag) {
+            out.set(tag, (out.get(tag) ?? 0) + each);
+        }
+    }
+    return out;
+};
+const supports = (type) => typeof PerformanceObserver === 'function' &&
+    (PerformanceObserver.supportedEntryTypes ?? []).includes(type);
+export const measure = () => {
+    const gathered = new Map();
+    const of = (tag) => {
+        let one = gathered.get(tag);
+        if (!one) {
+            one = { durations: [], shift: 0, spans: [] };
+            gathered.set(tag, one);
+        }
+        return one;
+    };
+    const long = [];
+    const store = globalThis;
+    const before = store[RENDER_SLOT];
+    let live = true;
+    const listener = (element, timing) => {
+        if (live && element?.localName !== OVERLAY) {
+            const one = of(element.localName);
+            one.durations.push(timing.duration);
+            if (one.spans.length < KEPT) {
+                one.spans.push({ end: timing.start + timing.duration, start: timing.start });
+            }
+        }
+        if (typeof before === 'function') {
+            before(element, timing);
+        }
+    };
+    store[RENDER_SLOT] = listener;
+    const observers = [];
+    const observe = (type, take) => {
+        if (!supports(type)) {
+            return false;
+        }
+        try {
+            const observer = new PerformanceObserver((list) => {
+                for (const entry of list.getEntries()) {
+                    take(entry);
+                }
+            });
+            observer.observe({ buffered: true, type });
+            observers.push(observer);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    const layoutShift = observe('layout-shift', (entry) => {
+        for (const [tag, share] of shares(entry)) {
+            of(tag).shift += share;
+        }
+    });
+    const longTasks = observe('longtask', (entry) => {
+        long.push({ end: entry.startTime + entry.duration, start: entry.startTime });
+    });
+    return {
+        results: () => {
+            const tags = {};
+            for (const [tag, one] of [...gathered].sort(([a], [b]) => (a < b ? -1 : 1))) {
+                const sorted = [...one.durations].sort((a, b) => a - b);
+                tags[tag] = {
+                    longTasks: long.filter((task) => one.spans.some((span) => span.start < task.end && span.end > task.start)).length,
+                    render: {
+                        count: sorted.length,
+                        max: tenth(sorted.at(-1) ?? 0),
+                        p50: tenth(percentile(sorted, 0.5)),
+                        p95: tenth(percentile(sorted, 0.95)),
+                    },
+                    shift: thousandth(one.shift),
+                };
+            }
+            return { measured: { layoutShift, longTasks }, tags };
+        },
+        stop: () => {
+            live = false;
+            for (const observer of observers) {
+                observer.disconnect();
+            }
+            if (store[RENDER_SLOT] === listener) {
+                store[RENDER_SLOT] = before;
+            }
+        },
+    };
+};

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';
@@ -242,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/usage.d.ts

@@ -1,7 +1,8 @@
 import type { Answered, Located } from './collect.js';
 import type { Published } from './manifest.js';
 import { type Page } from './page.js';
-import type { Usage } from './report.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'>;
 /**
@@ -23,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;
 }
 /**
@@ -41,13 +50,26 @@ 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, { onRender, }?: {
+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

package/dist/usage.js

@@ -1,5 +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) => {
@@ -68,7 +70,7 @@ export const listed = (counted, tags) => {
         unlisted,
     };
 };
-export const watch = (from = document, { onRender, } = {}) => {
+export const watch = (from = document, { onRender, onRuntime, performance, quiet, } = {}) => {
     const counted = empty();
     const seen = new WeakSet();
     const see = (element) => {
@@ -93,13 +95,38 @@ export const watch = (from = document, { onRender, } = {}) => {
     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.139.0";
+export declare const VERSION = "0.140.0";

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = '0.139.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.139.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.139.0",
+    "@fusion.dev/helix-testing": "0.140.0",
     "@types/bun": "^1.3.0"
   },
   "homepage": "https://fusion.dev",