# KitJS browser benchmarks

This harness measures the checked-in standalone artifacts in `dist/`; it does
not build from `src/` and does not call a private runtime API. Each recorded
sample gets a fresh browser context and a local, no-store HTTP fixture.

Run the default Chromium matrix (1,000 and 10,000 nodes, one warmup and five
recorded samples):

```sh
npm run bench
```

Useful variants:

```sh
npm run bench -- --smoke
npm run bench -- --full
npm run bench -- --browsers=chromium,firefox,webkit
npm run bench -- --sizes=1000 --samples=10 --warmups=2
```

`--full` adds the optional 50,000-node tier. `--smoke` runs every applicable
scenario at 100 nodes with one sample. Use `--help` for profile, scenario,
timeout, and output filters.

The cases cover cold boot, delegated click plus `outside`, action-alias lookup,
Promise-settlement rendering, keyed-list reconciliation, and Hydrate Drive
Morph. Drive Morph is intentionally absent from the `kit` profile because
Morph and Drive are not part of that artifact.

The critical browser matrix separately locks the scheduling shape without a
clock: initial component metadata/template preparation occurs once, while a
known Promise owner and debounce owner settle with zero document-wide lookup.
For a structure-free component, binding, class, style, and model work is also
planned from exactly one owned-tree traversal. Those scan-count assertions
complement this end-to-end timing harness.

The default report is `.bench-results/latest.json`. It contains the package
identity and exact artifact hashes, browser name/version, Node and Playwright
versions, OS/architecture, configuration, raw samples, median, p95, and a
completion shape. It omits hostnames, usernames, local paths, environment
variables, URLs, and machine identifiers. Generated reports are gitignored.

These measurements are comparative evidence, not release pass/fail limits.
The timeout only detects a case that never completes. Every sample must still
produce the expected DOM count and final state, so a fast but incomplete run
fails instead of becoming a timing result. Keep machines otherwise quiet and
compare results on the same machine with the same artifact hash, browser
version, platform, sizes, warmups, and sample count. The privacy-safe report
does not identify the machine, so keep that run label or hardware inventory
outside the JSON when results must be compared across time.