immersive-scroll

把静态资料（PPT / Word / PDF / 图片目录）编排成单文件沉浸式 HTML 滚动页——可离线、双击即用、能直接微信发出去。

一句话区分：这不是格式转换，是叙事重构。

PPT 是分页的、绝对定位的；网页是滚动的、响应式的。像素级还原必然在手机和投屏上崩，所以交付目标是重建信息层级，而不是复刻版式。

---

怎么用（给人看的部分）

你不需要记住这个技能的名字。直接对 AI 说一句人话就行：

把这个 PPT 做成能发微信的单文件网页

把这份产品手册做成一个能滚动浏览的 H5，手机上也要好看

给这份资料加滚动动画，要有一层层展开的感觉

AI 会自己判断要不要走这个技能。

脚本（能跑的那部分）

文档之外，本仓库带三个可执行脚本与一份合成样例：

python scripts/extract_pptx.py deck.pptx ./work        # 第 1-3 段：探针 / 提取 / 压缩
python scripts/build_single_html.py --work ./work \
    --sections my_sections.py --out ./out/deck.html    # 第 5-6 段：组装单文件 + 静态自检
node scripts/verify_single_html.js ./out/deck.html     # 第 7 段：双视口真机取证

第 4 段（叙事重构）没有脚本，也不该有——按内容语义归章是人的判断，自动化只会退回"按页码等分"，那正是本技能明令禁止的做法。

编排写在 my_sections.py 里，形式和手写 HTML 一样，没有中间 DSL：page.T(页号, 前缀) 取原文、page.fig(key, 图注, 类名) 出图。

内置样式分两层：机制层（防横向溢出、防图片变形、懒注入骨架、定值画框——恒注入不可关）与版式层（配色/间距/栅格，默认注入）。想彻底换成自己的视觉：加 --no-pattern 关掉版式层，再用 --css 带上自己的样式（重定义 :root 变量即可改配色）。

examples/minimal/ 里有可直接改的编排示例、现场绘制的合成样例 PPTX，以及四步跑通说明。

三档漫游（开工前定档）

档	内容	代价	适用
甲 · 静态滚动叙事	淡入 + 章节导航 + 点击放大	零依赖，纯手写 JS	通用默认
乙 · 漫游	甲 + GSAP / ScrollTrigger / Lenis 全内联（约 133 KB）；钉住擦洗、剖面穿越、序列入场	+133 KB；移动端必须降级	有"穿越 / 序列入场"叙事诉求
丙 · WebGL / Three.js	3D 场景	体积大、低端机崩、维护重	已否决，不再提

乙档两条硬约束，都是实测代价换来的：

• 库必须内联，不得用 CDN（否则不满足"离线双击即用"）。
• 移动端（≤960px）钉住 / 擦洗一律降级为普通滚动——微信内置浏览器对 sticky 和 100vh 不稳定。
• 横向劫持滚轮默认不做：滚轮上下 → 内容横移属于输入方向与视觉方向错配，实测会让用户无法浏览内容。要横向内容，用 overflow-x:auto 让用户自己滑。

已验证矩阵（请先看这个）

输入源	状态	说明
PPT / PPTX	T1 已实测	全链路可复现：scripts/ 三个脚本 + examples/minimal/ 端到端跑通（含双视口取证）
Markdown / 纯文本长文	T1 已实测	无图片源，直接解析标题层级/列表/加粗/表格。见 SKILL.md 版本记录 v2.6.0（1,208 行 md → 35 条长文单文件页，4.25 万字正文全量保留）
DOCX	T2 未验证	只提供判据，不提供"已验证步骤"
PDF	T2 未验证	同上；扫描件无文本层需 OCR，工作量另议
图片目录	T2 未验证	无文本时章节全靠口述，先问再动

T2 纪律：未实测的源只写判据，不写"已验证步骤"。跑通任一 T2 源后，请把实测命令与坑回填并升为 T1——欢迎 PR。

核心方法论（三句话）

1. 不对齐内容，对齐"框"。 素材比例不可控是常态（实测极差 14 倍），任何单维度硬对齐都会把代价转到另一个维度。统一画框 + contain + 同图模糊底，把不可控约束吸收进机制。
2. 判据分三层。 结构级（数量、类名、控制台）、几何级（盒子比例 vs 素材比例）、语义级（图文配对、对比标签是否成立）。前两层可脚本断言，语义级只能人工读图——必须写成强制步骤，否则必漏。
3. 取证异常先证伪测量链路。 截图黑屏、滚不到位、读图结论相反，三次都是测量工具失真，不是被测对象坏了。

完整内容见 SKILL.md：七段流水线、17 条实测坑、M1–M7 机制层判据、验收判据表。

环境依赖

• 提取与构建：Python 3 + python-pptx + Pillow
• 乙档：npm 取 gsap 与 lenis（不随本仓库分发，见下方许可）
• 取证：playwright-core + 本机已缓存的 chromium（无需重新下载浏览器）

第三方许可

完整声明见 THIRD-PARTY-NOTICES.md。

• GSAP 3.15 — Standard "No Charge" License。商用允许；禁止用于"无代码可视化动画构建器"类竞品。该许可不允许单独分发 GSAP 本体，因此本仓库不附带 gsap.min.js，请在构建时从 npm 获取并内联。
• Lenis 1.3.26 — MIT。

以上为对许可条款的解读，不构成法律意见。用于商业产品前请自行复核 gsap.com/standard-license 现行文本。

贡献

最欢迎的三类：

1. T2 输入源实测回填（docx / pdf / 图片目录）——跑通后把命令与坑写进 SKILL.md 的输入源表并升 T1。
2. 新坑——请附实测数据（现象数值、复现条件、修法），不接受"经验之谈"。
3. 修复归因错误——本技能已修正过两处误诊（见坑 9、坑 13），欢迎继续证伪。
4. 脚本缺陷——scripts/ 三个脚本的正确性问题（判据漏测、跨平台失效、边界崩）尤其欢迎；请附能复现的最小输入。

License

本仓库以 MIT 许可发布，见 LICENSE。

第三方组件（GSAP / Lenis）的许可声明见 THIRD-PARTY-NOTICES.md。