oil-ui-pro 0.15.4 → 0.22.2（上游 ui.oiloil.org 正式包）＋ 记 P0-98 跨盘 rename 坑

- oil-ui-pro 升到 0.22.2：references 13→28 份（新增 16、删 imagery.md）、assets 增 cards/（22 组）与 fonts/、SKILL.md 顶层五步结构未改名。
- 升级路径：官方 `npx github:oil-oil/oil-cli update` 稳定失败（error=replace、报「检查目录权限」）。
  真身为 EXDEV —— 解压在 os.tmpdir()（C 盘）、技能目录在 E 盘，Windows 上 rename 不能跨盘；
  CLI 的 catch 把非 CliError 原生异常一律兜底成 replaceFailed，真错误一个字不吐。
  做法＝借其 prepare() 只做下载+校验，再 cp 到同盘 stage、rename 交换；官方命令复验 up_to_date。
- 回归：product-planning 按名引用的 visual-review.md／tools.md／design-direction.md／style-explorer.md 全部健在；命名闸门 2061｜0｜27。
- session-mechanism/references/pitfalls.md 新增 P0-98（含通则：更新器把原生错误兜底成指错方向的人话）。

oil-ui-pro/references/motion.md

@@ -2,23 +2,23 @@
 
 ## 每个界面先做三处动效
 
-完全不动的界面像一张截图：按下没有回应，切换没有来路，用户只能猜刚才发生了什么。新界面和改动了操作流程的界面，先把这三处做出来，手感写进方向卡的“动效”一栏：
+完全不动的界面像一张截图：按下没有回应，切换没有来路，用户只能猜刚才发生了什么。新界面和改动了操作流程的界面，先把这三处做出来，手感写进方向卡的“动效”一栏，改流程和加新功能时写进方案卡或设计说明：
 
 1. **主操作的反馈。** 按下立刻有回应，完成时交出一个结果：按钮陷下去再弹回，勾号画出来，数字滚到新值。
 2. **一处状态切换的来路。** 选中、展开、换视图、增删列表项时，让人看见东西从哪里来、到哪里去，见下文“界面过渡”。
 3. **第一次进入时的一次出场。** 主角先到，其余按阅读顺序跟上，只在首次进入时播放。
 
-这三处之外再加动效，先问：如果要手写一周才能做出来，还值得做吗？模型让动效变得免费，但滚动淡入、视差、跟随鼠标和装饰性循环最容易变成干扰。每个动效都要承担反馈、引导、连续或品牌表达中的一项。
+这三处之外再加的动效，每个都要承担反馈、引导、连续或品牌表达中的一项；滚动淡入、视差、跟随鼠标和装饰性循环最容易变成干扰。
 
 | 目的 | 适合考虑的方式 |
 | --- | --- |
-| 按下、聚焦、展开或普通状态变化 | 原生能力或已有组件的小范围过渡 |
+| 按下、聚焦、展开或普通的状态变化 | 用浏览器原生的过渡，或已有组件自带的小过渡 |
 | 视图之间的切换、元素换位置 | 共享元素过渡，见下文“界面过渡” |
-| 拖拽、手势、空间变化与复杂编排 | 项目已有成熟动效能力 |
-| 特殊品牌画面、材质、复杂物理效果 | 图片、3D、着色器或预渲染视频，按需求取舍；着色器能做的效果见 [点缀与特效](ornament.md) |
-| 鼠标、触控或滚动控制叙事进度 | 将输入映射到明确的动画进度，处理反向和快速操作；思路见下文“滚动叙事” |
+| 拖拽、手势、位置和大小的变化、多个元素配合的动画 | 用项目里已有的成熟动效库 |
+| 特殊品牌画面、材质、复杂物理效果 | 图片、3D、着色器或预渲染视频，按需求取舍；什么时候用实时 3D 见 [素材](media.md) |
+| 用鼠标、触控或滚动控制一段叙事的进度 | 让动画的进度直接跟着输入走，往回滚和快速操作都要处理好；见 [滚动叙事](scroll-narrative.md) |
 
-代码动画适合需要精确状态控制的界面，生成视频适合预先确定的视觉变化；不能用视频替代需要动态数据与真实操作的控件。
+需要精确控制状态的界面，用代码写动画；画面怎么变早就定好的，可以用生成的视频。要显示实时数据、要让人真的去操作的控件，不能用视频代替。
 
 ## 手感
 
@@ -41,22 +41,17 @@
 
 ## 呼应：让动作彼此接上
 
-生硬的动效各动各的：按钮自己闪一下，面板自己滑出来，数字直接换掉。好的动效像一句话：一个动作引起的变化沿同一条路传下去，前一段的终点是下一段的起点。
+一个动作引起的变化沿同一条路传下去，前一段的终点是下一段的起点；不要按钮、面板和数字各动各的。
 
 - **从被操作的地方出发。** 点“加入购物袋”，商品缩成一个点飞进袋子，袋子上的数字跟着跳一下；删掉一行，它朝删除按钮的方向收走，下面的行补上来。
 - **一次切换朝一个方向。** 卡片往左滑，标题、序号和底色也往左换；数字往上滚，进度也往上涨。方向一乱，就成了几段互不相干的动画。
 - **主角先动，其余被带动。** 被影响的东西晚 40–80ms 跟上，幅度更小，像被主角拉过去的。全部同时起跑、同样幅度，看起来只是一起闪了一下。
 - **形状接力。** 上一个状态里的元素变成下一个状态里的元素：按钮展开成面板，搜索图标拉长成输入框，播放键变成暂停键。用户一眼看出它们是同一个东西。
-- **动法和画面是同一种材质。** 纸面的方向，切换轻、有一点停顿；硬件的方向，开关有咔嗒到位的感觉；液体和玻璃的方向，用流淌和折射。
+- **动法和画面是同一种材质。** 动作的轻重、停顿和回弹从方向卡的生成引擎和控件语法推出。
 
 ### 巧思从产品里找
 
-巧思是让一处动效讲出这个产品自己的事，不是加更多花样。从内容里找一个只有它才有的动作：
-
-- 天气应用切到雨天，雨点落在卡片上；雨停以后，卡片上的水痕慢慢干掉。
-- 记账应用记下一笔支出，预算条少掉的那一截落进这笔账里。
-- 音乐播放器换歌，新封面的颜色从唱片中心漫到整个背景。
-- 完成待办时，勾号用和品牌标志相同的笔画画出来。
+巧思是让一处动效讲出这个产品自己的事，不是加更多花样。写成一句：这个产品里的哪样东西，因为用户的哪个动作，发生了只有它才会有的变化。
 
 找不到这样的动作，就把三处基本动效做准，不硬造。一页最多一两处巧思，其余动效安静、短促。
 
@@ -78,6 +73,16 @@
 
 **到头要有反馈。** 已经是第一项或最后一项时，轻轻顶一下（往返 10–15px），而不是毫无反应。
 
+### 整页转场的稳定性取舍
+
+整页切换和组件的过渡不一样：旧页面要卸载，新页面要挂载。按稳不稳、难不难做，分三类：
+
+- **遮罩式（Curtain / Wipe）。** 用一块纯色、纹理或几何形状划过或盖住整个屏幕，趁挡住的时候卸掉旧页、挂上新页。它最简单、最稳，两个页面的结构互不相干，绝大多数页面都适合。
+- **交叠式（Overlapping）。** 新旧两页同时在屏幕上，互相错开、推挤，或者分层淡入淡出。看起来连贯，但两页的 DOM 要同时存在，层级和内存都要管好。
+- **共享元素式（Shared Element）。** 一个关键元素从旧页一直变形到新页，例如缩略图放大成详情页的主图。看起来最顺，也最容易出问题：用户快速双击、中途打断、后退，或者视口变了，都容易错位和闪烁，所以必须留好退路，出问题时直接显示到位的状态。
+
+第一次进站的加载屏（Splash），可以在等大文件加载的时候放一小段叙事或进度；站内的页面跳转，时长按下面“时长和幅度”里整页切换的取值，不让转场挡着用户看内容。
+
 ## 时长和幅度
 
 | 对象 | 时长 | 要点 |
@@ -88,37 +93,27 @@
 | 整页或视图切换 | 350–500ms | 超过 500ms 就会让人等 |
 | 首次进入时依次出现 | 每项间隔 40–80ms | 总长不超过 600ms；只在首次进入时播放，重新渲染和恢复状态时不重播 |
 
+这张表管的是界面操作。游戏和抽奖的演出时长见 [游玩](play.md)。
+
 悬停上浮 2–4px，阴影随之加深。位移超过 20px 的悬停效果会显得轻浮。
 
 ## 看不见的结果要说出来
 
 一次点击产生了看不见的副作用，例如复制到剪贴板、后台保存、发送，就用一条短暂的提示说出结果本身，例如“已复制：……”，而不是只说“成功”。确认类的时刻，例如选中或完成，可以用一次小幅弹出，只在状态第一次变化时播放，重复点击不重播。
 
-## 滚动叙事：视差与一镜到底
-
-滚动当作翻页，它只是翻页；当作摄影机的推拉，页面就能讲故事。品牌、发布和叙事页可以这样做，文档、文章、工具和后台不做；一页最多一段。记忆点先放在用户会做的动作上（点按、拖动、悬停），再考虑滚动；不要把整页做成视差秀。
-
-- **一镜到底。** 整段是一次不切换的镜头。一个主角从头走到尾，可以是产品、一根线、一个形状或一个字，每一步长成、变成或让出下一个画面：推近看到细节，拉远看到全貌，转过去看到背面，穿过去进入下一个场景。动手前先画分镜：每个镜头占多少滚动距离、画面里有什么、什么在动、文字什么时候出现。
-- **停下来再说话。** 每个镜头留一段静止，文字在静止时出现；边动边读很累。
-- **视差要有真实的前后。** 只在画面本来就有远近层次时用：前景的物体、中景、远处的背景，越近动得越多，差别要小。文字不做视差。
-- **转场也是镜头。** 一个圆从某一点扩开，带出下一节；推进一张图，穿过它到达下一节；背景色在章节之间随阅读慢慢变；一句宣言随滚动逐字亮起。每种手法一页只用一次。
-- **倒着滚也成立。** 每一帧只由滚动位置决定，往回滚自然倒放，刷新或跳到中间也立刻是对的画面。不接管用户的滚动。
-- **留出口。** 长段落前给一个跳过入口；减少动态效果时，把每个静止画面按顺序排成普通区块。
-- **代码做不出来的，交给视频。** 用户想要很强的首屏动画，而效果要靠生成视频或序列帧才做得出来，例如角色转身、产品拆解、镜头穿越场景，可以告诉用户用 [oil-motion](https://github.com/oil-oil/oil-motion) 来做。CSS、SVG、着色器能完成的仍自己做；同一次对话只提一次。
-
 ## 体验与性能
 
-沿用项目的运动节奏和组件能力。高频操作反馈直接，不让动画延迟业务完成。
+项目里已有的动效节奏和组件能力先沿用。经常要做的操作，反馈要立刻给，不让动画拖慢事情本身。
 
 动画要能被打断。连续快速操作时，新动画从当前位置接着走，不跳回起点重播。CSS 过渡会从当前值重新出发，适合高频切换；关键帧动画会从头重播，适合一次性的出场。业务状态立即更新，不等动画结束。
 
-网页连续动画优先用变换与透明度，只声明需要变化的属性；小尺寸的指示块可以直接过渡宽高。逐帧工作要有停止和清理条件，避免频繁交错读写布局，离屏或无任务时停止播放。整页过渡期间页面通常不响应点击，所以整页过渡要短。
+网页上连续播放的动画，优先只动变换和透明度，过渡里只写会变的那几个属性；很小的指示块可以直接过渡宽高。每一帧都要执行的代码，要有停下来和清理的条件，不要一会儿读布局、一会儿写布局地来回交替；滚出屏幕或没事可做时就停。整页过渡期间页面通常点不动，所以整页过渡要短。
 
-明显位移、缩放和滚动特效，要为“减少动态效果”提供等价呈现，此时所有状态直接到位。必要信息和主要操作不能依赖自动播放、声音或动画完整结束。
+有明显位移、缩放或滚动特效的地方，要照顾开了“减少动态效果”的用户：这时所有状态直接到位，内容一样不少。必要的信息和主要的操作，不能等自动播放、声音或动画播完才出现。
 
 ## 检查动效
 
-静态截图证明不了动效。三处基本动效和动效记忆点都要留证据：一段 3–5 秒录屏，或开始、中间、结束三帧，并写明触发它的动作。把播放速度调到 10%，可以用浏览器开发者工具的动画面板，或自动化工具里的动画倍速，在过渡进行到一半时截图。看有没有重影、跳动、元素突然出现，或者从奇怪的位置飞来。逐个检查开始、中间、结束和反向；再快速连按几次，确认不会卡在中间状态。最后开启“减少动态效果”再走一遍。只有实际测量后才报告帧率或性能改善。
+按正常速度操作一遍，再往回操作一次、快速连按几次：没有重影和跳动，元素不突然出现，不从奇怪的位置飞来，不卡在中间状态。开启“减少动态效果”后内容直接可读。只有实际测量后才报告帧率或性能改善。
 
 ## 网页实现提示