custom-shuffle-order 是一个媒体播放引擎层面的洗牌顺序实现方案，用于替换默认的随机打散逻辑。默认实现会把新插入的条目随机放到剩余播放顺序的任意位置，这对“随机播放整张专辑”是合理的，但对“播放下一首”或“追加一页队列”这类操作并不合适：用户点击“下一首播放”时希望该曲目紧接着当前曲目，追加续页时也希望这一页保持连续成块。
主要能力：条目给出的 BetterShuffleOrder 类维护两个数组：正向排列 shuffled（shuffled[playPosition] = timelineIndex）与在构造时派生的反查映射 indexInShuffled（indexInShuffled[timelineIndex] = playPosition）。它实现 getNextIndex 等方法，通过反查映射找到当前位置的下一个播放位置；引擎还会向它查询上一首与首尾条目，并在队列变动时要求它克隆自身。
使用方式与关键约束：所有变更操作都是 cloneAnd* 形式（如 cloneAndInsert、cloneAndClear），必须返回新实例而非原地修改，因为引擎在构建新时间线期间可能丢弃结果，原地修改会在队列编辑被回滚后产生与实际不符的顺序。cloneAndInsert 需要同时完成两件事：时间线索引位于插入点及之后的既有条目整体后移 insertCount；新条目放到枢轴（pivot）附近的播放位置。插入点越过末尾（append）与插入点位于队列中间是两个分支，必须分别处理。删除操作需要把被删范围之后的时间线索引整体下移，只删条目而不重编号会导致顺序指向超出收缩后队列的位置。反查映射必须由 shuffled 重建，不能在插入和删除时只修补正向数组。洗牌开始时若存在正在播放的曲目，需把它交换到排列首位，避免开启随机播放后从头另播。排列生成建议使用 inside-out 变体 Fisher–Yates，只需一个输出数组。getFirstIndex、getLastIndex 和 cloneAndInsert 都需处理空队列情况，防止越界读取。另外，关闭洗牌后引擎会回到时间线顺序，“下一首播放”的曲目会出现在其时间线插入位置，这属于产品层面的取舍，洗牌顺序本身无法改变。
验证方式：打印每次克隆后的 shuffled 数组，人工检查它是否为 0 until size 的排列（无重复、无缺失），且插入的块紧邻当前播放位置之后。
适用场景：使用 ShuffleOrder 抽象、需要自定义“下一首播放”和分页追加行为的媒体播放队列。
限制与许可：条目中的设计参考 Auxio 项目（Alexander Capehart）以 GPL-3.0 许可发布的 BetterShuffleOrder；若在自己的项目中复制代码而非借鉴模式，需遵守该许可证及其署名要求。具体的安装、依赖与集成步骤暂未提供。