chore(performance): measure initial bytes of the built web app (#1692)

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>

docs/architecture/performance-journeys.md

@@ -0,0 +1,68 @@
+# 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.html` itself,
+- every same-origin `<script src>`, including `assets/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.
+
+```bash
+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
+
+1. Produce the value from the built output or from a deterministic probe, not
+   from source heuristics. Missing inputs must fail the measurement.
+2. Emit it under `journeys.<journey>.counters.<name>` in the summary JSON.
+3. Cover the extraction and the failure modes with `node --test` and register
+   the test file in `tools/performance/project.json`.
+4. Validate the counter before it becomes a guardrail: one PR must show that
+   lowering it moved wall-clock in the same journey.

docs/architecture/validation-map.md

@@ -153,6 +153,19 @@ Identical English fallback values are reported as warnings by default; use
 `node tools/i18n/check-drift.mjs --fail-on-identical` for a stricter translation
 audit.
 
+## Performance
+
+```bash
+pnpm nx build web
+pnpm run perf:initial-bytes
+pnpm nx test performance-tools
+```
+
+`perf:initial-bytes` reads the built `dist/apps/web/index.html` and sums the
+bytes on the initial path (the J1 counter `renderer.initialBytes`). The
+contract, what counts and how to add a counter are in the
+[performance journeys](performance-journeys.md) document.
+
 ## Logging
 
 Runtime playback and EPG debug logs should use the existing logger or trace

docs/maintenance/agent-context-map.md

@@ -14,6 +14,7 @@ are not prerequisites for reading repository contracts.
 | Bootstrap, project placement, dependencies, aliases and lint configuration; root Nx config and project-local project.json files | [Nx boundaries](../architecture/nx-workspace-boundaries.md), [security overrides](../architecture/dependency-security-overrides.md) | [Nx architecture](../../.codex/skills/iptvnator-nx-architecture/SKILL.md) |
 | Angular conventions; docs and skills maintenance | [Agent workflow](../development/agent-workflow.md) | Use the area's skill below |
 | Unit, E2E, lint and coverage; `tools/coverage` | [Validation map](../architecture/validation-map.md) | Use the area's validation section |
+| Performance journeys, counters and the CI ratchet; `tools/performance` | [Performance journeys](../architecture/performance-journeys.md) | Read the contract directly |
 | Electron entry/events/preload and CDP; `apps/electron-backend` | [Debugging and trace flags](../development/electron-debugging.md), [Electron security](../architecture/electron-security.md) | Use the available global electron skill for automation |
 | Releases, notes, screenshots, native assets, Linux manager metadata; `tools/release` | [Release pipeline](../architecture/release-pipeline.md), [note format](../../.changes/README.md) | [Release notes](../../.codex/skills/release-notes/SKILL.md), [release cut](../../.codex/skills/release-cut/SKILL.md) |