From b52e767f86b624a7151674bf41025622cf118084 Mon Sep 17 00:00:00 2001
From: thePR0M3TH3AN <53631862+PR0M3TH3AN@users.noreply.github.com>
Date: Wed, 24 Sep 2025 15:23:24 -0400
Subject: [PATCH] Document torrent playback normalization details

---
 js/playbackUtils.js | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/js/playbackUtils.js b/js/playbackUtils.js
index a670effe..53c4c57b 100644
--- a/js/playbackUtils.js
+++ b/js/playbackUtils.js
@@ -8,6 +8,30 @@ import {
 const HEX_INFO_HASH = /^[0-9a-f]{40}$/i;
 const MAGNET_URI = /^magnet:\?/i;
 
+/**
+ * Normalizes torrent related playback inputs into a canonical magnet payload.
+ *
+ * The function first trims and safely decodes the incoming `magnet` string so
+ * that URL encoded magnets become plain text before processing. Bare info hash
+ * strings are tolerated: whenever the caller supplies an info hash (either via
+ * the `infoHash` field or a magnet that looks like one) it gets promoted to a
+ * full magnet URI so downstream WebTorrent code can consume it directly.
+ *
+ * When the normalized output differs from the original magnet input (for
+ * example due to whitespace/encoding fixes or tracker augmentation) the
+ * original candidate is exposed through `fallbackMagnet`. Callers can surface
+ * that value if a later refactor breaks magnet normalization.
+ *
+ * The returned flags communicate provenance: `provided` indicates that some
+ * torrent-related input was supplied, while `usedInfoHash` is only `true` when
+ * the normalized magnet was derived from an info hash instead of an already
+ * well-formed magnet URI.
+ *
+ * Web seeds coming from the `url` parameter are forwarded to
+ * `normalizeAndAugmentMagnet` via the `webSeed` option. Refactors must preserve
+ * that flow (even if the parameter name changes) so hosted URLs continue to
+ * populate `ws=` hints automatically.
+ */
 export function deriveTorrentPlaybackConfig({
   magnet = "",
   infoHash = "",