test(hls): [PKG-HLS-SDK-01] retain controller evidence across page crashes

test/browser/README.md

@@ -146,6 +146,16 @@ one explicit capability/error-cleanup test covers that limitation and its 14 pla
 skipped with a reason. Chromium/Firefox run the full four-combination HLS matrix. This is not
 Safari playback approval; see [HLS validation](../../refactor/hls-validation.md) for evidence and open gates.
 
+The standalone `refactor/scripts/hls-sdk-diagnostic.mjs --controller-state` option
+installs `helpers/hls-controller-state.js` only for a fixed-SDK diagnostic. It reads
+the 1.5.17 buffer dictionary or 1.7.2 buffer array and the controllers' shared
+fragment tracker, keeping cyclic loaded objects out of JSON. The 1.5 audio stream
+controller is located by playlistType in networkControllers. Observations are also
+copied asynchronously into a bounded Node queue, retaining received events after
+a page crash; the last undelivered events may be lost. Default diagnostics
+do not enable this observer. A missing or errored snapshot is incomplete evidence;
+neither transient empty media ranges nor repeated success resolves HLS-PLAYBACK-01.
+
 `playback.spec.js` tests published/current core with current chapter, real decoded frame colors,
 media time advancing, pause, seek, source change to the existing docs video, destroy and real
 HTTP failure. These are initial smoke contracts, not full chapter or lifecycle coverage.

test/helpers/hls-controller-state.js

@@ -0,0 +1,35 @@
+// Self-contained so the fixed-SDK diagnostic can install this function in a page.
+// These private fields are evidence only, never dependencies of a player plugin.
+export function snapshotHlsControllers(hls) {
+  const ranges = source => source && Array.from({ length: source.length }, (_, index) => [source.start(index), source.end(index)])
+  const fragment = value => value && ({ sn: value.sn, level: value.level, type: value.type, start: value.start, duration: value.duration })
+  const controller = value => value && ({
+    state: value.state,
+    level: value.level,
+    nextLoadPosition: value.nextLoadPosition,
+    altAudio: value.altAudio,
+    mediaBuffer: value.mediaBuffer === value.videoBuffer && value.videoBuffer ? 'video' : value.mediaBuffer === value.media && value.media ? 'media' : 'other',
+    buffered: ranges(value.mediaBuffer?.buffered),
+    current: fragment(value.fragCurrent),
+    previous: fragment(value.fragPrevious),
+  })
+  try {
+    const audio = hls?.audioStreamController || hls?.networkControllers?.find(value => value.playlistType === 'audio')
+    const tracker = hls?.streamController?.fragmentTracker || audio?.fragmentTracker
+    const bufferController = hls?.bufferController
+    const buffers = Array.isArray(bufferController?.sourceBuffers)
+      ? bufferController.sourceBuffers
+      : bufferController?.sourceBuffer && Object.entries(bufferController.sourceBuffer)
+    return {
+      main: controller(hls?.streamController),
+      audio: controller(audio),
+      mediaSourceState: hls?.bufferController?.mediaSource?.readyState,
+      buffers: buffers?.map(([type, source]) => ({ type, updating: source?.updating, buffered: ranges(source?.buffered) })),
+      endList: tracker && Object.fromEntries(Object.entries(tracker.endListFragments || {}).map(([type, entity]) => [type, { fragment: fragment(entity.body), buffered: !!entity.buffered, loaded: !!entity.loaded }])),
+      tracked: tracker && Object.entries(tracker.fragments || {}).map(([key, entity]) => ({ key, buffered: !!entity?.buffered, loaded: !!entity?.loaded })),
+    }
+  }
+  catch (error) {
+    return { diagnosticError: String(error) }
+  }
+}