Pryne 前端调试手册

Pryne 前端调试手册 是做什么的？

针对 Pryne 的纯 JS 演示构建的症状→分类指南：由 window.Roll 模块骨架（design-demos/js/roll-*.js）驱动的单文件 HTML 页面，包含带 2D 降级的 WebGL 颗粒着色器、一个 rAF 渲染循环、自带的 Lenis 平滑滚动，以及从 CDN 异步加载作为渐进增强的 GSAP。

必需背景： 超能力：系统化调试 拥有通用的根本原因鉴别规则（未经调查不得修复）。请遵循该规则；本技能仅提供项目特定的症状表和陷阱。

工具： 关于如何驱动浏览器、捕获控制台、模拟减量运动以及记录跟踪信息，请使用 pryne-browser-lab。本技能假定您已能执行这些命令。

首先阅读头部注释

每个 v4 演示（design-demos/ 中的 v4-a 至 v4-d）都将其审核历史记录为文件顶部的 HTML 注释——包含发现的问题、修复内容及原因。截至 2026-07-22，已对所有四个文件进行验证。在重新诊断任何问题之前，请使用 head -30 查看您正在调试的演示。 您发现的多个“错误”已被记录为已修复的回归问题；如果某个问题再次出现，您需要寻找导致回退的原因，而非新原因。

还需了解构建布局（截至 2026-07-22）：只有 v4-d-hybrid.html 使用共享的 roll-*.js 模块。v4-a/b/c 是范围较小的比较构建，带有各自的内联 JS——此表中的 Roll 特定检查不适用于它们，但相同的故障类别仍然适用。

零控制台错误是默认状态

标准是零控制台错误（design-demos/DECISIONS.md 中的 CRITIQUE 评分标准要求如此）。根据项目状态日志，v3 已确认为零错误；v4 变体在方向决策活动（pryne-design-direction-decision）之前尚未认证。任何控制台错误都是需要分类的缺陷，而非可忽略的环境噪声。

症状→分类表

症状	可能原因	判别检查
动画/开发面板在其所在区域滚动进入视图之前运行（或完成）	可见性门控回归。v4-d 头部注释将此记录为优先级最高的审核修复：功能面板“从页面加载时无条件触发，并在任何人滚动到它们之前完成解析”。开发必须基于面板的 .in 类进行门控。	下方实验 1
揭示动画剪辑错误、跳跃或从不触发	clip-path 应用于 IntersectionObserver 监视的元素，而非内部包装器。概念 C 的修复（已带入 v4-d，根据其头部注释）：clip-path 揭示位于内部包装器上，绝不位于被监视的元素上。	检查元素：被监视的节点和剪辑节点是否相同？
操作系统光标消失，无自定义光标替代	不应再次发生——已于 2026-07-22 修复（由冷测试审核发现，并于同日修复）：每个事件处理程序（roll-cursor.js:17-20）及其 pointermove 调用点（roll-core.js:26-29）现在都在原始设置时捕获的基础上进行捕获并恢复（Roll.cursorUpdate 置空，移除 .custom-cursor）；#cur/#ring 的 z-index 从 50 提升到 70，高于 #flash（60），因此高潮脉冲无法覆盖光标。如果症状再次出现，则这些保护之一已回归，或新代码在此约定之外隐藏了光标。	document.body.classList.contains('custom-cursor') 与 Roll.cursorUpdate——true/null 同时出现是故障状态；如果两者看起来正常，请检查 getComputedStyle(cur).opacity 以及是否仅在高潮闪光时消失
WebGL 鬼影/拖尾，或颜色与页面混合错误	缺少每帧清除，或预乘 Alpha 不匹配。roll-shader.js 每帧调用 gl.clear(gl.COLOR_BUFFER_BIT)，并以 { alpha: true, premultipliedAlpha: false } 创建上下文（均为审核修复，根据 v4-d 头部注释）。	对比 roll-shader.js 与 git：git diff HEAD -- design-demos/js/roll-shader.js
着色器画布空白，无颗粒效果	(a) 减量运动——GL 有意从未设置（useGL = !Roll.reduced && setupGL()）；(b) WebGL 上下文丢失——webglcontextlost 处理程序将画布不透明度设为 0 并静默失败；(c) 在 WebGL 获得机会之前已获取 2D 上下文（每个画布仅允许一个上下文——在 roll-shader.js 顶部有说明）。	首先检查 Roll.reduced。对于上下文丢失，请检查处理程序的可观察效果：getComputedStyle(document.getElementById('tone')).opacity === '0'。注意：Roll.shader.useGL 是设置时的快照（roll-shader.js:120-121）——webglcontextlost 处理程序仅翻转闭包变量（roll-shader.js:130-132），因此上下文丢失后 Roll.shader.useGL 仍为 true；请勿用它来排除丢失
滚动编排失效，但页面渲染和滚动正常	脚本加载顺序或 window.Roll 命名空间中断。脚本顺序至关重要——其链和检查命令位于 pryne-frontend-architecture 中。每个模块都是一个仅通过 window.Roll 共享状态的 IIFE；早期模块中的一次抛出错误会导致之后的所有模块无法执行。	下方实验 2；控制台将显示 Roll.X is undefined，指明被饿死的模块
仅某用户报告所有动画失效；在您的机器上正常	他们已启用 prefers-reduced-motion。这是正确行为，而非错误：roll-core.js 从媒体查询设置 Roll.reduced，并且每个模块都基于此进行门控（封面移除，面板立即完全展开渲染，跳过 Lenis，着色器关闭）。请勿“修复”它。	下方实验 3
不同设备（触摸板/滚轮/触摸屏）滚动感受不一致	原始滚动增量差异——内置 Lenis 的文档化理由（请参阅 design-demos/DECISIONS.md）。Lenis 包装原生滚动，因此 window.scrollY 仍然有效；它仅为体验升级，在减量运动下无效。	typeof Lenis（是否已加载？），然后检查演示在其滚动模块中是否构造了它
基础功能正常，但悬停/动态/光标优化缺失	GSAP CDN 失败或已被阻止。GSAP 从 jsdelivr（SRI 锁定）以 async 方式加载，并仅在其加载完成时通过 Roll.upgradeMotion() 将 Roll.enhanced = true 翻转。渐进增强是有意设计的：基础编排必须仍能在没有它的情况下正常工作。如果基础功能也损坏，则这不是您的原因。	下方实验 4
音频静音	静音是默认状态：roll-audio.js 以静音启动，将选择持久化在 localStorage['ch001_muted'] 中，并且仅在单击 #mute-toggle 时（用户手势，满足自动播放策略）才开始环境嗡声。所有合成均包含 try/catch 并且无资产依赖。在怀疑代码之前，请检查 SND 切换状态。	Roll.audio.muted 和 localStorage.getItem('ch001_muted')
固定 HUD 重叠/遮挡页脚	页脚淡出修复回归：footer 上的 IntersectionObserver 切换节拍器和静音按钮的 .faded 类（roll-scroll.js）。	滚动到页脚；检查 .faded 是否出现在 #beatmeter 上

判别性实验

在页面控制台中运行这些实验，或通过 evaluate_script（请参阅 pryne-browser-lab）。每个实验在您修改代码之前回答一个关键问题。

1 — 面板开发是否正确基于可见性进行门控？

({ workVisible: document.getElementById('work').classList.contains('in'),
   plate1: { d: Roll.featurePlate.d, done: !!Roll.featurePlate.done },
   plate2: { d: Roll.featurePlate2.d, done: !!Roll.featurePlate2.done } })

在全新加载时，在滚动到 work 区域之前：workVisible: false 且两个 d 值接近 0。如果 d 在增加（或 done: true）而 workVisible 为 false，则门控已回归。

2 — Roll 骨架是否完整？

({ core: !!window.Roll, reduced: Roll?.reduced, enhanced: Roll?.enhanced,
   shader: !!Roll?.shader, audio: !!Roll?.audio, plates: !!Roll?.plates,
   cursorUpdate: Roll?.cursorUpdate === null ? 'null' : typeof Roll?.cursorUpdate })

关于 cursorUpdate：它初始化为 null（roll-core.js:23），并且在 GSAP 加载之前以及在没有 pointer: fine 的设备上也为 null——单独为 null 不能证明任何问题。仅当 document.body.classList.contains('custom-cursor') 为 true 且 cursorUpdate 为 null 时（请参阅分类表中的光标行），才表示“故障安全”。

任何 false/undefined 都指明了未完成的模块——请在控制台中检查抛出的错误，并在 HTML 中检查脚本顺序是否符合上述关键顺序。

3 — “所有动画失效”是否仅仅是减量运动？

({ mediaQuery: matchMedia('(prefers-reduced-motion: reduce)').matches, roll: Roll.reduced })

两者均为 true → 按设计工作；通过模拟减量运动（pryne-browser-lab）复现报告。mediaQuery: true 但 roll: false（或反之）→ 模块正在读取错误的信息源。

4 — GSAP 增强层是否加载？

({ gsapLoaded: !!window.gsap, enhanced: Roll.enhanced, reduced: Roll.reduced })

gsapLoaded: false → CDN 被阻止/失败（检查网络面板中的 jsdelivr 请求；SRI 不匹配也会导致此结果）。gsapLoaded: true, enhanced: false, reduced: false → upgradeMotion() 未运行——请检查脚本标签的 onload 钩子。

会浪费大量时间的陷阱

陷阱	故事（一句话）	防护措施
“已验证可工作”≠ 正确方向	v3 NIGHT DRIVE 已完全构建，零控制台错误，已验证——然后被取代，因为统一概念错误（完整说明：pryne-failure-archaeology）。	不要花费精美化/调试努力来维护一个其概念尚未被确认为当前方向的构建。首先检查 DECISIONS.md 和存储库状态。
重新诊断已记录的修复	每个 v4 头部注释都是一个已发现、已修复缺陷的变更日志。	在打开开发者工具之前阅读头部注释。如果列出的修复似乎被破坏，请寻找回退原因，而非症状本身。
“修复”减量运动	所有动画关闭是 prefers-reduced-motion 用户的设计行为，在一处进行门控（Roll.reduced）。	在将无动画报告视为缺陷之前，请运行实验 3。
为了“测试某些东西”而获取 2D 上下文	画布只能有一种上下文类型；先获取 2D 会使该画布上的 WebGL 永久不可用（在 roll-shader.js 中已说明）。	切勿在控制台实验中调用 getContext('2d') 处理 #tone。

何时不使用此技能

• 通用调试规范（假设、最小更改、根本原因优先于修复）→ 超能力：系统化调试。
• 如何驱动浏览器/进行测量（MCP 工具详解、跟踪、Lighthouse、截图）→ pryne-browser-lab。
• 判断行为是否违反设计规范（减量运动门控、细语级别个性、自带依赖）→ pryne-frontend-architecture。
• 构建/回退原因的完整历史→ pryne-failure-archaeology。
• 其他技术栈（React/框架构建、非 Pryne 项目）：上表特定于 window.Roll 演示家族；仅通用规范可迁移。

来源与维护

运行 scripts/verify.sh（在此技能目录中）以一次性检查以下所有内容。

事实截至 2026-07-22，已验证于仓库 ~/Documents/Coding Folder/Portfolio (test) 的提交 457868a。请在信任之前重新验证：

• 模块列表及大小：wc -l design-demos/js/*.js
• 脚本加载顺序：grep -n "<script" design-demos/v4-d-hybrid.html
• 哪些演示使用共享模块：grep -l "roll-core.js" design-demos/*.html
• 头部注释约定仍有效：for f in design-demos/v4-*.html; do echo "== $f"; head -5 "$f"; done
• 减量运动门控：grep -n "prefers-reduced-motion\|Roll.reduced" design-demos/js/*.js
• 面板可见性门控：grep -n "classList.contains('in')" design-demos/js/roll-scroll.js
• Lenis 自带并已连接：ls design-demos/js/vendor/ && grep -n "new Lenis" design-demos/js/roll-scroll.js
• GSAP 增强钩子：grep -n "upgradeMotion" design-demos/js/roll-core.js design-demos/v4-d-hybrid.html
• 音频静音默认值及存储键：grep -n "ch001_muted" design-demos/js/roll-audio.js
• 零控制台错误标准：grep -n "console errors" design-demos/DECISIONS.md