From 0d56082c5414808596b8289bd5bf5f3abfca5738 Mon Sep 17 00:00:00 2001
From: thePR0M3TH3AN <53631862+PR0M3TH3AN@users.noreply.github.com>
Date: Wed, 24 Sep 2025 15:20:40 -0400
Subject: [PATCH] docs: document magnet normalization behavior

---
 js/magnetUtils.js | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/js/magnetUtils.js b/js/magnetUtils.js
index 1bc0b54f..29057dc3 100644
--- a/js/magnetUtils.js
+++ b/js/magnetUtils.js
@@ -81,6 +81,21 @@ export function safeDecodeMagnet(value) {
   return decoded;
 }
 
+/**
+ * Normalize a magnet URI while preserving legacy payload quirks and augmenting it
+ * for browser playback.
+ *
+ * Key behaviors:
+ * - Accepts bare info-hash strings and promotes them to full `magnet:?xt=urn:btih:` links.
+ * - Leaves the existing `xt` payload untouched—no percent re-encoding or normalization
+ *   beyond decoding legacy `%3A` segments.
+ * - Only appends browser-safe WSS trackers in addition to whatever the caller provides.
+ * - Skips insecure `http:` web seeds unless the application itself is running over HTTP.
+ *
+ * Note: `didChange` may be reported even if the resulting magnet string is textually
+ * identical to the input. Callers should not rely on `didChange` to detect a modified
+ * URI.
+ */
 export function normalizeAndAugmentMagnet(
   rawValue,
   {