mirror of
https://github.com/4gray/iptvnator.git
synced 2026-10-08 09:01:03 -08:00
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>
7.6 KiB
7.6 KiB
Agent context map
Read the row for your task before editing. For a cross-domain change, read each affected contract. This is navigation, not a request to load every linked file. Common constraints remain in AGENTS.md; Claude imports it. Repository skill frontmatter defines triggers. If your client does not discover a listed skill automatically, read its SKILL.md directly. Optional global tools are not prerequisites for reading repository contracts.
Development and maintenance
| Area / code ownership | Canonical documents | Repository skill |
|---|---|---|
| Bootstrap, project placement, dependencies, aliases and lint configuration; root Nx config and project-local project.json files | Nx boundaries, security overrides | Nx architecture |
| Angular conventions; docs and skills maintenance | Agent workflow | Use the area's skill below |
Unit, E2E, lint and coverage; tools/coverage |
Validation map | Use the area's validation section |
Performance journeys, counters and the CI ratchet; tools/performance |
Performance journeys | Read the contract directly |
Electron entry/events/preload and CDP; apps/electron-backend |
Debugging and trace flags, Electron security | Use the available global electron skill for automation |
Releases, notes, screenshots, native assets, Linux manager metadata; tools/release |
Release pipeline, note format | Release notes, release cut |
Data, sources and networking
| Area / code ownership | Required contracts | Repository skill |
|---|---|---|
SQLite schema/startup; libs/shared/database; Electron DB events/workers/operations |
DB worker, migration ownership and tests | SQLite worker |
M3U import/state/player, XMLTV, source lifecycle, startup readiness and OS file opening; libs/m3u-state, libs/playlist, libs/epg |
M3U module, adding sources across layers | Read both contracts when adding a source |
Xtream API/store/data sources and routed views; libs/portal/xtream |
Xtream compatibility, category management, detail navigation | Xtream |
Stalker/Ministra protocol, identity, sessions and routed views; libs/portal/stalker |
Stalker portal, Stalker EPG for EPG work, store API baseline for store API changes | Stalker |
Browser runtime, HTTP proxies, redirects and backend networking; apps/web-backend, libs/shared/host-health |
PWA/self-hosting, connectivity guard, Electron security for desktop boundary changes | Read the affected runtime contract |
| Source health and selective cleanup; portal shared data access | Desktop source health, subscription expiry | Read the affected provider skill |
| Backup and restore; playlist persistence | Backup/restore, database migrations | Read the affected persistence skill |
Playback, navigation and UI
| Area / code ownership | Required contracts | Repository skill |
|---|---|---|
Web engines, controls, tracks, PiP, radio and display sleep; libs/ui/playback |
Player controls, inline playback/diagnostics/recovery | Read the contract directly |
Embedded MPV, platform engines, addon, pinned runtime and packaging; Electron native services, tools/embedded-mpv |
Native MPV, runtime build and licensing | Read the contract directly |
| Live panels, keyboard focus, grid/layout conventions; shared UI and portal views | UI guidelines, detail navigation | UI design, theme/style |
Workspace routes, title bar, switcher, collections and dashboard; libs/workspace |
Workspace shell, dashboard, collection/detail navigation | UI/theme skills for visible changes |
Remote control, playback queue, channel return and shortcuts; libs/ui/remote-control, apps/remote-control-web |
Remote control | Provider skill when queue ownership changes |
Downloads, offline details, catch-up and file availability; libs/portal/downloads |
Download manager, provider contract for URL resolution | Read the affected provider skill |
VOD source discovery, factual metadata and failover; libs/portal/shared/data-access |
VOD multi-source | Xtream |
TMDB enrichment, artwork, actors and recommendations; libs/services/src/lib/tmdb |
TMDB contracts, dashboard | UI skill for rendering changes |
| Timezones, catch-up formatting and EPG display offsets | Date handling, Xtream compatibility, M3U EPG | Affected provider skill |
Website, blog and download pages; apps/website |
Website README | Use an available website skill |
Mock servers and fictional release fixtures; apps/stalker-mock-server, apps/xtream-mock-server |
Stalker mock, Xtream mock, release screenshot contract | Release-cut for release captures |
Maintenance rules
Keep unique behavior contracts in the authoritative document, procedures in a
skill or development guide, and universal constraints in AGENTS.md. Update this
map when ownership or a canonical destination changes. Preserve release skill
mirrors; do not create extra copies of other contracts for individual agents.
Use normal Markdown links for document destinations so pnpm run agents:validate
can check them. Do not add root imports for the linked documents.
The migration ledger explains how the original root instructions were accounted for. It is historical audit evidence, not another source of current runtime policy or required task context.