From 80230b0d471d1dcf24fe3ce4a1989fbfa9745c50 Mon Sep 17 00:00:00 2001
From: 4gray <serega05@gmail.com>
Date: Thu, 30 Jul 2026 09:47:32 +0200
Subject: [PATCH] docs(playback): document native error evidence

---
 .changes/playback-accurate-source-errors.md          |  7 +++++++
 docs/architecture/embedded-inline-playback.md        |  7 +++++++
 ...026-07-30-accurate-native-playback-diagnostics.md | 12 ++++++------
 3 files changed, 20 insertions(+), 6 deletions(-)
 create mode 100644 .changes/playback-accurate-source-errors.md

diff --git a/.changes/playback-accurate-source-errors.md b/.changes/playback-accurate-source-errors.md
new file mode 100644
index 000000000..5ed9b8a70
--- /dev/null
+++ b/.changes/playback-accurate-source-errors.md
@@ -0,0 +1,7 @@
+---
+type: fix
+area: playback
+issues: [1159]
+---
+
+Unavailable streams no longer appear as unsupported codecs. When Video.js exposes a server error such as HTTP 404, the player shows that status; otherwise ambiguous source errors remain unidentified instead of guessing.
diff --git a/docs/architecture/embedded-inline-playback.md b/docs/architecture/embedded-inline-playback.md
index 3acd31898..1ad8ef2f8 100644
--- a/docs/architecture/embedded-inline-playback.md
+++ b/docs/architecture/embedded-inline-playback.md
@@ -328,6 +328,13 @@ Supported diagnostic codes are:
 - `drm-or-encryption`
 - `unknown-playback-error`
 
+Native `MediaError` code 4 alone is not codec evidence. A source with a known
+browser-incompatible container remains `unsupported-container`; otherwise, a
+code 4 error without stronger evidence is `unknown-playback-error`. An explicit
+Video.js HTTP error is `network-error` and shows its status. Because an HTTP
+status is server/network evidence rather than decoding evidence, external
+decoding is not presented as a likely fix.
+
 `network-error` is reserved for provider/network loading failures. Browser security failures such as CORS, mixed content, Content Security Policy, and private-network-access blocks are classified as `browser-access-error` so the UI can explain that the browser player was blocked before playback reached decoding.
 
 mpegts.js `Early-EOF` failures on MPEG-TS streams are classified as `media-decode-error` instead of generic `network-error`. These failures usually mean the fetch stream ended before mpegts.js expected a complete transport stream, and external players may still handle the same URL more tolerant of short reads or malformed TS boundaries.
diff --git a/docs/superpowers/plans/2026-07-30-accurate-native-playback-diagnostics.md b/docs/superpowers/plans/2026-07-30-accurate-native-playback-diagnostics.md
index c930c8cef..24ba01e4e 100644
--- a/docs/superpowers/plans/2026-07-30-accurate-native-playback-diagnostics.md
+++ b/docs/superpowers/plans/2026-07-30-accurate-native-playback-diagnostics.md
@@ -70,7 +70,7 @@ it('classifies an explicit Video.js HTTP failure as a network error', () => {
             code: 4,
             message: 'The media could not be loaded',
             status: 404,
-            metadata: { errorType: 'NETWORK_REQUEST_ERR' },
+            metadata: { errorType: 'networkrequestfailed' },
         },
         createPlaybackSourceMetadata({
             url: 'https://example.com/missing/playlist.m3u8',
@@ -83,7 +83,7 @@ it('classifies an explicit Video.js HTTP failure as a network error', () => {
         expect.objectContaining({
             code: PlaybackDiagnosticCode.NetworkError,
             httpStatus: 404,
-            nativeErrorType: 'NETWORK_REQUEST_ERR',
+            nativeErrorType: 'networkrequestfailed',
             externalFallbackRecommended: false,
         })
     );
@@ -309,7 +309,7 @@ it('preserves safe Video.js HTTP context in playback diagnostics', () => {
         code: 4,
         message: 'The media could not be loaded',
         status: 404,
-        metadata: { errorType: 'NETWORK_REQUEST_ERR' },
+        metadata: { errorType: 'networkrequestfailed' },
     };
 
     harness.emit('error');
@@ -320,7 +320,7 @@ it('preserves safe Video.js HTTP context in playback diagnostics', () => {
             source: 'native',
             sourceUrl: 'https://example.test/missing/playlist.m3u8',
             httpStatus: 404,
-            nativeErrorType: 'NETWORK_REQUEST_ERR',
+            nativeErrorType: 'networkrequestfailed',
             externalFallbackRecommended: false,
         })
     );
@@ -419,7 +419,7 @@ function createHttpDiagnostic(): PlaybackDiagnostic {
         httpStatus: 404,
         nativeErrorCode: 4,
         nativeErrorMessage: 'The media could not be loaded',
-        nativeErrorType: 'NETWORK_REQUEST_ERR',
+        nativeErrorType: 'networkrequestfailed',
         externalFallbackRecommended: false,
     };
 }
@@ -450,7 +450,7 @@ it('renders explicit HTTP evidence without recommending an external player', ()
         expect.arrayContaining([
             {
                 labelKey: 'PLAYBACK_DIAGNOSTICS.DETAIL_ERROR_DETAILS',
-                value: 'HTTP 404 · NETWORK_REQUEST_ERR',
+                value: 'HTTP 404 · networkrequestfailed',
             },
         ])
     );