# 3D Playlist Shelf Memory

## 2026-06-24 详情页歌词可读与避让边界

- 3D 歌单详情页打开时，歌词不能再被压成几乎不可见；用户要的是“默认歌词仍可读，只是不挡歌单详情页”，避让应主要靠 `stageLyrics.group.renderOrder` 低于详情页和削弱 glow/sun/spark。
- 当前边界：`updateStageLyrics3D()` 的 `shelfDetailLyricProfile` 普通详情页文字 opacity 约 `0.38`、骷髅详情页约 `0.30`；readability/辉光单独降低，退场歌词也乘 `outgoing`，防止选歌、切歌或新词进来时突然跳亮。
- 禁止回退：不要把详情页歌词目标透明度恢复到 `0.055` 左右；不要只压当前歌词而放任旧词退场保持高亮；不要让发光层重新横穿详情页中心高亮行。

## 2026-06-24 常驻实卡质感与歌词层级

- 常驻 3D 歌单架默认视觉要接近右键展开后的实体卡效果，不能再把 `passiveAlways` 压成灰暗半透明幽灵卡；当前边界是保留 `shelfBgOpacity` 的实卡黑玻璃底，`passiveAlways` 只做极轻微透明/亮度压制。
- 层级不能因此回退：常驻未命中时 shelf group/card 仍保持在歌词后层，避免长期遮挡歌词；只有鼠标真实命中/选中卡片后，通过 `selected` / `floatMix` 浮起动画把卡片抬到歌词前景。
- 相关位置：`public/index.html` 的 `makeShelfManager().placeCard()`，关注 `passiveAlways`、`floatMix`、`card.mesh.renderOrder`、`group.renderOrder` 和 `shelfVisibility`。
- 禁止回退：不要为了让常驻卡片更清楚而把整组歌单架永久放到歌词上层；不要再把常驻默认卡片透明度压回 0.5 左右导致看起来像没有右键展开质感。

## 2026-06-24 自动隐藏触发区边界

- 3D 歌单架在“自动隐藏”显示状态下，不允许保留右侧隐形动态镜头触发区；只有歌单架已经显示、正在淡入/淡出可见、详情页打开、固定展开、常驻真实卡片命中或视觉引导时，`shelfAutoHiddenInputReady()` 才能放行动态镜头 focus、hover 高亮和滚轮接管。
- fullscreen DIY 悬浮入口不能和视觉控制台/视觉引导/热键弹窗抢层级；`shouldSuppressFullscreenDiyPeek()` 需要在这些场景下移除 `fullscreen-diy-peek`，不要再靠提高 z-index 硬压。

## 2026-06-24 内容开关与连续滚动

- 3D 歌单架内容开关必须保留：`fx.shelfShowPodcasts` 默认 `true`，用于控制播客歌单是否显示；`fx.shelfMergeCollections` 默认 `false`，默认仍保留“我的歌单滚到底再进入收藏歌单”的二段体验。
- 开启“合并收藏歌单”后，`activePlaylists()` 应返回 `mine.concat(fav)`，滚轮一路向下就是我的歌单到收藏歌单，不再触发 `switchPane('fav')` 的二段切页。
- 切换播客显示或合并收藏时必须重建 shelf，并且列表签名要包含开关值、播客数量和实际 item 采样，避免 UI 开关亮了但 3D 卡片还停在旧内容。
- 不要把播客永久移出歌单架，也不要把合并收藏设成默认开启；这是用户可选的内容组织方式，不是替换原手感。

## 2026-06-24 动态/静态详情页边界

- 动态镜头模式下，歌单详情页必须跟随镜头，使用 `camera.quaternion` 面向当前镜头；不要把动态详情页也绑到封面粒子旋转上。
- 静态/固定镜头模式下，歌单详情页才跟封面粒子/画布绑定旋转移动，避免像硬贴镜头。
- 动态镜头 + 常驻歌单架同时开启时，常驻未展开状态不能用 `shelfAlwaysVisible()` 直接触发 shelf focus、滚轮或点击；只允许真实卡片命中触发，封面粒子/画布区域继续留给画布交互。

更新时间：2026-06-24

这份文档保存 3D 歌单架已经调好的交互和视觉边界。后续修改歌单架时先读本文件，优先小步调整，不要推倒重做。

## 已确认的功能边界

- 视觉控制台里保留「3D / 手势」折叠分组，入口文案为「歌单架 / 摄像头交互」。
- 歌单架模式保留三段：关闭、侧栏、舞台。
- 歌单架镜头保留两段：动态镜头、静态镜头。
- 歌单架显示保留两段：自动隐藏、常驻。
- 歌单架外观保留独立颜色，不只跟随全局高亮色；颜色需要接入高级取色器和用户存档快照。
- 参数滑条保留：歌单架大小、左右位置、上下位置、前后景深、侧向角度、整体透明度、背景透明度。

## 关键实现位置

- 主文件：`public/index.html`
- 控制台 UI：`#shelf-seg`、`#shelf-camera-seg`、`#shelf-presence-seg`、`#shelf-accent-picker`、`#fx-shelfsize`、`#fx-shelfx`、`#fx-shelfy`、`#fx-shelfz`、`#fx-shelfangle`、`#fx-shelfopacity`、`#fx-shelfbgalpha`
- 默认状态：`fxDefaults.shelf`、`shelfCameraMode`、`shelfPresence`、`shelfSize`、`shelfOffsetX`、`shelfOffsetY`、`shelfOffsetZ`、`shelfAngleY`、`shelfOpacity`、`shelfBgOpacity`、`shelfAccentColor`
- 调参入口：`shelfLayoutProfile()`、`makeShelfManager()`、`makeContentListManager()`、`setFocusZone()`

## 手感边界

- 不要把歌单架手感推倒重做；最强手感来自 hover 透明度、视差、展开节奏、轻微浮动和旧版张力线索。
- 后续优化应在 `makeShelfManager()` / `makeContentListManager()` 周围小步调参。
- 悬停展开和点击可用之间要更清楚，避免用户以为 hover 后已经可以直接操作。
- 滚动选择必须跟随中心卡/中心行高亮，并触发短促、清脆、偏 PSP 的机械齿轮咔哒反馈；当前用 WebAudio 合成，不额外依赖二进制音效素材。
- 选择音效要偏清脆金属齿点，不要太钝、太闷或低频太厚；以后如果替换开源素材，优先找许可证明确、清脆机械咔哒质感的短 UI selection。
- 侧栏滚轮接管区不能再使用半屏 `shelfPreviewUseZone`；滚轮只在真实卡片命中、详情页实际面板/行命中，或右侧窄热区内接管，避免抢走封面粒子半边滚轮交互。
- 性能优化不要回到一次性渲染全部歌单或全部歌曲。

## 镜头和布局边界

- 动态镜头保留当前默认聚焦逻辑。
- 静态镜头要阻止歌单架触发镜头跟随，不要让画面被歌单架突然拉走。
- 侧栏歌单架的角度偏好：动态镜头默认 `0`；静态/固定镜头默认 `-15`，这个角度才更接近与画布粒子平行。用户手动拖动侧向角度滑条后才视为自定义角度。
- 常驻模式下，侧栏歌单架需要跟随粒子封面角度绑定，保持和舞台视觉同向。
- 常驻模式下，未悬停选中时侧栏歌单架应退到歌词后层并降低存在感；鼠标命中卡片后再通过 `selected` / `floatMix` 浮起到歌词前景，形成上浮动画和高亮描边。
- 常驻或详情页打开时，歌词需要主动避让，减少遮挡歌单架操作；但常驻未选中卡片不能长期压住歌词。
- 歌单详情页层级必须高于歌单卡片，打开后盖在卡片最上层，便于选择歌曲。
- 歌单详情页需要保持选中行居中和完整页面显示；普通非骷髅布局不要再回到过右、偏下、右侧被裁切的详情页位置。
- 歌单详情页打开时要和封面粒子/画布绑定旋转与轻微移动，不能像相机贴片一样硬跟随镜头；中心高亮行应尽量和歌词保持同一水平线，面板不能显小、偏下。
- 歌词与封面粒子画布的绑定必须使用同一个世界位置和世界四元数基准；不要再用相机坐标轴叠加封面欧拉角，否则左上方俯视/大角度旋转时会出现歌词偏轴、倾斜过度、像绕另一个轴运动的 bug。
- 歌单详情页打开时歌词必须主动让出可读性：降低歌词 renderOrder/亮度/辉光/可读性层，详情页中心高亮行不能被歌词横穿遮挡，尤其固定/静态状态下。
- 安魂/骷髅预设打开 3D 歌单架时，应保持左侧大骷髅近景、右侧偏中歌单架构图。

## 禁止回退

- 不要恢复 3D 歌单架强制切回星河预设的问题。
- 不要恢复常驻歌单架长期遮挡歌词的问题；常驻默认退后，只有悬停/选中卡片才浮到歌词上层。
- 不要恢复滚动选中高亮不跟随、滚轮热区吃掉封面粒子半屏、或选择音效完全静默的状态。
- 不要把静态/固定镜头默认角度改回 0；不要让详情页打开后硬跟随镜头、偏小、偏下或脱离画布粒子运动。
- 不要恢复歌词在画布大角度旋转时偏轴倾斜、或固定详情页被歌词发光层挡住的状态。
- 不要恢复详情页被卡片遮挡、滚动卡手、按钮设计偏差、Home 与后方歌单架误穿透的旧问题。
- 不要恢复详情页右侧被隐藏、整体偏下不居中的旧布局。
- 不要让右键唤起歌单架时误唤出底部播放器控制台；歌单架打开期间应抑制底部控制台热区。
- 不要因为 shelf 重建或 3D 详情列表绘制失败而误报“歌单加载失败”。
