playlist-data-engine 1.7.2 → 1.8.0

package/dist/gateway-CDMPqFEH.js

@@ -0,0 +1,1320 @@
+import { a as $ } from "./arweaveGatewayManager-DDSO5sLJ.js";
+class c {
+  /**
+   * Extract primary (compressed) audio URL with priority:
+   * 1. mp3_url (Standard web audio - preferred)
+   * 2. lossy_audio (Compressed)
+   * 3. audio_url (Explicit audio field)
+   * 4. audio (Bare audio field — some platforms use this instead of audio_url)
+   * 5. lossless_audio (High fidelity - larger files)
+   * 6. animation_url (OpenSea standard - often audio, but could be video)
+   * 7. multimedia_url (Alternative media field)
+   */
+  static extractAudioUrl(t) {
+    const e = ["mp3_url", "mp3Url", "lossy_audio", "lossyAudio", "audio_url", "audioUrl", "audio", "lossless_audio", "losslessAudio", "animation_url", "animationUrl", "multimedia_url", "multimediaUrl"];
+    for (const r of e)
+      if (t[r] && typeof t[r] == "string")
+        return t[r];
+    return null;
+  }
+  /**
+   * Extract the highest-fidelity audio URL the track offers — best
+   * available, not a guarantee. A track whose only source is an mp3 gets
+   * that back rather than null.
+   */
+  static extractAudioUrlLossless(t) {
+    const e = ["lossless_audio", "losslessAudio", "wav_url", "wavUrl", "flac_url", "flacUrl", "audio_url", "audioUrl"];
+    for (const r of e)
+      if (t[r] && typeof t[r] == "string")
+        return t[r];
+    return null;
+  }
+  /**
+   * Extract image URL with priority:
+   *
+   * Flat fields:
+   * 1. image_small (Preferred for performance)
+   * 2. image (Standard)
+   * 3. image_url (Explicit image URL variant)
+   * 4. image_large (Fallback)
+   * 5. image_uri (URI variant)
+   * 6. image_preview (Preview variant)
+   * 7. image_thumb (Last resort)
+   *
+   * Nested object fields (checked if no flat match found):
+   * 8. artwork.uri (Nina Protocol structured artwork)
+   * 9. project.artwork.uri (Project-level artwork)
+   * 10. primaryMedia.uri (Primary media field)
+   */
+  static extractImageUrl(t) {
+    const e = ["image_small", "imageSmall", "image", "image_large", "imageLarge", "image_thumb", "imageThumb", "image_url", "imageUrl", "image_uri", "imageUri", "image_preview", "imagePreview"];
+    for (const i of e)
+      if (t[i] && typeof t[i] == "string")
+        return t[i];
+    const r = [
+      this.extractNestedUri(t, "artwork", "uri"),
+      this.extractNestedUri(t, "project", "artwork", "uri"),
+      this.extractNestedUri(t, "primaryMedia", "uri")
+    ];
+    for (const i of r)
+      if (i) return i;
+    return null;
+  }
+  /**
+   * Extract thumbnail image URL directly from image_thumb fields.
+   * Unlike extractImageUrl, this specifically targets thumbnail fields only.
+   * Priority: image_thumb_url > image_thumb
+   */
+  static extractImageThumbUrl(t) {
+    return t.image_thumb_url && typeof t.image_thumb_url == "string" ? t.image_thumb_url : t.image_thumb && typeof t.image_thumb == "string" ? t.image_thumb : null;
+  }
+  /**
+   * Extract name/title with priority (see specs/001-core-engine/SPEC.md):
+   * 1. name
+   * 2. title
+   */
+  static extractTitle(t) {
+    return t.name && typeof t.name == "string" ? t.name : t.title && typeof t.title == "string" ? t.title : null;
+  }
+  /**
+   * Extract artist with priority (see specs/001-core-engine/SPEC.md):
+   * 1. artist
+   * 2. created_by
+   * 3. minter
+   * 4. OpenSea-style attributes array with trait_type "Artist"
+   */
+  static extractArtist(t) {
+    const e = ["artist", "artist_name", "artistName", "album_artist", "albumArtist", "created_by", "createdBy", "minter"];
+    for (const r of e)
+      if (t[r] && typeof t[r] == "string")
+        return t[r];
+    if (Array.isArray(t.attributes)) {
+      const r = t.attributes.find(
+        (i) => i.trait_type?.toLowerCase() === "artist" && i.value !== void 0
+      );
+      if (r && typeof r.value == "string")
+        return r.value;
+    }
+    return null;
+  }
+  /**
+   * Parse metadata string to JSON object
+   * Handles stringified JSON with error handling
+   */
+  static parseMetadata(t) {
+    if (!t)
+      return null;
+    if (typeof t == "object" && !Array.isArray(t))
+      return t;
+    if (typeof t == "string")
+      try {
+        const e = JSON.parse(t);
+        if (typeof e == "object" && !Array.isArray(e))
+          return e;
+      } catch (e) {
+        return console.warn("Failed to parse metadata:", e), null;
+      }
+    return null;
+  }
+  /**
+   * Extract genre with support for string or array formats.
+   * Sources are checked in priority order; first non-empty wins:
+   * - `genre` field as a string
+   * - `genre` field as an array (first element)
+   * - OpenSea `attributes` array with `trait_type` of "genre" (case-insensitive)
+   * - `attributes` as an object keyed by trait name (e.g. `attributes.Genre`)
+   * - malformed `attribute ` key (literal trailing space) with `.genre`
+   * Stays strict: only fields literally named "genre" are considered
+   * (no fallback to `category` or similar).
+   */
+  static extractGenre(t) {
+    if (typeof t.genre == "string")
+      return t.genre;
+    if (Array.isArray(t.genre) && t.genre.length > 0) {
+      const r = t.genre[0];
+      return typeof r == "string" ? r : "";
+    }
+    if (Array.isArray(t.attributes)) {
+      const r = t.attributes.find(
+        (i) => i.trait_type?.toLowerCase() === "genre" && i.value !== void 0
+      );
+      if (r) {
+        if (typeof r.value == "string")
+          return r.value;
+        if (Array.isArray(r.value) && r.value.length > 0) {
+          const i = r.value[0];
+          return typeof i == "string" ? i : "";
+        }
+      }
+    }
+    if (t.attributes && typeof t.attributes == "object" && !Array.isArray(t.attributes)) {
+      const r = t.attributes;
+      for (const i of Object.keys(r))
+        if (i.toLowerCase() === "genre" && typeof r[i] == "string")
+          return r[i];
+    }
+    const e = t["attribute "];
+    if (e && typeof e == "object" && !Array.isArray(e)) {
+      const r = e.genre;
+      if (typeof r == "string")
+        return r;
+    }
+    return "";
+  }
+  /**
+   * Extract tags from track metadata, normalized to a deduped,
+   * lowercased, trimmed string[] with empties removed.
+   * Sources (concatenated, then deduped):
+   * - `tags` field as an array, or a single comma-separated string
+   * - `properties.tags` array (when `properties` is an object)
+   * - OpenSea `attributes` array with `trait_type` of "tag"/"tags" (case-insensitive)
+   * - `attributes` as an object keyed by trait name (e.g. `attributes.Tags`)
+   */
+  static extractTags(t) {
+    const e = [];
+    if (Array.isArray(t.tags) ? e.push(...t.tags) : typeof t.tags == "string" && e.push(...t.tags.split(",")), t.properties && typeof t.properties == "object" && !Array.isArray(t.properties)) {
+      const r = t.properties.tags;
+      Array.isArray(r) ? e.push(...r) : typeof r == "string" && e.push(...r.split(","));
+    }
+    if (Array.isArray(t.attributes))
+      for (const r of t.attributes) {
+        if (!r || typeof r != "object") continue;
+        const i = r.trait_type;
+        if (typeof i == "string" && i.toLowerCase().match(/^tags?$/)) {
+          const n = r.value;
+          Array.isArray(n) ? e.push(...n) : typeof n == "string" && e.push(...n.split(","));
+        }
+      }
+    else if (t.attributes && typeof t.attributes == "object") {
+      const r = t.attributes;
+      for (const i of Object.keys(r))
+        if (i.toLowerCase().match(/^tags?$/)) {
+          const n = r[i];
+          Array.isArray(n) ? e.push(...n) : typeof n == "string" && e.push(...n.split(","));
+        }
+    }
+    return c.normalizeTags(e);
+  }
+  /**
+   * Extract track description with priority:
+   *
+   * Flat fields:
+   * 1. description (Canonical)
+   * 2. track_description / trackDescription (Explicit track-scoped variants)
+   * 3. description_text / descriptionText (Text-suffixed variants)
+   * 4. desc / blurb (Short-form variants)
+   *
+   * Then:
+   * 5. OpenSea-style attributes array with trait_type "description" (case-insensitive)
+   * 6. Deep search fallback — breadth-first walk of nested objects for the
+   *    shallowest key matching /description/i (catches properties.description
+   *    and any other nested home for the field). Arrays are skipped: items
+   *    inside arrays (stems, mixes, attribute entries) carry their own scoped
+   *    descriptions, not the track's.
+   */
+  static extractDescription(t) {
+    const e = ["description", "track_description", "trackDescription", "description_text", "descriptionText", "desc", "blurb"];
+    for (const r of e)
+      if (t[r] && typeof t[r] == "string")
+        return t[r];
+    if (Array.isArray(t.attributes)) {
+      const r = t.attributes.find(
+        (i) => i.trait_type?.toLowerCase() === "description" && typeof i.value == "string"
+      );
+      if (r && typeof r.value == "string")
+        return r.value;
+    }
+    return c.deepFindString(t, /description/i);
+  }
+  /**
+   * Extract album description — one of the bonus flavors. Priority:
+   *
+   * Flat fields:
+   * 1. album_description (Canonical)
+   * 2. albumDescription (camelCase variant)
+   *
+   * Nested object fields (only when `album` is an object — it is just as
+   * often a plain name string, which yields nothing here):
+   * 3. Deep search scoped to the album object — catches album.description,
+   *    album.liner_notes, album.notes and friends without ever misattributing
+   *    the track's own description to the album.
+   */
+  static extractAlbumDescription(t) {
+    const e = ["album_description", "albumDescription"];
+    for (const i of e)
+      if (t[i] && typeof t[i] == "string")
+        return t[i];
+    const r = t.album;
+    return r && typeof r == "object" && !Array.isArray(r) ? c.deepFindString(r, /description|liner|notes/i) : null;
+  }
+  /**
+   * Extract artist description — one of the bonus flavors. Priority:
+   *
+   * Flat fields:
+   * 1. artist_description (Canonical)
+   * 2. artistDescription (camelCase variant)
+   * 3. artist_bio / artistBio (Bio variants)
+   *
+   * Nested object fields (only when `artist` is an object — it is just as
+   * often a plain name string, which yields nothing here):
+   * 4. Deep search scoped to the artist object — catches artist.description,
+   *    artist.bio, artist.about and friends without ever misattributing the
+   *    track's own description to the artist.
+   */
+  static extractArtistDescription(t) {
+    const e = ["artist_description", "artistDescription", "artist_bio", "artistBio"];
+    for (const i of e)
+      if (t[i] && typeof t[i] == "string")
+        return t[i];
+    const r = t.artist;
+    return r && typeof r == "object" && !Array.isArray(r) ? c.deepFindString(r, /description|bio|about/i) : null;
+  }
+  /**
+   * Breadth-first search for the shallowest string value whose key matches
+   * the given pattern. First match in breadth order wins: shallowest level,
+   * then key order. Objects are descended (arrays skipped), depth-capped so
+   * pathological metadata blobs stay cheap.
+   */
+  static deepFindString(t, e, r = 5) {
+    const i = /* @__PURE__ */ new Set(), n = [{ node: t, depth: 0 }];
+    for (; n.length > 0; ) {
+      const { node: u, depth: o } = n.shift();
+      for (const a of Object.keys(u)) {
+        const l = u[a];
+        if (typeof l == "string" && l && e.test(a))
+          return l;
+      }
+      if (!(o >= r))
+        for (const a of Object.keys(u)) {
+          const l = u[a];
+          l && typeof l == "object" && !Array.isArray(l) && !i.has(l) && (i.add(l), n.push({ node: l, depth: o + 1 }));
+        }
+    }
+    return null;
+  }
+  /**
+   * Normalize a list of raw tag values into a deduped, lowercased,
+   * trimmed string[] with empties removed.
+   */
+  static normalizeTags(t) {
+    const e = /* @__PURE__ */ new Set();
+    for (const r of t) {
+      if (r == null) continue;
+      const i = String(r).trim().toLowerCase();
+      i && e.add(i);
+    }
+    return Array.from(e);
+  }
+  static convertAttributes(t) {
+    if (!Array.isArray(t))
+      return null;
+    const e = {};
+    for (const r of t)
+      r.trait_type && r.value !== void 0 && (e[r.trait_type] = r.value);
+    return Object.keys(e).length > 0 ? e : null;
+  }
+  /**
+   * Safely extract a URI string from a nested object path.
+   * e.g. extractNestedUri(data, 'project', 'artwork', 'uri') => data.project.artwork.uri
+   */
+  static extractNestedUri(t, ...e) {
+    let r = t;
+    for (const i of e)
+      if (r && typeof r == "object" && !Array.isArray(r))
+        r = r[i];
+      else
+        return null;
+    return typeof r == "string" ? r : null;
+  }
+}
+function _e(s) {
+  if (!s || !s.metadata) return null;
+  if (typeof s.metadata == "string")
+    try {
+      const t = JSON.parse(s.metadata);
+      return typeof t == "object" && t !== null && !Array.isArray(t) ? t : null;
+    } catch {
+      return null;
+    }
+  return typeof s.metadata == "object" && !Array.isArray(s.metadata) ? s.metadata : null;
+}
+function A(s) {
+  const t = { stems: [], mixes: [], hasExtras: !1 };
+  if (!s) return t;
+  const e = V(s), r = Z(s), i = typeof s.vrm == "string" ? s.vrm : void 0, n = K(s.lyrics), u = S(s.visualizer), o = S(s.video), a = Q(s.merch), l = J(s.credits), f = typeof s.midi == "string" ? s.midi : void 0, d = typeof s.step_mania == "string" ? s.step_mania : void 0, m = typeof s.clone_hero == "string" ? s.clone_hero : void 0, p = typeof s.external_url == "string" ? s.external_url : void 0;
+  return {
+    hasExtras: e.length > 0 || r.length > 0 || !!i || !!n || !!u || !!o || !!a || !!l || !!f || !!d || !!m || !!p,
+    ...e.length > 0 ? { stems: e } : {},
+    ...r.length > 0 ? { mixes: r } : {},
+    ...i ? { vrm: i } : {},
+    ...n ? { lyrics: n } : {},
+    ...u ? { visualizer: u } : {},
+    ...o ? { video: o } : {},
+    ...a ? { merch: a } : {},
+    ...l ? { credits: l } : {},
+    ...f ? { midi: f } : {},
+    ...d ? { step_mania: d } : {},
+    ...m ? { clone_hero: m } : {},
+    ...p ? { external_url: p } : {}
+  };
+}
+const w = ["audio/wav", "audio/x-wav", "audio/flac"];
+function k(s, t, e) {
+  const r = t?.["Selected Mix"], i = typeof s == "string" && s || typeof r == "string" && r || null;
+  if (!i || i === "default") return null;
+  const n = (e ?? []).filter((l) => l.name === i);
+  if (n.length === 0) return null;
+  const u = (l) => w.includes((l.mime_type ?? "").toLowerCase()), o = n.find(u), a = n.find((l) => !u(l)) ?? n[0];
+  return {
+    name: i,
+    ...a?.uri ? { audio_url: a.uri } : {},
+    ...o?.uri && o.uri !== a?.uri ? { audio_url_lossless: o.uri } : {}
+  };
+}
+function ve(s, t, e) {
+  if (!s || !t) return null;
+  const r = C(s, t, e?.caseInsensitive !== !1, e?.aliases !== !1);
+  return r.length > 0 ? I(r, e?.prefer ?? "lossy") : null;
+}
+function I(s, t = "lossy") {
+  if (!s || s.length === 0) return null;
+  if (s.length === 1) return s[0];
+  const e = t === "lossy" ? ["audio/mpeg", "audio/wav", "audio/flac"] : ["audio/wav", "audio/flac", "audio/mpeg"];
+  for (const r of e) {
+    const i = s.find((n) => M(n.mime_type) === r);
+    if (i) return i;
+  }
+  return s[0];
+}
+function Ae(s) {
+  if (!s || !Array.isArray(s)) return [];
+  const t = /* @__PURE__ */ new Map();
+  for (const e of s) {
+    const r = e.name.trim().toLowerCase(), i = t.get(r);
+    i ? i.push(e) : t.set(r, [e]);
+  }
+  return Array.from(t.values()).map((e) => ({
+    name: e[0].name,
+    mixes: e
+  }));
+}
+async function b(s, t) {
+  if (!s) return null;
+  const e = s, r = e.uri ?? e.audio_url ?? e.audio_url_lossless;
+  if (!r) return null;
+  let i = r;
+  if (t?.followMetadata !== !1 && X(s, r)) {
+    const n = await q(r, t?.fetchTimeoutMs);
+    if (!n) return null;
+    i = n;
+  }
+  if (t?.resolveUrl === !1) return i;
+  try {
+    return await $.resolveUrl(i);
+  } catch {
+    return null;
+  }
+}
+async function xe(s, t, e) {
+  const r = s.extras?.mixes;
+  if (!r || r.length === 0 || !t) return null;
+  let i = C(r, t, !0, e?.aliases !== !1);
+  if (i.length === 0) return null;
+  if (e?.conditionsContext) {
+    const f = re(
+      { hasExtras: s.extras?.hasExtras ?? !0, mixes: r },
+      e.conditionsContext
+    ), d = new Set(f.filter((m) => m.allMet).map((m) => m.mix.name));
+    if (i = i.filter((m) => d.has(m.name)), i.length === 0) return null;
+  }
+  const n = I(i, e?.prefer ?? "lossy");
+  if (!n || !n.uri) return null;
+  const u = {
+    resolveUrl: e?.resolveUrl,
+    followMetadata: e?.followMetadata
+  }, o = await b(n, u);
+  if (!o) return null;
+  const a = i.find(W), l = a && a !== n && a.uri ? await b(a, u) : void 0;
+  return {
+    ...s,
+    audio_url: o,
+    audio_url_lossless: l && l !== o ? l : void 0,
+    selected_mix: n.name
+  };
+}
+const j = ["application/json", "application/ld+json"], B = {
+  "audio/x-wav": "audio/wav",
+  "audio/wave": "audio/wav",
+  "audio/vnd.wave": "audio/wav",
+  "audio/x-flac": "audio/flac",
+  "audio/mp3": "audio/mpeg",
+  "audio/mpeg3": "audio/mpeg"
+};
+function M(s) {
+  const t = (s ?? "").trim().toLowerCase();
+  return B[t] ?? t;
+}
+function W(s) {
+  return w.includes(M(s.mime_type));
+}
+function H(s, t, e) {
+  if (!s || !t) return [];
+  const r = (n) => e ? n.trim().toLowerCase() : n.trim(), i = r(t);
+  return s.filter((n) => r(n.name) === i);
+}
+const Y = [
+  ["no vocals", "instrumental"],
+  ["vocals only", "acapella"],
+  ["vocal only", "acapella"],
+  ["a cappella", "acapella"],
+  ["tv mix", "karaoke"],
+  ["tv version", "karaoke"],
+  ["karaoke version", "karaoke"],
+  ["karaoke mix", "karaoke"]
+], z = {
+  inst: "instrumental",
+  instr: "instrumental",
+  instrument: "instrumental",
+  instrumentals: "instrumental",
+  aca: "acapella",
+  acap: "acapella",
+  acappella: "acapella",
+  cappella: "acapella",
+  vox: "acapella",
+  vocal: "acapella",
+  vocals: "acapella",
+  rmx: "remix",
+  tvmix: "karaoke",
+  tv: "karaoke",
+  karoake: "karaoke"
+};
+function E(s) {
+  let t = " " + s.toLowerCase().replace(/[^a-z0-9\s]/g, " ").replace(/\s+/g, " ").trim() + " ";
+  for (const [e, r] of Y)
+    t = t.split(" " + e + " ").join(" " + r + " ");
+  return t.trim().split(" ").filter(Boolean).map((e) => z[e] ?? e);
+}
+function C(s, t, e, r) {
+  const i = H(s, t, e);
+  if (i.length > 0 || !r || !e) return i;
+  const n = E(t);
+  return n.length === 0 ? [] : s.filter((u) => {
+    const o = E(u.name);
+    return n.every((a) => o.includes(a));
+  });
+}
+function X(s, t) {
+  const e = ("mime_type" in s ? s.mime_type : "") ?? "";
+  return j.includes(e.toLowerCase()) ? !0 : e ? !1 : t.split(/[?#]/)[0].toLowerCase().endsWith(".json");
+}
+async function q(s, t = 1e4) {
+  const e = new AbortController(), r = setTimeout(() => e.abort(), t);
+  try {
+    const i = await fetch(s, { signal: e.signal });
+    if (!i.ok) return null;
+    const n = c.parseMetadata(await i.text());
+    return n ? c.extractAudioUrl(n) : null;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(r);
+  }
+}
+function K(s) {
+  if (s) {
+    if (typeof s == "string") return { text: s };
+    if (typeof s == "object" && !Array.isArray(s)) {
+      const t = s;
+      return { text: typeof t.text == "string" ? t.text : void 0 };
+    }
+  }
+}
+function S(s) {
+  if (!s || typeof s != "object" || Array.isArray(s)) return;
+  const t = s;
+  if (typeof t.uri == "string")
+    return {
+      uri: t.uri,
+      mime_type: typeof t.mime_type == "string" ? t.mime_type : void 0
+    };
+}
+function Q(s) {
+  if (!s || typeof s != "object" || Array.isArray(s)) return;
+  const t = s;
+  if (typeof t.uri == "string")
+    return {
+      uri: t.uri,
+      mime_type: typeof t.mime_type == "string" ? t.mime_type : void 0,
+      type: typeof t.type == "string" ? t.type : void 0
+    };
+}
+function J(s) {
+  if (!Array.isArray(s)) return;
+  const t = [];
+  for (const e of s)
+    if (e && typeof e == "object") {
+      const r = e;
+      typeof r.name == "string" && typeof r.credit == "string" && t.push({ name: r.name, credit: r.credit });
+    }
+  return t.length > 0 ? t : void 0;
+}
+function V(s) {
+  const t = s.stems;
+  if (!Array.isArray(t)) return [];
+  const e = [];
+  for (const r of t)
+    if (r && typeof r == "object") {
+      const i = r;
+      e.push({
+        name: typeof i.name == "string" ? i.name : "",
+        uri: typeof i.uri == "string" ? i.uri : void 0,
+        mime_type: typeof i.mime_type == "string" ? i.mime_type : void 0
+      });
+    }
+  return e;
+}
+function Z(s) {
+  const t = s.mixes;
+  if (!Array.isArray(t)) return [];
+  const e = [];
+  for (const r of t)
+    if (r && typeof r == "object") {
+      const i = r, n = ee(i.name), u = te(i.conditions);
+      e.push({
+        name: n || "",
+        uri: typeof i.uri == "string" ? i.uri : void 0,
+        mime_type: typeof i.mime_type == "string" ? i.mime_type : void 0,
+        conditions: u
+      });
+    }
+  return e;
+}
+function ee(s) {
+  if (typeof s == "string") return s;
+  if (s && typeof s == "object" && !Array.isArray(s)) {
+    const t = s;
+    if (typeof t.value == "string") return t.value;
+  }
+  return "";
+}
+function te(s) {
+  if (!Array.isArray(s)) return [];
+  const t = [];
+  for (const e of s)
+    if (e && typeof e == "object") {
+      const r = e;
+      typeof r.type == "string" && (typeof r.value == "string" || typeof r.value == "number" || typeof r.value == "boolean") && t.push({ type: r.type, value: String(r.value) });
+    }
+  return t;
+}
+function re(s, t) {
+  const e = [], r = /* @__PURE__ */ new Date();
+  for (const i of s.mixes || []) {
+    if (i.conditions.length === 0) {
+      e.push({
+        mix: i,
+        conditions: [],
+        allMet: !0,
+        unmetConditions: []
+      });
+      continue;
+    }
+    const n = [], u = [];
+    for (const o of i.conditions) {
+      const a = se(o, t, r);
+      n.push(a), a.met || u.push(a);
+    }
+    e.push({
+      mix: i,
+      conditions: n,
+      allMet: u.length === 0,
+      unmetConditions: u
+    });
+  }
+  return e;
+}
+function se(s, t, e = /* @__PURE__ */ new Date()) {
+  const { type: r, value: i } = s, n = t?.environment, u = t?.appState;
+  switch (r) {
+    case "weather": {
+      const o = n?.weather?.weatherType || "", a = o.toLowerCase() === i.toLowerCase();
+      return {
+        type: r,
+        value: i,
+        met: a,
+        reason: a ? `Weather is ${o}` : `Weather is ${o} (need ${i})`
+      };
+    }
+    case "day": {
+      const a = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"][e.getDay()], l = a.toLowerCase() === i.toLowerCase();
+      return {
+        type: r,
+        value: i,
+        met: l,
+        reason: l ? `Today is ${a}` : `Today is ${a} (need ${i})`
+      };
+    }
+    case "start_time": {
+      const o = e.getHours() * 60 + e.getMinutes(), a = T(i), l = o >= a;
+      return {
+        type: r,
+        value: i,
+        met: l,
+        reason: l ? `Time is after ${i}` : `Time is before ${i}`
+      };
+    }
+    case "end_time": {
+      const o = e.getHours() * 60 + e.getMinutes(), a = T(i), l = o < a;
+      return {
+        type: r,
+        value: i,
+        met: l,
+        reason: l ? `Time is before ${i}` : `Time is after ${i}`
+      };
+    }
+    case "min_plays": {
+      const o = parseInt(i, 10), a = u?.playCount ?? 0, l = a >= o;
+      return {
+        type: r,
+        value: i,
+        met: l,
+        reason: l ? `Played ${a} times (need ${o})` : `Played ${a} times (need ${o})`
+      };
+    }
+    case "max_plays": {
+      const o = parseInt(i, 10), a = u?.playCount ?? 0, l = a <= o;
+      return {
+        type: r,
+        value: i,
+        met: l,
+        reason: l ? `Played ${a} times (max ${o})` : `Played ${a} times (exceeds max ${o})`
+      };
+    }
+    case "every_x_plays": {
+      const o = parseInt(i, 10), a = u?.playCount ?? 0, l = o > 0 && a > 0 && a % o === 0;
+      return {
+        type: r,
+        value: i,
+        met: l,
+        reason: l ? `Play #${a} (every ${o} plays)` : `Play #${a} (not a multiple of ${o})`
+      };
+    }
+    case "altitude": {
+      const o = n?.geolocation?.altitude;
+      if (o == null)
+        return { type: r, value: i, met: !1, reason: "Altitude unavailable" };
+      const a = ie(i), l = ne(o, a.operator, a.threshold);
+      return {
+        type: r,
+        value: i,
+        met: l,
+        reason: l ? `Altitude ${o}m ${a.operator} ${a.threshold}m` : `Altitude ${o}m (need ${a.operator} ${a.threshold}m)`
+      };
+    }
+    case "favorite": {
+      const o = u?.isFavorite ?? !1, a = i.toLowerCase() === "true", l = o === a;
+      return {
+        type: r,
+        value: i,
+        met: l,
+        reason: l ? o ? "Track is favorited" : "Track is not favorited" : o ? "Track is favorited (need unfavorited)" : "Track is not favorited (need favorited)"
+      };
+    }
+    case "birthday": {
+      if (!u?.userBirthday)
+        return { type: r, value: i, met: !1, reason: "Birthday not set" };
+      const a = `${String(e.getMonth() + 1).padStart(2, "0")}-${String(e.getDate()).padStart(2, "0")}` === u.userBirthday;
+      return {
+        type: r,
+        value: i,
+        met: a,
+        reason: a ? "It's your birthday!" : `Not your birthday (need ${u.userBirthday})`
+      };
+    }
+    case "weight":
+      return {
+        type: r,
+        value: i,
+        met: !0,
+        reason: `Weight ${i} (used for random selection, always available)`
+      };
+    default:
+      return {
+        type: r,
+        value: i,
+        met: !0,
+        reason: `Custom condition: ${r} = ${i}`
+      };
+  }
+}
+function T(s) {
+  const t = s.split(":");
+  if (t.length !== 2) return 0;
+  const e = parseInt(t[0], 10), r = parseInt(t[1], 10);
+  return isNaN(e) || isNaN(r) ? 0 : e * 60 + r;
+}
+function ie(s) {
+  const t = s.match(/^(>=|<=|>|<|=)?\s*(\d+(?:\.\d+)?)\s*$/);
+  return t ? {
+    operator: t[1] || ">=",
+    threshold: parseFloat(t[2])
+  } : { operator: ">=", threshold: parseFloat(s) || 0 };
+}
+function ne(s, t, e) {
+  switch (t) {
+    case ">":
+      return s > e;
+    case ">=":
+      return s >= e;
+    case "<":
+      return s < e;
+    case "<=":
+      return s <= e;
+    case "=":
+    case "==":
+      return s === e;
+    default:
+      return s >= e;
+  }
+}
+function h(s) {
+  if ("audio_url" in s && typeof s.audio_url == "string")
+    return s.audio_url;
+  if ("metadata" in s) {
+    const t = c.parseMetadata(s.metadata);
+    if (t)
+      return c.extractAudioUrl(t);
+  }
+  return null;
+}
+function N(s) {
+  if ("audio_url_lossless" in s && typeof s.audio_url_lossless == "string")
+    return s.audio_url_lossless;
+  if ("metadata" in s) {
+    const t = c.parseMetadata(s.metadata);
+    if (t)
+      return c.extractAudioUrlLossless(t);
+  }
+  return null;
+}
+function _(s) {
+  if ("image_url" in s && typeof s.image_url == "string")
+    return s.image_url;
+  if ("metadata" in s) {
+    if ("artwork_url" in s && typeof s.artwork_url == "string")
+      return s.artwork_url;
+    const t = c.parseMetadata(s.metadata);
+    if (t)
+      return c.extractImageUrl(t);
+  }
+  return null;
+}
+function P(s) {
+  if ("image_thumb_url" in s && typeof s.image_thumb_url == "string")
+    return s.image_thumb_url;
+  if ("metadata" in s) {
+    const t = c.parseMetadata(s.metadata);
+    if (t)
+      return c.extractImageThumbUrl(t);
+  }
+  return null;
+}
+function L(s) {
+  if ("metadata" in s) {
+    const t = c.parseMetadata(s.metadata);
+    if (t && typeof t.vrm == "string" && t.vrm)
+      return t.vrm;
+  }
+  return "extras" in s && s.extras && typeof s.extras.vrm == "string" && s.extras.vrm || null;
+}
+function U(s) {
+  if ("extras" in s && s.extras?.mixes)
+    return s.extras.mixes;
+  if ("metadata" in s) {
+    const t = c.parseMetadata(s.metadata);
+    if (t)
+      return A(t).mixes ?? [];
+  }
+  return [];
+}
+function R(s) {
+  if ("audio_url" in s || !("metadata" in s))
+    return null;
+  const t = c.parseMetadata(s.metadata);
+  return k(
+    s.selected_mix,
+    c.convertAttributes(t?.attributes),
+    t ? A(t).mixes : void 0
+  );
+}
+function be(s) {
+  const t = [];
+  for (const e of s.tracks) {
+    const r = h(e);
+    r && t.push(r);
+  }
+  return t;
+}
+function Ee(s) {
+  const t = [];
+  for (const e of s.tracks) {
+    const r = _(e);
+    r && t.push(r);
+  }
+  return t;
+}
+function Se(s) {
+  const t = [];
+  for (const e of s.tracks) {
+    if ("title" in e && typeof e.title == "string") {
+      t.push(e.title);
+      continue;
+    }
+    if ("metadata" in e) {
+      const r = c.parseMetadata(e.metadata);
+      if (r) {
+        const i = c.extractTitle(r);
+        i && t.push(i);
+      }
+    }
+  }
+  return t;
+}
+function Te(s) {
+  const t = [];
+  for (const e of s.tracks) {
+    if ("artist" in e && typeof e.artist == "string") {
+      t.push(e.artist);
+      continue;
+    }
+    if ("metadata" in e) {
+      const r = c.parseMetadata(e.metadata);
+      if (r) {
+        const i = c.extractArtist(r);
+        i && t.push(i);
+      }
+    }
+  }
+  return t;
+}
+function we(s) {
+  const t = /* @__PURE__ */ new Set();
+  for (const e of s.tracks) {
+    if ("genre" in e && typeof e.genre == "string" && e.genre) {
+      t.add(e.genre);
+      continue;
+    }
+    if ("metadata" in e) {
+      const r = c.parseMetadata(e.metadata);
+      r && typeof r.genre == "string" && r.genre && t.add(r.genre);
+    }
+  }
+  return Array.from(t).sort();
+}
+function ke(s) {
+  const t = /* @__PURE__ */ new Set();
+  for (const e of s.tracks) {
+    if ("tags" in e && Array.isArray(e.tags)) {
+      for (const r of e.tags)
+        r && t.add(r.toLowerCase());
+      continue;
+    }
+    if ("metadata" in e) {
+      const r = c.parseMetadata(e.metadata);
+      if (r && Array.isArray(r.tags))
+        for (const i of r.tags)
+          i && t.add(String(i).toLowerCase());
+    }
+  }
+  return Array.from(t).sort();
+}
+function Ie(s) {
+  let t = 0;
+  for (const e of s.tracks) {
+    if ("duration" in e && typeof e.duration == "number") {
+      t += e.duration;
+      continue;
+    }
+    if ("metadata" in e) {
+      const r = c.parseMetadata(e.metadata);
+      r && typeof r.duration == "number" && (t += r.duration);
+    }
+  }
+  return t;
+}
+function Me(s) {
+  return s.tracks.length;
+}
+function Ce(s) {
+  const t = [];
+  for (const e of s.tracks) {
+    let r = h(e);
+    const i = _(e), n = P(e), u = R(e);
+    u?.audio_url && (r = u.audio_url);
+    const o = u ? u.name : "audio_url" in e ? e.selected_mix : void 0;
+    let a = "", l = "", f;
+    if ("title" in e)
+      a = e.title || "", l = e.artist || "", f = e.description || void 0;
+    else if ("metadata" in e) {
+      const d = c.parseMetadata(e.metadata);
+      d && (a = c.extractTitle(d) || "", l = c.extractArtist(d) || "", f = c.extractDescription(d) || void 0);
+    }
+    if (r) {
+      const d = {
+        title: a,
+        artist: l,
+        audio_url: r,
+        image_url: i || ""
+      }, m = N(e), p = u ? u.audio_url_lossless : m && m !== r ? m : void 0;
+      p && (d.audio_url_lossless = p), o && (d.selected_mix = o), n && (d.image_thumb_url = n), f && (d.description = f), "audio_ipfs_hash" in e && typeof e.audio_ipfs_hash == "string" && (d.audio_ipfs_hash = e.audio_ipfs_hash), "artwork_ipfs_hash" in e && typeof e.artwork_ipfs_hash == "string" && (d.artwork_ipfs_hash = e.artwork_ipfs_hash), "mint_function" in e && typeof e.mint_function == "string" && (d.mint_function = e.mint_function), "mint_price" in e && typeof e.mint_price == "string" && (d.mint_price = e.mint_price), "mint_snapshot_time" in e && typeof e.mint_snapshot_time == "number" && (d.mint_snapshot_time = e.mint_snapshot_time), "mint_token" in e && typeof e.mint_token == "string" && (d.mint_token = e.mint_token), t.push(d);
+    }
+  }
+  return t;
+}
+function Ne(s) {
+  const t = [];
+  for (const e of s.tracks) {
+    if ("audio_url" in e) {
+      t.push({ ...e });
+      continue;
+    }
+    if ("metadata" in e) {
+      const r = c.parseMetadata(e.metadata);
+      if (r) {
+        const i = A(r), n = k(
+          e.selected_mix,
+          c.convertAttributes(r.attributes),
+          i.mixes
+        ), u = c.extractAudioUrlLossless(r), o = c.extractAudioUrl(r), a = n?.audio_url || o, l = n ? n.audio_url_lossless : u && u !== a ? u : void 0;
+        t.push({
+          id: e.chain_name === "AR" ? `AR-${e.tx_id}` : `${e.chain_name}-${e.token_address}-${e.token_id}`,
+          chain_name: e.chain_name,
+          token_address: e.token_address,
+          token_id: e.token_id,
+          tx_id: e.tx_id,
+          platform: e.platform,
+          title: c.extractTitle(r),
+          artist: c.extractArtist(r),
+          audio_url: a,
+          image_url: c.extractImageUrl(r),
+          image_thumb_url: c.extractImageThumbUrl(r),
+          duration: r.duration,
+          genre: r.genre,
+          tags: r.tags,
+          bpm: r.bpm,
+          key: r.key,
+          album: r.album,
+          description: c.extractDescription(r),
+          attributes: c.convertAttributes(r.attributes),
+          ...l ? { audio_url_lossless: l } : {},
+          ...n ? { selected_mix: n.name } : {},
+          ...i.hasExtras ? { extras: i } : {},
+          // v0.4 IPFS hash + mint fields from the raw track wrapper
+          ...e.audio_ipfs_hash ? { audio_ipfs_hash: e.audio_ipfs_hash } : {},
+          ...e.artwork_ipfs_hash ? { artwork_ipfs_hash: e.artwork_ipfs_hash } : {},
+          ...e.mint_function ? { mint_function: e.mint_function } : {},
+          ...e.mint_price ? { mint_price: e.mint_price } : {},
+          ...e.mint_snapshot_time ? { mint_snapshot_time: e.mint_snapshot_time } : {},
+          ...e.mint_token ? { mint_token: e.mint_token } : {}
+        });
+      }
+    }
+  }
+  return t;
+}
+function Pe(s) {
+  const t = [];
+  for (const e of s.tracks) {
+    const r = L(e);
+    r && t.push(r);
+  }
+  return t;
+}
+function Le(s) {
+  const t = [];
+  for (const e of s.tracks) {
+    const r = L(e);
+    if (!r) continue;
+    const i = h(e), n = _(e), u = P(e);
+    let o = "", a = "", l;
+    if ("title" in e)
+      o = e.title || "", a = e.artist || "", l = e.description || void 0;
+    else if ("metadata" in e) {
+      const d = c.parseMetadata(e.metadata);
+      d && (o = c.extractTitle(d) || "", a = c.extractArtist(d) || "", l = c.extractDescription(d) || void 0);
+    }
+    const f = {
+      title: o,
+      artist: a,
+      audio_url: i || "",
+      image_url: n || "",
+      vrm: r
+    };
+    u && (f.image_thumb_url = u), l && (f.description = l), t.push(f);
+  }
+  return t;
+}
+function Ue(s) {
+  const t = [];
+  for (const e of s.tracks)
+    t.push(...U(e));
+  return t;
+}
+function Re(s) {
+  const t = [];
+  for (const e of s.tracks) {
+    const r = U(e);
+    if (r.length === 0) continue;
+    const i = R(e);
+    let n = "", u = "", o;
+    if ("title" in e)
+      n = e.title || "", u = e.artist || "", o = e.description || void 0;
+    else if ("metadata" in e) {
+      const d = c.parseMetadata(e.metadata);
+      d && (n = c.extractTitle(d) || "", u = c.extractArtist(d) || "", o = c.extractDescription(d) || void 0);
+    }
+    let a = h(e) || "", l;
+    if (i)
+      a = i.audio_url || a, l = i.audio_url_lossless;
+    else {
+      const d = N(e);
+      l = d && d !== a ? d : void 0;
+    }
+    const f = i ? i.name : "audio_url" in e ? e.selected_mix : void 0;
+    t.push({
+      title: n,
+      artist: u,
+      audio_url: a,
+      image_url: _(e) || "",
+      ...l ? { audio_url_lossless: l } : {},
+      ...f ? { selected_mix: f } : {},
+      ...o ? { description: o } : {},
+      mixes: r
+    });
+  }
+  return t;
+}
+const x = [
+  "ipfs.io",
+  "cloudflare-ipfs.com",
+  "dweb.link",
+  "gateway.pinata.cloud",
+  "ipfs.infura.io",
+  "nftstorage.link",
+  "web3-music-pipeline.mypinata.cloud",
+  "soundxyz.mypinata.cloud",
+  "gold-broad-gibbon-29.mypinata.cloud",
+  "bonfire.mypinata.cloud",
+  "spinamp.mypinata.cloud",
+  "catalogworks.b-cdn.net",
+  "www.heds.cloud"
+], ae = "ipfs.io", v = "/ipfs/", oe = /^Qm[1-9A-HJ-NP-Za-km-z]{44}$/, le = /^b[a-z2-7]{55,}$/;
+function ue(s) {
+  return oe.test(s) || le.test(s);
+}
+const ce = /^ipfs_[a-z]+$/;
+function D(s) {
+  const t = s.split("/").filter(Boolean);
+  for (let e = 0; e < t.length - 1; e++)
+    if (ce.test(t[e]) && ue(t[e + 1])) {
+      const r = t[e + 1], i = t.slice(e + 2);
+      return i.length > 0 ? `${r}/${i.join("/")}` : r;
+    }
+  return null;
+}
+function de(s) {
+  if (!s || typeof s != "string") return null;
+  if (s.startsWith("ipfs://ipfs/"))
+    return s.slice(12);
+  if (s.startsWith("ipfs://"))
+    return s.slice(7);
+  try {
+    const t = new URL(s), { hostname: e, pathname: r } = t, i = e.match(/^([A-Za-z0-9]+)\.ipfs\.dweb\.link$/);
+    if (i)
+      return `${i[1]}${r}`;
+    if (x.some(
+      (o) => e === o || e.endsWith("." + o)
+    ) && r.startsWith(v))
+      return r.slice(v.length);
+    const u = D(r);
+    if (u) return u;
+  } catch {
+  }
+  return null;
+}
+function De(s) {
+  if (!s || typeof s != "string") return !1;
+  if (s.startsWith("ipfs://")) return !0;
+  try {
+    const t = new URL(s), { hostname: e, pathname: r } = t;
+    if (/^[A-Za-z0-9]+\.ipfs\.dweb\.link$/.test(e) || x.some(
+      (n) => e === n || e.endsWith("." + n)
+    ) && r.startsWith(v) || D(r)) return !0;
+  } catch {
+  }
+  return !1;
+}
+function fe(s) {
+  if (!(!s || s.startsWith("ipfs://")))
+    try {
+      const { hostname: t } = new URL(s);
+      return x.some(
+        (r) => t === r || t.endsWith("." + r)
+      ) ? t : void 0;
+    } catch {
+      return;
+    }
+}
+function Oe(s, t = {}) {
+  if (!s) return s;
+  const e = typeof t == "string" ? { gatewayHost: t } : t, { gatewayHost: r = ae, preserveOriginalGateway: i = !1 } = e, n = de(s);
+  if (n) {
+    if (i) {
+      const u = fe(s);
+      if (u)
+        return `https://${u}/ipfs/${n}`;
+    }
+    return `https://${r}/ipfs/${n}`;
+  }
+  return s;
+}
+const me = "---\nname: playlist-data-engine\ndescription: The playlist-data-engine npm package — parse Arweave/IPFS serverless music playlists (Ethereum NFTs + Arweave uploads; the data behind ar://listen and ApeTapes) into clean track data; resolve alternate mixes (entry pins, selected_mix, alias-tolerant lookup, lossy/lossless pairs) and track extras/stems; reach files through Arweave gateway failover (AR.IO Wayfinder); analyze audio (sonic fingerprint, genre/mood classification, pitch, BPM/beat maps, rhythm charts) and drive deterministic D&D-style generation from the music — characters, enemies, combat, equipment, XP. Use when working with the playlist-data-engine package, serverless playlist JSON, Arweave music NFTs, or building music-reactive or rhythm-game features on this engine.\n---\n\n# playlist-data-engine\n\nOne engine, one pipeline: a **serverless playlist** (Arweave JSON mixing Ethereum NFTs and Arweave uploads) is parsed into clean tracks; track audio is analyzed; analysis drives **deterministic generation** — characters, enemies, rhythm charts, combat; XP/progression and IRL sensors make the result a living music player. Two halves meet at audio: the data half (parse → extract → resolve → analyze) and the game half (beat map → chart → character/XP/combat).\n\n## First moves\n\n- Docs ship **inside the package**, version-matched to your install: `node_modules/playlist-data-engine/docs/`. If docs and observed behavior disagree, check your installed version.\n- `docs/DATA_ENGINE_REFERENCE.md` is the master index — every export, one row each, **no examples or algorithms by design** (those live in USAGE and features/*). Start at its **Quick Export Reference** to find the function, then jump to its section. Caveat: its Core table predates the entry-point split — the ML classes listed there now live behind `/analysis`.\n- `docs/USAGE_IN_OTHER_PROJECTS.md` has working code for every major feature (install, full pipeline, troubleshooting).\n- CLI: `npx playlist-data-engine docs` (doc index) · `docs <topic>` (full text) · `skill` (this file). From code: `engineHelp()` / `engineHelp('<topic>')` / `engineHelp('skill')` — exported from both the default and `/gateway` entries. Canonical copy of this file: `skills/playlist-data-engine/SKILL.md` in the repo.\n- The `.d.ts` in `dist/` is the complete API surface with JSDoc.\n\n## Three entry points — pick by bundle weight\n\n| Import | Gives you | Pulls TF? |\n|---|---|---|\n| `playlist-data-engine` (default) | Everything **except** ML — parser, playlists, mixes, gateway, generation, combat, XP, sensors, beat detection | No |\n| `playlist-data-engine/gateway` | Lightest: `ArweaveGatewayManager` + Arweave/IPFS URL utils, `MetadataExtractor`, mix lookup (`findMixByName`/`resolveMixUrl`/`selectMix`), `getMixes`/`getMixTracks`/VRM getters | No |\n| `playlist-data-engine/analysis` | TensorFlow-bearing: `AudioAnalyzer`, `MusicClassifier`, `PitchAnalyzer`, `EssentiaPitchDetector`, `PitchBeatLinker`, `ButtonMapper`, `LevelGenerator`, `LevelSerializer`, `BeatConverter`, `ModelCache` | Yes (~14 MB) |\n\nRules: default to the bare import; import `/analysis` only in code that actually runs ML — ideally isolated in a Web Worker; never re-export `/analysis` symbols through the other entries.\n\n## The map\n\n| You want… | Reach for | Read |\n|---|---|---|\n| Parse a playlist | `new PlaylistParser().parse(raw)` — takes any raw object; options `strict`, `validateAudioUrls`, `resolveImageUrls`. Gateway fetch is yours: `arweaveGatewayManager.resolveUrl()` + `fetch` | features/PLAYLIST_PARSING.md |\n| Quick data arrays | `getAudioUrls`, `getTrackTitles`, `getArtists`, `getGenres`, `getTags`, `getTotalDuration`, `getTracks`, `getFullTracks` — work on raw **and** parsed input | DATA_ENGINE_REFERENCE.md → Playlist Utilities |\n| Track extras (stems, mixes, VRM, lyrics, charts…) | `track.extras`, `getTrackMetadata(raw)`, `getTrackExtras(metadata)` | features/PLAYLIST_PARSING.md |\n| Alternate mixes | See **Mixes** below | features/PLAYLIST_PARSING.md |\n| Conditional mixes (weather/time/plays) | `evaluateMixConditions(extras, { environment, appState })` — unknown condition types always pass; `weather` conditions need `WEATHER_API_KEY`, day/time pass keyless | features/PLAYLIST_PARSING.md |\n| Resolve any Arweave URL | `arweaveGatewayManager.resolveUrl(url)` — cache → the gateway already in the URL → persisted gateway → arweave.net → static gateways in parallel → AR.IO Wayfinder last. Hot path: `resolveUrlSimple()`. After a real fetch fails: `reportGatewayFailure(url, { reason })`. Non-Arweave URLs pass through | features/GATEWAY_RESOLUTION.md |\n| IPFS URLs | `isIPFS`, `extractIPFSPath`, `resolveIPFSLink` | features/GATEWAY_RESOLUTION.md |\n| Sonic fingerprint / full timeline | `AudioAnalyzer.extractSonicFingerprint(url)` (samples 5%/40%/70%), `.analyzeTimeline(url, { type: 'interval' \\| 'count', … })` | features/AUDIO_ANALYSIS.md |\n| Genre / mood / vibes | `MusicClassifier.analyze(url)` — 400+ subgenres, mood themes, danceability/energy/valence; zero-config defaults load Arweave-hosted models; `preset:` swaps models | features/AUDIO_ANALYSIS.md |\n| Pitch / melody | `PitchDetector` (pure pYIN, TF-free, **default entry**) or `/analysis` `PitchAnalyzer.analyze(url)` (adds contour; `EssentiaPitchDetector` needs `await .create()`) | features/AUDIO_ANALYSIS.md |\n| Colors from artwork | `ColorExtractor.extractPalette(imageUrl)` (default entry, no TF) | DATA_ENGINE_REFERENCE.md → ColorExtractor |\n| Detect beats / play in rhythm | `BeatMapGenerator.generateBeatMap()` → `BeatStream` (real-time sync, `checkButtonPress`); `GrooveAnalyzer` (DMC-style groove meter); interpolation/subdivision helpers; manual chart editing via `reapplyDownbeatConfig` + beat key helpers | features/BEAT_DETECTION.md |\n| Procedural rhythm charts | `RhythmGenerator` (default entry: transients → quantize → phrases → composite streams → difficulty variants) or `/analysis` `LevelGenerator` (adds pitch-driven `ButtonMapper` for DDR/Guitar Hero/Tap) | features/BEAT_DETECTION.md |\n| Character from a song | `CharacterGenerator.generate(seed, audioProfile, track, { gameMode: 'standard' \\| 'uncapped' })` — same song, same character. `audioProfile` = `/analysis` `AudioAnalyzer.extractSonicFingerprint()` — or any plain `AudioProfile` object (TF-free synthesis is valid) | USAGE_IN_OTHER_PROJECTS.md |\n| Enemies / encounters | `EnemyGenerator.generate()` / `generateEncounter(party, opts)` / `generateEncounterByCR(opts)` — **CR = power, rarity = complexity, independent axes**; audio profile steers templates & stats | features/ENEMY_GENERATION.md |\n| Combat & balance | `CombatEngine` (turn-based; `hitMode: 'scaled'` default — AC reduces damage — vs `'dnd'`), `CombatSimulator` (Monte Carlo, per-run seeds), `CombatAI`/`AICombatRunner`, `DifficultyCalculator`, `BalanceValidator`, `ParameterSweep` | features/COMBAT_SYSTEM.md |\n| Dice & seeds | `generateSeed(chain, address, tokenId)`, `deriveSeed`, `SeededRNG`, `DiceRoller`, `SeededDiceRoller`/`createSeededRoller` | features/ROLLS_AND_SEEDS.md |\n| Equipment / loot | `EquipmentGenerator`, `EquipmentModifier` (enchant/curse/upgrade), `EquipmentSpawnHelper` (batch spawn), `BoxOpener` (box items) | features/EQUIPMENT_SYSTEM.md |\n| XP & leveling | `SessionTracker` → `CharacterUpdater.updateCharacterFromSession()` (~1 XP/s × modifiers), `addXP`/`addRhythmXP` for other sources; `StatManager` strategies; `PrestigeSystem` (track mastery); uncapped XP curves | features/XP_AND_STATS.md |\n| IRL context | `EnvironmentalSensors` (GPS/motion/weather; solar math needs no API key), `GamingPlatformSensors` (Steam); XP modifier capped at 3.0× | features/IRL_SENSORS.md |\n| Custom content | `ExtensionManager.getInstance().register(category, items, { mode, weights })` — races, classes, spells, skills, `classFeatures`, `racialTraits`, equipment; runtime only | features/EXTENSIBILITY_GUIDE.md (+ CUSTOM_CONTENT.md, CONTENT_PACKS.md, PREREQUISITES.md) |\n| Something broke | ML models load from Arweave at runtime (offline dev fails); audio analysis needs Web Audio | USAGE_IN_OTHER_PROJECTS.md → Troubleshooting |\n| Validate data | Zod schemas: `ServerlessPlaylistSchema`, `PlaylistTrackSchema`, `CharacterSheetSchema`, `AudioProfileSchema`, `MixInfoSchema`, … | DATA_ENGINE_REFERENCE.md → Utilities |\n\n## Mixes — the subtle part\n\n- A playlist **entry** pins a mix via `selected_mix` on the track wrapper. Pin matching is **exact and case-sensitive** — `'default'`, or a name matching nothing, means unpinned; legacy `Selected Mix` attribute is the fallback. A pinned track's `audio_url` (and `audio_url_lossless`) are repointed at parse time, so it just plays. `getTracks`/`getFullTracks` apply pins on the raw path too.\n- **User choice after parse** is the tolerant path over `track.extras.mixes`: `findMixByName(mixes, name, { prefer, aliases, caseInsensitive })` and `selectMix(track, name)` — case-insensitive, trimmed, alias-aware, exact names always win. `'tv mix'` finds Karaoke, which is its own concept, **never** an instrumental. One name can ship twice (lossy + lossless master): `prefer` defaults to `'lossy'`; `getUniqueMixes`/`getPreferredMixByQuality` handle grouping. Pass `conditionsContext` to `selectMix` to enforce a gated mix's conditions at choice time.\n- Audio/mix URIs are **not** resolved at parse time (only images, and only with `resolveImageUrls: true`). `resolveMixUrl(mix)` gateway-resolves for you and follows metadata-JSON uris (`application/json`) one hop to the real audio file.\n\n## Cross-cutting rules\n\n- **Determinism is the contract.** `generateSeed`/`deriveSeed` → `SeededRNG` (generation) and `SeededDiceRoller` (combat dice): same seed + same inputs = byte-identical output. This is why characters are cacheable per track id.\n- **Leveling config:** `LevelUpProcessor.setUncappedConfig()` is genuinely global (set before leveling uncapped characters). XP math is otherwise **per-instance**: `new XPCalculator({ xp_per_second, activity_bonuses })`, optionally handed to `new SessionTracker(calculator)` — `mergeProgressionConfig()` is a stateless merge helper, not global state.\n- **Extensions are runtime-only.** Nothing persists across restarts; re-register on boot or round-trip `exportCustomData()`.\n- **No `src` ships in the package** — consumers get built `dist` (plus `docs/`, `bin/`, `skills/`, `llms.txt`). Consumers on `file:` deps read built dist — rebuild the engine (`npm run build`) after source changes, then restart the consumer's dev server (webpack does not invalidate `file:` symlink targets).\n- **Environment:** audio analysis + beat detection need Web Audio (browser, or the `web-audio-api` polyfill in Node); the gateway manager persists state to `localStorage` (shim it server-side); ML models fetch from Arweave at runtime.\n- **Sensors are optional.** Env keys: `WEATHER_API_KEY`, `STEAM_API_KEY`, `STEAM_USER_ID`, `XP_MAX_MODIFIER`; sunrise/sunset math needs no key.\n", O = [
+  { slug: "data_engine_reference", file: "docs/DATA_ENGINE_REFERENCE.md", summary: "Every public function in one table — signatures, inputs, outputs." },
+  { slug: "usage_in_other_projects", file: "docs/USAGE_IN_OTHER_PROJECTS.md", summary: "Install, main vs gateway entry, first parsed playlist." },
+  { slug: "playlist_parsing", file: "docs/features/PLAYLIST_PARSING.md", summary: "Loading playlists, track objects, alternate mixes: pins, alias matching, lossy/lossless pairs." },
+  { slug: "gateway_resolution", file: "docs/features/GATEWAY_RESOLUTION.md", summary: "Gateway failover, Wayfinder, resolving tx and IPFS URLs." },
+  { slug: "audio_analysis", file: "docs/features/AUDIO_ANALYSIS.md", summary: "BPM, key, mood, genre classification (TensorFlow + essentia)." },
+  { slug: "beat_detection", file: "docs/features/BEAT_DETECTION.md", summary: "Beat streams and rhythm-game chart generation." },
+  { slug: "combat_system", file: "docs/features/COMBAT_SYSTEM.md", summary: "Seeded combat simulations driven by track energy." },
+  { slug: "content_packs", file: "docs/features/CONTENT_PACKS.md", summary: "Bundled content collections." },
+  { slug: "custom_content", file: "docs/features/CUSTOM_CONTENT.md", summary: "Authoring your own content." },
+  { slug: "enemy_generation", file: "docs/features/ENEMY_GENERATION.md", summary: "Characters generated from sonic fingerprints." },
+  { slug: "equipment_system", file: "docs/features/EQUIPMENT_SYSTEM.md", summary: "Loot and equipment." },
+  { slug: "extensibility_guide", file: "docs/features/EXTENSIBILITY_GUIDE.md", summary: "Extending the engine." },
+  { slug: "irl_sensors", file: "docs/features/IRL_SENSORS.md", summary: "Weather, time, motion context for condition-gated mixes." },
+  { slug: "prerequisites", file: "docs/features/PREREQUISITES.md", summary: "Required setup." },
+  { slug: "rolls_and_seeds", file: "docs/features/ROLLS_AND_SEEDS.md", summary: "Deterministic seeded dice." },
+  { slug: "xp_and_stats", file: "docs/features/XP_AND_STATS.md", summary: "Progression and persistence." }
+], G = {
+  reference: "data_engine_reference",
+  usage: "usage_in_other_projects",
+  parsing: "playlist_parsing",
+  mixes: "playlist_parsing",
+  gateway: "gateway_resolution",
+  docs: "data_engine_reference"
+}, y = [
+  {
+    version: "1.7.3",
+    uploadedAt: "2026-10-05T00:00:00.000Z",
+    files: {
+      "DATA_ENGINE_REFERENCE.md": "TWQ0ashXikM82N2fEmeSSWtV72CavF6kySmZWWyTUX0",
+      "USAGE_IN_OTHER_PROJECTS.md": "wzeOtdQnuAx4Tk_SuTL0Mzkk05EviFljJdpI93pB7Ek",
+      "features/AUDIO_ANALYSIS.md": "v6apJcfWhSXSNf2zFgl36xaeurTsfm89YUvi0PPGUbs",
+      "features/BEAT_DETECTION.md": "IK26T_JcCnS5SVWmvaSzLL_QyihvyCpKXaUrBlhQRow",
+      "features/COMBAT_SYSTEM.md": "dk8G9qnh76tpjudjOhzvCEL89Wm2ZNHY_BPqIzuoxLg",
+      "features/CONTENT_PACKS.md": "QzoLMibxAWtJ6NfM82f_xZUh4tLAoF0ZoQf-vzI-r5c",
+      "features/CUSTOM_CONTENT.md": "76hpg3ox37NfaK4b1PplPrJpAP3PXBqQwTtpOhvFWXo",
+      "features/ENEMY_GENERATION.md": "eeEuV9bCP8jxX5_DU6V6p2imbiJ251cTM8dM3UqaCbc",
+      "features/EQUIPMENT_SYSTEM.md": "I8GH9d6UuHl1bbdLAN5LUo4ppcPu5cK320q_HQ0GEzU",
+      "features/EXTENSIBILITY_GUIDE.md": "8ha92HARwcA1AQ0z5OqmdXWa7VPDcPrImqF1MB2Dd5Q",
+      "features/GATEWAY_RESOLUTION.md": "__oqyaVqA-DPF_M_9_C9S8nYNohXjJd2b2YIU9uYVHE",
+      "features/IRL_SENSORS.md": "AodJ11PvwSNnT8hoReib4lWArlfO6nH0tU3Gz5x5ul8",
+      "features/PLAYLIST_PARSING.md": "CDZOVCe1RTVWQKhG-FMj12XA0hAb6E_Gj-UBq1-h9SY",
+      "features/PREREQUISITES.md": "CnP5rxjK_5xX70-1SiCzymVROaARp5Um2yESF2yaTmQ",
+      "features/ROLLS_AND_SEEDS.md": "y1mCkus6jre7h_jHDZMM_PGoucrDuUazNBnCZD2-zdo",
+      "features/XP_AND_STATS.md": "UV4cFhuL7Un8XuguyAKNu0Qo1RlIiKYGWiBdvBJzEEM"
+    }
+  }
+], pe = "https://github.com/jasondesante/playlist-data-engine/blob/main";
+function F() {
+  const s = O.map((r) => `- \`${r.slug}\` — ${r.file}: ${r.summary}`).join(`
+`), t = y[y.length - 1];
+  return [
+    "# playlist-data-engine — docs index",
+    "",
+    "Parse Arweave serverless music playlists, resolve alternate mixes and quality, reach files through gateway failover.",
+    "",
+    "## Where the full docs are",
+    "",
+    "- In this install: `node_modules/playlist-data-engine/docs/` (version-matched — prefer this)",
+    "- CLI: `npx playlist-data-engine docs <topic>`",
+    "- GitHub: https://github.com/jasondesante/playlist-data-engine/tree/main/docs",
+    ...t ? [`- Permanent archive on Arweave: latest snapshot is v${t.version} (${t.uploadedAt}) — every doc also has an \`ar://\` link via \`engineHelp('<topic>')\``, "- All archived versions stay addressable forever: " + y.map((r) => `v${r.version} (${r.uploadedAt.slice(0, 10)})`).join(", ")] : [],
+    "",
+    "## Topics",
+    "",
+    s,
+    "",
+    "## For AI agents",
+    "",
+    "- `engineHelp('<topic>')` returns where to read one doc (aliases: " + Object.keys(G).join(", ") + ")",
+    "- `engineHelp('skill')` returns the Claude Code skill file — write it to `.claude/skills/playlist-data-engine/SKILL.md` to install",
+    "- The `.d.ts` in dist/ is the complete API surface with JSDoc",
+    ""
+  ].join(`
+`);
+}
+function g(s) {
+  const t = s.replace(/^docs\//, "");
+  for (let e = y.length - 1; e >= 0; e--) {
+    const r = y[e].files[t];
+    if (r) return { entry: y[e], txId: r };
+  }
+}
+function ye(s) {
+  const t = G[s.toLowerCase()] ?? s.toLowerCase(), e = O.find((r) => r.slug === t || r.slug.startsWith(t));
+  return e ? [
+    `# ${e.slug}`,
+    "",
+    e.summary,
+    "",
+    `- File: \`${e.file}\` (relative to the package root)`,
+    `- In this install: \`node_modules/playlist-data-engine/${e.file}\``,
+    `- CLI: \`npx playlist-data-engine docs ${e.slug}\``,
+    `- Online: ${pe}/${e.file}`,
+    ...g(e.file) ? [`- Permanent: ar://${g(e.file).txId} (docs v${g(e.file).entry.version}, uploaded ${g(e.file).entry.uploadedAt.slice(0, 10)})`] : [],
+    "",
+    "Read the file itself for the full text — this pointer is deliberately small so it stays safe in browser bundles.",
+    ""
+  ].join(`
+`) : `No doc topic "${s}".
+
+${F()}`;
+}
+function Ge(s) {
+  return s ? s.toLowerCase() === "skill" ? me : ye(s) : F();
+}
+export {
+  b as A,
+  xe as B,
+  ae as D,
+  y as E,
+  x as K,
+  c as M,
+  O as a,
+  re as b,
+  de as c,
+  Te as d,
+  Ge as e,
+  ve as f,
+  A as g,
+  be as h,
+  Ne as i,
+  we as j,
+  Ee as k,
+  Re as l,
+  Ue as m,
+  I as n,
+  ke as o,
+  Ie as p,
+  Me as q,
+  k as r,
+  _e as s,
+  Se as t,
+  Ce as u,
+  Ae as v,
+  Le as w,
+  Pe as x,
+  De as y,
+  Oe as z
+};