iptvnator/docs/superpowers/plans/2026-07-30-structured-hls-diagnostics.md

# Structured HLS Diagnostics Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Replace broad HLS error-string heuristics with a safe structured
hls.js 1.6.16 evidence contract shared by HTML5 and ArtPlayer.

**Architecture:** Sanitize `ErrorData` at one boundary into an allowlisted
`HlsPlaybackEvidence` object, classify only that object, and return no terminal
diagnostic for recoverable events. Preserve the evidence on
`PlaybackDiagnostic` for deterministic technical details without retaining
engine messages, URLs, headers, response bodies, credentials, or arbitrary
provider payloads.

**Tech Stack:** Angular 21, TypeScript 5.9, hls.js 1.6.16, Jest through Nx,
ngx-translate JSON catalogs, Markdown release notes.

---

### Task 0: Confirm The Clean Baseline

**Files:**
- Verify only: `package.json`
- Verify only: `pnpm-lock.yaml`
- Verify only: `libs/ui/playback/project.json`

- [ ] **Step 1: Install locked dependencies**

Run:

```bash
pnpm install --frozen-lockfile
```

Expected: exit 0 without changing `pnpm-lock.yaml`.

- [ ] **Step 2: Verify Nx workspace discovery**

Run:

```bash
pnpm nx show projects
```

Expected: exit 0 and output containing `ui-playback`, `web`, and `web-e2e`.

- [ ] **Step 3: Run the affected project baseline**

Run:

```bash
pnpm nx test ui-playback --skip-nx-cache
```

Expected: 84 suites and 741 tests pass before implementation.

### Task 1: Drive The Evidence Contract From Failing Tests

**Files:**
- Create:
  `libs/ui/playback/src/lib/playback-diagnostics/hls-playback-evidence.util.spec.ts`
- Modify:
  `libs/ui/playback/src/lib/playback-diagnostics/playback-diagnostics.util.spec.ts`
- Modify:
  `libs/ui/playback/src/lib/playback-diagnostics/playback-diagnostics.model.ts`
- Create:
  `libs/ui/playback/src/lib/playback-diagnostics/hls-playback-evidence.util.ts`
- Modify:
  `libs/ui/playback/src/lib/playback-diagnostics/playback-diagnostics.util.ts`
- Modify:
  `libs/ui/playback/src/lib/playback-diagnostics/playback-error-patterns.util.ts`

- [ ] **Step 1: Add extractor regressions before the extractor exists**

In `hls-playback-evidence.util.spec.ts`, import hls.js 1.6.16 `ErrorData`,
`ErrorDetails`, and `ErrorTypes`, then exercise the wished-for export through
the existing diagnostics module namespace. Use a helper returning a complete
`ErrorData`:

```typescript
function createErrorData(overrides: Partial<ErrorData> = {}): ErrorData {
    return {
        type: ErrorTypes.OTHER_ERROR,
        details: ErrorDetails.UNKNOWN,
        error: new Error('provider payload must not survive'),
        fatal: true,
        ...overrides,
    };
}
```

Cover these exact shapes:

- manifest 404:
  `networkError`, `manifestLoadError`, `fatal: true`,
  `response.code: 404`;
- level timeout:
  `networkError`, `levelLoadTimeOut`, `fatal: true`;
- recoverable fragment load:
  `networkError`, `fragLoadError`, `fatal: false`;
- key load:
  `networkError`, `keyLoadError`;
- fatal fragment decrypt:
  `mediaError`, `fragDecryptError`;
- buffer codec:
  `mediaError`, `bufferAddCodecError`;
- unknown runtime type/detail values;
- response status boundaries 99/100/599/600 and non-integers;
- a payload containing credential-shaped URLs, headers, response text/data,
  context, `networkDetails`, `error`, and `reason`.

Expected evidence examples:

```typescript
expect(createEvidence(manifest404)).toEqual({
    engineType: ErrorTypes.NETWORK_ERROR,
    engineDetails: ErrorDetails.MANIFEST_LOAD_ERROR,
    disposition: 'fatal',
    stage: 'manifest',
    failure: 'http',
    httpStatus: 404,
});

expect(createEvidence(recoverableFragment)).toEqual({
    engineType: ErrorTypes.NETWORK_ERROR,
    engineDetails: ErrorDetails.FRAG_LOAD_ERROR,
    disposition: 'recoverable',
    stage: 'segment',
    failure: 'network',
});
```

Serialize the unsafe-shape evidence and assert it contains none of the secret,
URL, header, text, body, or provider-message sentinels.

- [ ] **Step 2: Replace broad HLS classifier cases with structured expectations**

In `playback-diagnostics.util.spec.ts`, make
`classifyHlsPlaybackIssue` consume the wished-for evidence shape. Cover:

```typescript
expect(
    classifyHlsPlaybackIssue(recoverableFragmentEvidence, metadata)
).toBeNull();

expect(
    classifyHlsPlaybackIssue(fatalManifest404Evidence, metadata)
).toEqual(
    expect.objectContaining({
        code: PlaybackDiagnosticCode.NetworkError,
        httpStatus: 404,
        externalFallbackRecommended: false,
    })
);
```

Add exact codec, decrypt/DRM, media/mux, and unknown cases. Add misleading
provider-string-shaped values to the source metadata URL and prove they cannot
change classification, since the classifier receives no message payload.

Remove HLS expectations that arbitrary error objects, CORS phrases, or
provider messages appear in `details`. Keep native and mpegts.js coverage
unchanged.

- [ ] **Step 3: Run the focused tests to verify RED**

Run:

```bash
NODE_OPTIONS=--experimental-vm-modules \
node node_modules/jest/bin/jest.js \
  --config jest.web-esm.workspace.ts \
  --runTestsByPath \
  libs/ui/playback/src/lib/playback-diagnostics/hls-playback-evidence.util.spec.ts \
  libs/ui/playback/src/lib/playback-diagnostics/playback-diagnostics.util.spec.ts \
  --runInBand
```

Expected: FAIL because no structured evidence creator exists and the current
classifier still accepts broad strings and always returns a diagnostic.

- [ ] **Step 4: Add the evidence model**

In `playback-diagnostics.model.ts`, replace `HlsPlaybackErrorInput` with const
objects and extracted types:

```typescript
export const HlsPlaybackDisposition = {
    Fatal: 'fatal',
    Recoverable: 'recoverable',
} as const;

export const HlsPlaybackStage = {
    Manifest: 'manifest',
    Level: 'level',
    Segment: 'segment',
    Key: 'key',
    Media: 'media',
    Unknown: 'unknown',
} as const;

export const HlsPlaybackFailure = {
    Http: 'http',
    Timeout: 'timeout',
    Network: 'network',
    Access: 'access',
    Unknown: 'unknown',
} as const;
```

Define `HlsPlaybackEvidence` with allowlisted engine type/detail types,
disposition, stage, failure, and optional status. Add optional
`hls?: HlsPlaybackEvidence` to `PlaybackDiagnostic`.

- [ ] **Step 5: Implement exact extraction**

In `hls-playback-evidence.util.ts`:

- validate `type` against `Object.values(ErrorTypes)`, otherwise `unknown`;
- validate `details` against `Object.values(ErrorDetails)`, otherwise
  `ErrorDetails.UNKNOWN`;
- validate only `response.code` as an integer from 100 through 599;
- map stage through readonly sets of exact `ErrorDetails`;
- map timeout and network failure through readonly exact sets;
- prefer timeout, then 4xx/5xx HTTP failure, then network, else unknown;
- return only the six evidence keys and optional `httpStatus`.

Do not read any other `ErrorData` property.

- [ ] **Step 6: Implement exact classification**

In `playback-diagnostics.util.ts`:

- change the HLS classifier input to `HlsPlaybackEvidence`;
- return `null` for `Recoverable`;
- use exact detail sets for incompatible/add-codec and decrypt evidence;
- use exact key-system type/details for DRM;
- use exact network type/failure for network diagnostics;
- use exact media/mux types for decode diagnostics;
- use unknown otherwise;
- retain the evidence and HTTP status through `createPlaybackDiagnostic`.

Remove `HlsPlaybackErrorInput` from `playback-error-patterns.util.ts`.
`normalizeErrorDetails`, `isNetworkFailure`, `isCodecFailure`, and
`isDrmOrEncryptionFailure` remain only where mpegts.js still needs them, or are
deleted when HLS was their only consumer. Do not redesign mpegts.js behavior.

- [ ] **Step 7: Run focused tests to verify GREEN**

Run the focused command from step 3.

Expected: PASS for exact real shapes, unknown values, privacy exclusions,
recoverable suppression, and all unchanged native/mpegts behavior.

- [ ] **Step 8: Commit the evidence contract**

Run:

```bash
git add \
  libs/ui/playback/src/lib/playback-diagnostics/hls-playback-evidence.util.spec.ts \
  libs/ui/playback/src/lib/playback-diagnostics/hls-playback-evidence.util.ts \
  libs/ui/playback/src/lib/playback-diagnostics/playback-diagnostics.model.ts \
  libs/ui/playback/src/lib/playback-diagnostics/playback-diagnostics.util.spec.ts \
  libs/ui/playback/src/lib/playback-diagnostics/playback-diagnostics.util.ts \
  libs/ui/playback/src/lib/playback-diagnostics/playback-error-patterns.util.ts
git commit -m "fix(playback): classify HLS errors from structured evidence"
```

Expected: one contract/classifier commit with its RED/GREEN regressions.

### Task 2: Route HTML5 And ArtPlayer Through The Boundary

**Files:**
- Modify:
  `libs/ui/playback/src/lib/html-video-player/html-video-player-diagnostics.ts`
- Modify:
  `libs/ui/playback/src/lib/html-video-player/html-video-player.component.spec.ts`
- Modify:
  `libs/ui/playback/src/lib/art-player/art-player-source-session.ts`
- Modify:
  `libs/ui/playback/src/lib/art-player/art-player-source-session.spec.ts`
- Modify:
  `libs/ui/playback/src/lib/art-player/art-player.component.spec.ts`

- [ ] **Step 1: Write adapter regressions**

Update HTML5 and ArtPlayer tests first:

- fatal manifest 404 emits `network-error`, stage `manifest`, failure `http`,
  disposition `fatal`, and `httpStatus: 404`;
- recoverable fragment error emits nothing;
- payload sentinels placed in `error`, `reason`, response URL/text/data,
  request headers, and `networkDetails` do not appear in the emitted
  diagnostic JSON;
- stale ArtPlayer HLS callbacks remain ignored after a source change.

Use hls.js-shaped values, not prose-only test objects.

- [ ] **Step 2: Run adapter tests to verify RED**

Run:

```bash
NODE_OPTIONS=--experimental-vm-modules \
node node_modules/jest/bin/jest.js \
  --config jest.web-esm.workspace.ts \
  --runTestsByPath \
  libs/ui/playback/src/lib/html-video-player/html-video-player.component.spec.ts \
  libs/ui/playback/src/lib/art-player/art-player-source-session.spec.ts \
  libs/ui/playback/src/lib/art-player/art-player.component.spec.ts \
  --runInBand
```

Expected: FAIL because adapters still build broad HLS input and retain
arbitrary errors.

- [ ] **Step 3: Use the shared extractor/classifier**

In both adapters:

```typescript
const issue = classifyHlsPlaybackIssue(
    createHlsPlaybackEvidence(data),
    sourceMetadata
);
if (issue) {
    emitPlaybackIssue(issue);
}
```

Remove duplicated `if (!data.fatal)` gates and all copying of `data.error`
messages or objects.

- [ ] **Step 4: Run adapter tests to verify GREEN**

Run the focused command from step 2.

Expected: PASS for HTML5, ArtPlayer, recoverable suppression, privacy
exclusions, and stale-session guards.

- [ ] **Step 5: Commit adapter integration**

Run:

```bash
git add \
  libs/ui/playback/src/lib/html-video-player/html-video-player-diagnostics.ts \
  libs/ui/playback/src/lib/html-video-player/html-video-player.component.spec.ts \
  libs/ui/playback/src/lib/art-player/art-player-source-session.ts \
  libs/ui/playback/src/lib/art-player/art-player-source-session.spec.ts \
  libs/ui/playback/src/lib/art-player/art-player.component.spec.ts
git commit -m "fix(playback): sanitize HLS adapter errors"
```

Expected: one adapter-boundary commit.

### Task 3: Render Only Sanitized HLS Evidence

**Files:**
- Modify:
  `libs/ui/playback/src/lib/web-player-view/web-player-view-diagnostics.utils.ts`
- Modify:
  `libs/ui/playback/src/lib/web-player-view/web-player-view.component.spec.ts`

- [ ] **Step 1: Add the rendered-detail regression**

Create a diagnostic carrying structured manifest-404 evidence and expect its
technical error-details row to equal:

```text
stage=manifest · failure=http · type=networkError · details=manifestLoadError · disposition=fatal · HTTP 404
```

Include credential-shaped source/provider sentinels in fields that the HLS
extractor rejects and assert the banner/details text does not contain them.
Keep the existing direct native `HTTP 404 · networkrequestfailed` expectation.

- [ ] **Step 2: Run the view spec to verify RED**

Run:

```bash
NODE_OPTIONS=--experimental-vm-modules \
node node_modules/jest/bin/jest.js \
  --config jest.web-esm.workspace.ts \
  --runTestsByPath \
  libs/ui/playback/src/lib/web-player-view/web-player-view.component.spec.ts \
  --runInBand
```

Expected: FAIL because the formatter does not render structured HLS evidence.

- [ ] **Step 3: Format HLS evidence deterministically**

In `formatDiagnosticErrorDetails`, prefer `issue.hls` and format only:

```typescript
[
    `stage=${evidence.stage}`,
    `failure=${evidence.failure}`,
    `type=${evidence.engineType}`,
    `details=${evidence.engineDetails}`,
    `disposition=${evidence.disposition}`,
    evidence.httpStatus === undefined ? '' : `HTTP ${evidence.httpStatus}`,
]
```

Filter empty values and join with ` · `. Leave native, mpegts.js, and Shaka
formatting unchanged.

- [ ] **Step 4: Run the view spec to verify GREEN**

Run the focused command from step 2.

Expected: PASS with safe deterministic evidence and unchanged native HTTP
rendering.

- [ ] **Step 5: Commit the UI formatting**

Run:

```bash
git add \
  libs/ui/playback/src/lib/web-player-view/web-player-view-diagnostics.utils.ts \
  libs/ui/playback/src/lib/web-player-view/web-player-view.component.spec.ts
git commit -m "fix(playback): show safe HLS diagnostic evidence"
```

Expected: one focused UI/test commit without new translation keys.

### Task 4: Update Canonical Documentation And Release Notes

**Files:**
- Modify: `docs/architecture/embedded-inline-playback.md`
- Create: `.changes/playback-structured-hls-diagnostics.md`
- Verify only: `CLAUDE.md`
- Verify only: `AGENTS.md`

- [ ] **Step 1: Update the canonical diagnostic contract**

Replace the statement that technical details expose raw HLS information with:

- exact hls.js fields retained;
- stage/failure/disposition mapping;
- recoverable events suppressed;
- status zero/access ambiguity stays unknown/network;
- unsafe HLS fields are neither retained nor rendered;
- HTML5 and ArtPlayer share the same boundary.

Do not add history, probes, failover, Shaka, or mpegts redesign material.

- [ ] **Step 2: Assess living root docs**

Check the shared-player descriptions in `CLAUDE.md` and `AGENTS.md`. Update
both only if their existing claims become stale. If neither describes HLS error
payload details, leave both unchanged and record that assessment.

- [ ] **Step 3: Add the user-facing release note**

Create `.changes/playback-structured-hls-diagnostics.md`:

```markdown
---
type: fix
area: playback
---

HLS failures now use confirmed player evidence such as the failed stage, timeout, and HTTP status. Recoverable retries stay silent, and technical details no longer include raw provider error payloads.
```

Keep the body below 400 characters.

- [ ] **Step 4: Validate Markdown and release-note format**

Run:

```bash
git diff --check
pnpm run release:notes:validate
```

Expected: both commands exit 0.

- [ ] **Step 5: Commit docs and release note**

Run:

```bash
git add \
  docs/architecture/embedded-inline-playback.md \
  .changes/playback-structured-hls-diagnostics.md
git commit -m "docs(playback): document structured HLS evidence"
```

Add `CLAUDE.md` and `AGENTS.md` only if step 2 required synchronized changes.

### Task 5: Complete The Test-Impact Pass

**Files:**
- Verify only: all files changed from `origin/master`

- [ ] **Step 1: Run focused RED/GREEN suites together**

Run:

```bash
NODE_OPTIONS=--experimental-vm-modules \
node node_modules/jest/bin/jest.js \
  --config jest.web-esm.workspace.ts \
  --runTestsByPath \
  libs/ui/playback/src/lib/playback-diagnostics/hls-playback-evidence.util.spec.ts \
  libs/ui/playback/src/lib/playback-diagnostics/playback-diagnostics.util.spec.ts \
  libs/ui/playback/src/lib/html-video-player/html-video-player.component.spec.ts \
  libs/ui/playback/src/lib/art-player/art-player-source-session.spec.ts \
  libs/ui/playback/src/lib/art-player/art-player.component.spec.ts \
  libs/ui/playback/src/lib/web-player-view/web-player-view.component.spec.ts \
  --runInBand
```

Expected: all focused suites pass.

- [ ] **Step 2: Run the affected Nx project tests**

Run:

```bash
pnpm nx test ui-playback --skip-nx-cache
```

Expected: all `ui-playback` suites pass with the new regressions.

- [ ] **Step 3: Run lint and typechecks**

Run:

```bash
pnpm nx lint ui-playback --skip-nx-cache
pnpm exec tsc -p libs/ui/playback/tsconfig.lib.json --noEmit
pnpm run typecheck:web
```

Expected: all commands exit 0.

- [ ] **Step 4: Run repository validation**

Run:

```bash
pnpm run i18n:check
pnpm run release:notes:validate
git diff --check origin/master...HEAD
```

Expected: translations remain aligned, the release note is valid, and the diff
has no whitespace errors.

- [ ] **Step 5: Record the E2E decision**

No E2E is required: this PR does not change navigation, control interactions,
playback engine selection, or retry/fallback workflows. Unit/component tests
exercise the real hls.js public shape, both adapters, terminal suppression,
classification, and rendered technical details.

### Task 6: Run Independent Local Review And Revalidation

**Files:**
- Review only: `origin/master...HEAD`

- [ ] **Step 1: Inspect the complete diff**

Run:

```bash
git status --short --branch
git diff --stat origin/master...HEAD
git diff --check origin/master...HEAD
```

Expected: only the focused design/plan, HLS contract, tests, two adapters,
minimal diagnostic formatting, canonical doc, and release note are present.

- [ ] **Step 2: Dispatch an independent reviewer**

Give a fresh reviewer only the requirements, design path, base SHA, head SHA,
and full diff. Require actionable P0/P1/P2 findings with exact file/line
references, including:

- incorrect hls.js 1.6.16 shape assumptions;
- recoverable-to-terminal regressions;
- unsafe data retention or rendering;
- broad string inference;
- classification precedence errors;
- HTML5/ArtPlayer divergence;
- missing tests, type safety, or scope creep.

The reviewer must not modify files.

- [ ] **Step 3: Resolve findings with TDD**

For each valid finding, add or update the closest regression first, observe the
expected failure, apply the smallest fix, and return the focused suite to
green. Reject invalid findings only with concrete code/type/test evidence.

- [ ] **Step 4: Repeat review after fixes**

If any file changed, re-run the same independent review against the new
`origin/master...HEAD` range until no actionable P0/P1/P2 remains.

- [ ] **Step 5: Re-run final validation**

Repeat every command in Task 5 after the last review change.

Expected: all tests and validations exit 0 on the exact commit range that will
be pushed.

### Task 7: Publish The Ready Pull Request

**Files:**
- Verify only: `.github/pull_request_template.md` if present

- [ ] **Step 1: Commit any final reviewed fixes**

Run:

```bash
git status --short
git diff
git add -u
git commit -m "fix(playback): address structured HLS review findings"
```

Create this commit only when review produced verified changes.

- [ ] **Step 2: Inspect final history and scope**

Run:

```bash
git log --oneline origin/master..HEAD
git diff --stat origin/master...HEAD
git status --short --branch
```

Expected: a clean focused branch.

- [ ] **Step 3: Push the branch**

Run:

```bash
git push -u origin agent/structured-hls-diagnostics
```

Expected: push succeeds without force.

- [ ] **Step 4: Create a ready PR**

Create a non-draft PR targeting `master`:

```text
fix(playback): structure HLS diagnostics
```

The body summarizes:

- exact hls.js evidence and recoverable suppression;
- shared HTML5/ArtPlayer sanitizer;
- safe technical details without raw provider payloads;
- tests and validation commands;
- independent review status.

Link a relevant open issue only if one was found or created. Do not reopen or
close #1159, which PR #1314 already resolved.

- [ ] **Step 5: Verify PR state**

Run:

```bash
gh pr view --json number,title,state,isDraft,baseRefName,headRefName,url,body
```

Expected: `OPEN`, `isDraft: false`, base `master`, head
`agent/structured-hls-diagnostics`.