001 浮层开合瞬移（HIGH）#

病灶（改前行号）：src/styles/main.css:487 的 .float-panel 基类只有

1
@apply ... transition-colors duration-150 ...

transition-colors 只覆盖颜色族，而关闭态 .float-panel-closed 切的是 opacity 和位移——没有额外工具类的面板（搜索面板 Search.svelte、导航快捷面板 Navbar.astro）开合就是瞬移；另有 4 个面板靠 markup 里的 transition-all 苟活（transition: all 本身是禁项）。

本项目最关键的冷知识：Tailwind v4 把位移编译成了独立的 translate 属性，不是 transform。构建产物实测：

1
/* .float-panel-closed 的编译结果 */
2
.float-panel-closed {
3
  pointer-events: none;
4
  --tw-translate-y: calc(var(--spacing, .25rem) * -1);
5
  translate: var(--tw-translate-x) var(--tw-translate-y); /* ← 独立属性！ */
6
  opacity: 0;
7
}

所以 transition 里必须写 translate——写 transform 修了个寂寞。

修复（main.css，改后）：

1
.float-panel {
2
    @apply top-21 rounded-(--radius-large) overflow-hidden bg-(--card-bg) shadow-xl border border-black/5 dark:border-white/10;
3
    transition:
4
        opacity var(--duration-normal) var(--ease-decelerate),
5
        translate var(--duration-normal) var(--ease-decelerate),
6
        color var(--duration-normal) var(--ease-standard),
7
        background-color var(--duration-normal) var(--ease-standard),
8
        border-color var(--duration-normal) var(--ease-standard);
9
}
10
@media (prefers-reduced-motion: reduce) {
11
    .float-panel {
12
        transition:
13
            opacity var(--duration-normal) var(--ease-standard),
14
            color var(--duration-normal) var(--ease-standard),
15
            background-color var(--duration-normal) var(--ease-standard),
16
            border-color var(--duration-normal) var(--ease-standard);
17
    }
18
}

同时从 4 个 markup 里删掉 transition-all 这一个词（其余 class 不动），让全站浮层回归同一套机制：

• Navbar.astro（music-nav-panel）
• NavMenuPanel.astro（导航菜单卡片）
• DisplaySettingsIntegrated.svelte
• LightDarkSwitch.svelte

运行时验证：getComputedStyle(#search-panel).transitionProperty 应为 opacity, translate, color, background-color, border-color，时长 0.15s；关闭态 translate: 0px -4px。

002 详情模态：补退场、背板补入场#

病灶：AnimeDetailModal.svelte / BilibiliDetailModal.svelte（同构双文件）——背板 bg-black/60 随 {#if anime} 瞬现瞬消；卡片入场是 CSS keyframes（内置 ease-out 偏弱），关闭时 Svelte 直接摘 DOM，没有退场。

修复：用 Svelte transition 同时接管进、出（transition 可中断，keyframes 会从零重播），并删掉原 @keyframes animate-in：

1
<script lang="ts">
2
import { cubicOut } from "svelte/easing";
3
import { fade, fly } from "svelte/transition";
4
</script>
5

6
<!-- 背板 -->
7
<div
8
  use:portal
9
  in:fade={{ duration: 200, easing: cubicOut }}
10
  out:fade={{ duration: 150, easing: cubicOut }}
11
  ...
12
>
13
  <!-- 卡片：删掉 class 里的 animate-in，加 -->
14
  <div
15
    class="... scale-90 sm:scale-100"
16
    in:fly={{ y: prefersReducedMotion() ? 0 : 10, duration: 200, easing: cubicOut }}
17
    out:fly={{ y: prefersReducedMotion() ? 0 : 10, duration: 150, easing: cubicOut }}
18
  >

• 入 200ms / 出 150ms：退场快于入场的非对称节奏，均在模态 200–500ms 档与 UI <300ms 红线内；
• cubicOut 是 svelte/easing 的具名强 ease-out（JS 消费不了 CSS 的 cubic-bezier 字符串，用框架自带函数而不是手搓近似值）；
• 卡片上的 scale-90 在 Tailwind v4 编译为独立 scale 属性（实测产物 .scale-90{...scale:var(--tw-scale-x) var(--tw-scale-y)}），与 fly 写的 transform: translateY() 互不打架；
• prefersReducedMotion() 把位移归零、保留淡出。

验证：Esc 关闭后 [role="dialog"] 应滞留在 DOM 里跑完 150ms 退场才被移除（旧实现是瞬间蒸发）；打开后 200ms 内立刻 Esc，退场应从中途状态接管而非闪回起点。

003 公告栏关闭——四个只有实测才现形的 bug#

病灶：Announcement.astro 的关闭按钮原本是一行 onclick="...style.display='none'"，一击瞬隐、侧栏下方组件全体跳位。

布局前提（动手前必须确认）：widget-layout 是 SideBar.astro 里 flex flex-col gap-4 容器的直接子项——flex 子项会被 blockify，max-height 才可用；gap-4 = 1rem。

最终方案（三层）：

1. max-height: 实测高度 → 0 做折叠（高度动画在「手风琴/折叠」场景是被豁免的）；
2. margin-bottom: 0 → -1rem 吞掉父容器一个 gap——否则元素收成 0 高后两侧 gap 还在，动画结束 display:none 那一帧会再跳 16px；
3. 淡出不能做在根元素上（原因见坑④），做在子元素上。

最终 onclick 全文（可直接照抄）：

1
onclick="var w=this.closest('widget-layout');if(!w||w.dataset.closing)return;if(window.matchMedia('(prefers-reduced-motion: reduce)').matches){w.style.display='none';return}w.dataset.closing='1';w.style.maxHeight=w.offsetHeight+'px';w.style.marginBottom='0';void w.offsetHeight;requestAnimationFrame(function(){w.style.transition='max-height 200ms var(--ease-standard),margin-bottom 200ms var(--ease-standard)';w.style.maxHeight='0';w.style.marginBottom='-1rem';for(var i=0;i<w.children.length;i++){var c=w.children[i];c.style.transition='opacity 200ms var(--ease-standard)';c.style.opacity='0'}});setTimeout(function(){w.style.display='none'},240)"

踩坑全录（按发现顺序，每条都是实测抓的）：

实测曲线（每 35ms 采样一次 getComputedStyle）：

1
t=39ms   childOp=0.97  maxH=239px  mb=-0.4px
2
t=118ms  childOp=0.25  maxH=62px   mb=-12px
3
t=232ms  childOp=0     maxH=0      mb=-16px
4
t=273ms  display:none

三条属性同步走完 200ms，结束瞬间零跳位。

004 六处翻页桥接#

病灶：画廊/动态翻页时 currentPage 一改，{#each} 立即换一批卡片，整块内容瞬移替换。翻页是偶尔操作，值得一段标准动画；只动 opacity，不碰布局。

统一模式（淡出 → 换页 → 淡入，transition 而非 keyframes，快速连点可重定向）：

1
let gridFading = $state(false);
2

3
async function goToPage(page: number) {
4
  if (page === currentPage) return; // 原有 bounds 检查的文件照旧保留
5
  gridFading = true;
6
  await new Promise((r) => setTimeout(r, 150));
7
  currentPage = page;
8
  await new Promise((r) => requestAnimationFrame(() => r(null)));
9
  gridFading = false;
10
}

容器上绑（写在容器 div 上，inline style）：

1
style="opacity: {gridFading ? 0 : 1}; transition: opacity var(--duration-normal) var(--ease-decelerate)"

六个文件：

不做：搜索打字、筛选 chip、排序下拉——键盘驱动的高频路径，加动画只会钝化（门禁第一问直接否决）。

实测曲线：1 → 0.477（60ms 淡出中）→ 换页 → 0.707（淡入中）→ 1。

005 代码组切标签桥接#

病灶：TabGroup.svelte 切标签是 block.style.display 硬换，代码块瞬移。代码是用户在读的数据——只做透明度、不做位移。

1
let tabFading = $state(false);
2

3
async function selectTab(i: number) {
4
  if (i === active || tabFading) return; // 守卫：连点不叠动画
5
  tabFading = true;
6
  await new Promise((r) => setTimeout(r, 150));
7
  active = i; // $effect 随即换 display（此刻容器不可见，硬切被藏住）
8
  await new Promise((r) => requestAnimationFrame(() => r(null)));
9
  tabFading = false;
10
}

按钮 onclick 改走 selectTab(i)；容器绑 style="opacity: {tabFading ? 0 : 1}"；scoped style 加：

1
.code-group-blocks {
2
  transition: opacity var(--duration-normal) var(--ease-decelerate);
3
}

标签下划线/颜色的既有过渡保持不动——指示器即时响应，内容随后桥接，两者分工不冲突。

选型：为什么整站只用它一处#

anime.js 的招牌是 stagger 级联、时间线编排、数字滚动——前两样站内已有 CSS 方案（onload 错峰、Swup 过渡），硬上就是「为个淡入淡出装库」。真正值得的缺口是侧栏 SiteStats.astro 的六个死数字，于是按「最小试水」原则只做这一处。

安装#

1
pnpm add animejs --registry=https://registry.npmmirror.com
2
# 装到的是 animejs 4.5.0（npm 主线就是 v4，没有所谓 v6）

v4 API 速查（从 node_modules/animejs/dist/modules/types/index.d.ts 核实，别凭记忆写）#

1
import { animate } from "animejs";
2

3
const counter = { v: 0 };
4
animate(counter, {
5
  v: end,                 // 普通 JS 对象补间：参数键名 = 对象属性名
6
  duration: 1000,
7
  delay: index * 80,      // 每行错峰
8
  ease: "outExpo",        // 合法名见 EaseStringParamNames：outQuad/outCubic/outExpo/outBack...
9
  onUpdate: () => { el.textContent = Math.round(counter.v).toLocaleString(); },
10
  onComplete: () => { el.textContent = end.toLocaleString(); },
11
});

要点：

• AnimationParams 是 Record<string, ...>——属性 tween 与 duration/delay/ease/onUpdate/onComplete 回调可以混在同一个对象里；
• ease 取值必须是导出的具名字符串或函数，"outExpo" 在 EaseStringParamNames 联合类型里；
• 目标是普通对象时走 JS 补间（JSTargetsParam），不需要 DOM。

SiteStats 实现（三个关键设计）#

1. 锚点：给统计值 span 统一加 data-stat-value（不蒜子两行是异步来的，不加、不碰）。取值时读 textContent 当终值——静态值 SSR 已是终值，动态值（运行天数/最后更新）由上方 classic script 先写好（classic script 解析期执行，模块脚本 defer 执行，顺序天然正确）。"今天" 这类非数字用 /^\d+$/ 过滤跳过。
2. 触发：IntersectionObserver（threshold 0.3）滚入视口才播，播完 disconnect；非数字、end <= 0 不播。
3. 频率守卫：sessionStorage 键 ff-site-stats-counted——真正播过才置位（这样播之前切页还能换页重试）；swup 容器含 #left-sidebar-dynamic/#right-sidebar-dynamic，切页会重渲染本组件，没有守卫的话每次切页数字都滚一遍就是骚扰。切页重挂靠 astro:page-load（不要用 swup:contentReplaced——swup 4.x 根本不派发这个旧事件）。prefers-reduced-motion 直接置守卫跳过。

两个只有实测才现形的坑#

坑①：#site-stats 在 DOM 里有两份（桌面侧栏 + 移动侧栏各一），其中一份在当前断点下是 0×0 的隐藏副本。document.getElementById 永远返回树序第一份——观察了个寂寞。

坑②（阴险）：零面积元素会被 IntersectionObserver 特判为 isIntersecting。那个 0×0 的隐藏副本躺在 (0,0)，一加载就被判「相交」，抢先把 sessionStorage 守卫置了位——可见副本的回调一看守卫已设，直接自我了断。表现为：守卫显示已播、数值却全程不动。

双保险修复：

1
// 装观察器前：滤掉零宽根
2
const roots = Array.from(document.querySelectorAll("#site-stats")).filter(
3
  (root) => root.dataset.countUpReady !== "1" && root.getBoundingClientRect().width > 0,
4
);
5

6
// 回调里：再验一次目标宽度
7
const hit = entries.find(
8
  (entry) => entry.isIntersecting && entry.boundingClientRect.width > 0,
9
);
10
if (!hit) return;

给测试者的教训：排查过程中用 page.addInitScript 清守卫是永久挂在该 Page 上的——之后每次导航都会先清 key，把「二载不重播」测了个假阳性。换干净标签页重测才拿到真结论。测试钩子本身也会污染被测行为，切记。

双载实测结果（干净标签页）#

1
首载 t=0ms   : ["42","4","65","67,866","63","1",  "26","1","0","0","0","0"]  ← 后半在滚
2
首载收敛      : 两份副本均为 ["42","4","65","67,866","63","1"]，守卫="1"
3
二载 800ms 全程: 无归零、无变化（stayFinal=true），守卫="1"

（前 6 个是隐藏副本的 SSR 终值、后 6 个是可见副本的计数——隐藏副本全程未被触碰，坑①②修复生效。）