4grayandClaude Fable 5.1
8bc877b625
First step of the performance-journeys ratchet (plan thread: J1 `launch`, counter `renderer.initialBytes`).
- `tools/performance/measure-initial-bytes.mjs` reads the built `dist/apps/web/index.html` and sums `index.html` plus every same-origin `<script src>`, `<link rel="stylesheet">` and `<link rel="modulepreload">` it references. Manifest, icons, external URLs and lazy chunks are not counted. A referenced file missing from the build fails the measurement instead of counting as zero bytes.
- `--json` prints the breakdown; `--summary <file>` writes the `journeys.<journey>.counters` shape a ratchet checker will consume (next PR).
- New Nx project `performance-tools` (test + lint targets), Tier B in `tools/coverage/coverage-policy.json`, root scripts `perf:initial-bytes` and `perf:tools:test`.
- New contract `docs/architecture/performance-journeys.md`, linked from the validation map, the agent context map and the README.
- **Review follow-ups:** resources are deduplicated by request URL (query kept, fragment dropped); `index.html` is parsed with parse5 (already a repository dependency, scripting enabled), so comments, bogus comments, raw-text bodies (script/style/noscript/title/textarea), inert `<template>` contents and character references in attributes all follow the HTML5 algorithm instead of a hand-written scanner; the review's edge cases stay as regression tests; docs show the `pnpm --silent` form for JSON output and explain how the counter relates to Angular's rounded "Initial total".
- **Found while measuring:** the environment files and the playback diagnostic panel imported the whole `package.json` (`import packageJson from '@package'`), which esbuild cannot tree-shake, so `main.js` carried the complete file and the counter moved with every script or dependency edit. They now import `{ version }` only (eb662c485): `main.js` shrinks by **11,539 bytes** and the counter no longer depends on `package.json`. Jest's ESM loader exposes JSON only as a default export, so the two web Jest configs map `@package` to a stub that serves the real file's fields as named exports. Release note: `.changes/web-version-only-from-package-json.md` (`type: perf`).
Production build after this PR measures **2,739,508 bytes** (11 files + `index.html`); Angular's "Initial total" is this minus `index.html` and `assets/app-config.js`. The baseline file and the CI check land in the follow-up PRs; C1 (lazy Angular date locales) then lowers it.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
4.0 KiB
Performance journeys and the CI ratchet
IPTVnator measures performance through a small set of everyday user journeys.
Each journey has deterministic counters that are asserted exactly, and
wall-clock timings that are recorded as evidence. Counters are meant to be
ratcheted in CI: a committed baseline that may only be lowered, and only with
the measured output as evidence. This document is the contract for that loop;
tools/performance/ holds the scripts. The measurement script lands first;
the baseline file and the CI job follow in their own PRs (#1693, #1694), so
until they merge the reported number is informational, not enforced.
Journeys
| Journey | Start | End |
|---|---|---|
J1 launch |
Electron process spawn | first playlist or portal card rendered on /workspace, inline splash removed |
J2 open-source |
click on a portal card | live category list and first channel page painted |
J3 playback |
click on a channel | HTML5 playing event |
J4 search |
six-character query typed into global search | results list settled |
Only the J1 counter renderer.initialBytes is instrumented today. The other
journeys and counters follow the plan in .plans/ and are added one thread at
a time; each thread names its journey and counter in the PR description.
renderer.initialBytes
The bytes a browser fetches before Angular can bootstrap, read from the built
dist/apps/web/index.html:
index.htmlitself,- every same-origin
<script src>, includingassets/app-config.js, - every
<link rel="stylesheet">, - every
<link rel="modulepreload">chunk.
Manifest, icons, external URLs, commented-out tags and lazy chunks are not
counted. A file that index.html references but the build did not emit is an
error, never zero bytes. The value is raw (uncompressed) size, which is what the
renderer parses. It is Angular's "Initial total" plus index.html and
assets/app-config.js (about 4 KB together), so it sits slightly above the
rounded figure the build prints; never copy that figure into a baseline, use
the script's output. The bundle embeds only the app version from
package.json (a named import, which esbuild tree-shakes), not the whole
file, so editing scripts or dependencies does not move the counter.
pnpm nx build web # production configuration
pnpm run perf:initial-bytes # human-readable breakdown
pnpm --silent run perf:initial-bytes -- --json # machine-readable; --silent keeps pnpm's headers out of stdout
node tools/performance/measure-initial-bytes.mjs --summary dist/performance/journey-summary.json
--summary writes the journey summary shape (journeys.<journey>.counters)
that the ratchet checker consumes. --dist <dir> points the script at another
build output, for example the electron-performance configuration.
The measurement script is tools/performance/measure-initial-bytes.mjs; its
Node tests run with pnpm nx test performance-tools (Tier B in the coverage
policy) and lint with pnpm nx lint performance-tools.
Adding a counter
- Produce the value from the built output or from a deterministic probe, not from source heuristics. Missing inputs must fail the measurement.
- Emit it under
journeys.<journey>.counters.<name>in the summary JSON. - Cover the extraction and the failure modes with
node --testand register the test file intools/performance/project.json. - Validate the counter before it becomes a guardrail: one PR must show that lowering it moved wall-clock in the same journey.