gsap-sveltekit

GSAP SvelteKit

挂载 → 初始状态 → 入场 → 稳定 → 退场 → 结束状态 → 卸载

挂载和卸载由 Svelte 负责；动画负责两者之间的五个阶段。SvelteKit 会在参数变化时复用页面，并保留共享布局，因此新的页面生命周期不一定意味着新的节点。

保持所需的视觉效果和现有项目惯例。仅在需要时添加 GSAP/插件；除非用户提出要求，否则不要替换选定的动画库。

此技能决定动画何时运行。至于动画对象和高级感、俏皮感等风格，如果已安装 animaxxing 技能，也请加载它：其中的方案和用于寻找风格的指南可接入此生命周期。

从项目入手

阅读仓库说明、现有动画、布局、导航、CSS、无障碍惯例和检查项。然后：

1. 确认项目使用 SvelteKit 和处于 runes 模式的 Svelte 5。没有 SvelteKit 路由的纯 Svelte 项目应使用 gsap-frameworks。对于 Svelte 4 或 legacy 模式，应说明这一点，并将 $effect 相关建议映射到 onMount 和 onDestroy。
2. 读取已安装的 @sveltejs/kit 和 svelte 版本。优先参考它们自带的类型，而非凭记忆判断：node_modules/@sveltejs/kit/types/index.d.ts 记录了每个导航对象，node_modules/svelte/types/index.d.ts 记录了 runes 和生命周期导出。版本要求：onNavigate（1.24）、$app/state（2.12；此前使用 $app/stores）、导航目标上的 to.scroll（2.51）、svelte/motion 中的 prefersReducedMotion（5.7）、{@attach}（5.29）。
3. 检查 svelte.config.js、页面选项（ssr、csr、prerender）、src/app.html 中 body 上的 data-sveltekit-preload-data，以及标记了 data-sveltekit-reload 的链接。设置了 csr = false 的页面没有客户端路由器，也没有导航钩子；重新加载链接会完整加载文档。两者都应按普通文档处理。

选择动画引擎

简单的区块动画，以及只需在退场期间保留 DOM 的 {#key} 切换，使用 Svelte 的 transition: / in: / out:。需要快照变形或页面交叉淡化时，使用 onNavigate 中的 View Transitions。需要暂停实时 DOM 导航、可中断的动画序列、拆分文本或滚动联动动画时，使用 GSAP。每个元素只用一个引擎；参见组合使用多个引擎。

只阅读所需内容

• 不可见的入场动画、初始化失败、索引和首次加载性能：初始化与恢复，以及框架集成。
• 导航钩子及其顺序、导航前的退场、锁定、后退和前进、滚动、焦点、链接、预加载、View Transitions：SvelteKit 导航。
• 页面复用与重新挂载、布局、{#key} 与 afterNavigate、Svelte 5 生命周期、与 GSAP 并用的 Svelte 过渡、浅层路由模态框、SSR：页面生命周期。
• 五个阶段、GSAP 设置、上下文、显示与隐藏、布局稳定性、滚动、文本、插件：生命周期实现。
• Lenis、ScrollSmoother，或跨路由的缓动页面滚动：平滑滚动，以及钩子映射。
• 遮罩、首次访问预加载器和共享元素变形：过渡范式，以及布局集成。
• 触控、视口变化和设备预算：设备与输入。
• Tauri、Electron 或 Wails 桌面外壳：桌面 WebView。
• 完成工作前：验证。

在此仓库中一并安装 GSAP 官方技能。仅在需要时加载 gsap-core 获取 API 详情，以及加载 gsap-frameworks 了解组件设置。

规则

• 成功初始化时保留不可见的引导动画；失败时恢复当前传入的所有者。添加隐藏规则前，先遵循初始化约定。
• GSAP 只在浏览器中运行。onMount 和 $effect 不会在服务器上运行；模块级代码需要使用 browser 守卫。使用 gsap.context 将选择器限定在 bind:this 根节点内。在 effect 的清理函数或 onMount 的返回函数中清理每个补间、触发器、分割对象和监听器。
• 使用常规 CSS 和稳定的包装元素预留最终布局；让离场内容与入场内容重叠，不要让布局空间翻倍。
• 先挂载，再设置初始值，然后绘制。成功初始化时，入场动画开始前绝不会闪现已经到位的内容。服务器 HTML 会在 hydration 前绘制，因此只能在由内联脚本设置根属性时隐藏入场目标，并且仅限初始阶段；同时提供无 JavaScript 的路径。
• 在稳定状态下清除临时样式。只在动画期间使用 will-change；这会覆盖 gsap-performance 的静态提示。
• 使用能力查询区分设备档位。触摸状态要能释放；控件不能依赖悬停才能使用。
• 在离场动画期间及结束状态中，让离场页面保持挂载和可见。使用 beforeNavigate 暂停导航，并在结束回调中重新发起导航；或者从 onNavigate 返回离场动画的 promise。URL 会在 onNavigate 运行前改变，因此只有第一种方式能在离场动画期间保持 URL 不变。
• 导航到带有新参数的同一路由时，页面会就地更新。通过 afterNavigate 针对已处于稳定状态的 DOM 再次运行生命周期，或使用 {#key} 重新挂载。
• 返回和前进会通过相同的钩子以 popstate 到达。绝不要为它们运行离场动画。在滚动位置恢复后，为它们提供仅运行入场动画的路径。
• 除非应在每次导航时都重新构建 GSAP 设置，否则不要在构建 GSAP 设置的 effect 中读取 page、data 或 navigating。
• 每个元素只能由一个引擎控制。对 GSAP 也会动画处理的节点使用 out: 指令会导致冲突，而且该块会一直留在 DOM 中，直到指令执行完毕。
• 保留原生链接行为、data-sveltekit-* 选项、焦点、滚动，以及无 JavaScript 时的可读性。
• 减少动态效果时也要到达相同的稳定状态，并仍触发每个完成回调。Svelte 过渡会忽略 CSS 的减少动态效果规则；应通过 prefersReducedMotion 将其设为零。
• 明确处理中断和快速点击的行为；完成时必须恰好释放一次导航等待。
• 条件允许时，在真实浏览器中验证。涉及路由、配置、依赖或发布的变更应使用生产构建验证。