@nerdev/skillset 0.2.1

package/skills/ui/gsap-nuxt/references/navigation.md

@@ -0,0 +1,145 @@
+# Navigation
+
+Read this when changing how pages live and die: keys, keepalive, Nuxt app hooks, scroll, focus, links, history, View Transitions, and SSR.
+
+## Page lifecycle
+
+**mount → initial state → intro → settled → outro → end state → unmount**
+
+On a Nuxt route change with GSAP in the transition hooks:
+
+1. **Navigation.** A `<NuxtLink>` click or `navigateTo`. `page:loading:start`, route middleware, guards, the page chunk (usually prefetched), `beforeResolve`, commit. The old page is untouched.
+2. **Incoming setup.** `<NuxtPage>` renders the new page under Suspense: `page:start`, then its setup and data run off-screen. The old page stays visible and interactive.
+3. **Outro.** Suspense resolves: `page:finish`, then `page:loading:end`. Vue unmounts the old page component and hands its root to `onBeforeLeave` and `onLeave`. Under `out-in` the new root waits; without `mode` it is inserted now.
+4. **End state.** The outro's `done`. Vue removes the old root; `onAfterLeave` and `page:transition:finish` fire; Nuxt scrolls one frame later.
+5. **Initial state and intro.** `onBeforeEnter` before insertion, `onEnter` after, the page's `onMounted` in the same flush. Write start values, then play.
+6. **Settled.** The intro's `done`, then `onAfterEnter`. Clear temporary styles. CSS owns the page.
+
+One navigation at a time is Vue Router's job: a new navigation cancels a pending one, and Nuxt remounts the Suspense. Your job is that every hook call ends in `done` and every timeline can be killed.
+
+## When a page is reused versus remounted
+
+`<NuxtPage>` keys the page on the `pageKey` prop, else `definePageMeta({ key })`, else the matched route path with params filled in. So:
+
+- `/posts/1` to `/posts/2` changes the key: remount, full transition, `page:start` and `page:finish`.
+- Query or hash changes keep the key: the component is reused, no transition, no `page:start`. `page:loading:start` and `page:loading:end` still fire. Animate in place from `onBeforeRouteUpdate` or a `watch` on the route.
+- `key: route => route.fullPath` remounts on query changes too. Use it only when a query means a different screen.
+- `key: 'static'` or `<NuxtPage page-key="static">` never remounts across params. Param changes become in-page updates and the hooks never run.
+- Hash-only links are same-page. Leave them native; Nuxt scrolls to the target with the router's `scrollBehaviorType`.
+
+Nuxt's own test for "this navigation changes the page" is the same: the key differs or the matched components differ. View transitions and scroll use it.
+
+## Route lifetime under keepalive
+
+`definePageMeta({ keepalive: true })`, `<NuxtPage keepalive>`, or `app.keepalive` wraps pages in `<KeepAlive>`. A page is then deactivated instead of unmounted and reactivated instead of remounted. DOM and state survive; the lifecycle does not.
+
+- **Deactivate is unmount.** `onDeactivated` fires when the leave starts. Revert the page's context there. The root still plays `onLeave`, then moves to KeepAlive's off-document storage.
+- **Stored pages measure zero.** Do not create or refresh ScrollTrigger, Flip, or split instances while deactivated.
+- **Activate is mount.** `onActivated` fires after the root is inserted, and also once after `onMounted` on first mount. Setup runs again on DOM that holds settled or half-reverted values. Write initial state explicitly with `set` or `fromTo`; a `from` tween that trusts a fresh node is wrong. `onMounted` does not run again.
+- **The hooks run the same.** `onBeforeEnter` and `onEnter` fire on reactivation with the stored root as `el`; `onLeave` fires on deactivation.
+- **Cached pages leak.** Scope page-level CSS variables, `overflow` locks, and `will-change` to the page root, or undo them in `onDeactivated`.
+- `include` and `exclude` match component names. Under `future.compatibilityVersion: 5` page component names are normalized to route names.
+
+Without keepalive the page unmounts at leave start. Design for the keepalive case anyway; it costs nothing when unmount happens.
+
+## Nuxt app hooks
+
+Register with `useNuxtApp().hook(name, fn)` in a plugin, or `useRuntimeHook` (3.14+) in a component so it unregisters with the scope. In navigation order:
+
+- `page:loading:start`: in `router.beforeEach`, before middleware. Also when the `pageKey` prop changes. Fires for query-only changes and for navigations that later fail.
+- `page:start`: the incoming page's Suspense went pending. Its setup and data are running; the old page is on screen.
+- `page:finish`: that Suspense resolved. This is when the leave starts, not the end of the transition.
+- `page:loading:end`: after `page:finish`, or on navigation failure or router error. Pair with `page:loading:start` for a global navigating state, lock, or cover.
+- `page:transition:finish`: the outgoing page's `onAfterLeave`. Under `out-in` the new root has just been inserted and its `onEnter` has not run yet.
+- `page:view-transition:start`: only with `experimental.viewTransition`; passes the `ViewTransition`.
+- `app:suspense:resolve`: the root Suspense resolved on the client, the first-load counterpart of `page:finish`. `app:mounted` fires earlier, when `mount()` returns.
+- `link:prefetch`: a `<NuxtLink>` is about to prefetch.
+
+Use these for app-level state: cover, lock, loading indicator, analytics, announcing. Use the transition hooks for anything that touches the page's elements. For work after the intro, `onAfterEnter` is the only hook that fires then.
+
+## Scroll and focus
+
+Nuxt's default `scrollBehavior` (override it in `app/router.options.ts`) waits for `page:loading:end`, then for the outgoing leave to finish, then one animation frame, then scrolls: `savedPosition` on back and forward, the hash target if any, otherwise top. `definePageMeta({ scrollToTop: false })`, or a function of `to` and `from`, disables it per route. Same-path hash changes scroll at once.
+
+So the window moves after the outro and around the first frame of the intro. Keep initial state independent of scroll position (transforms, `autoAlpha`), create ScrollTrigger instances after that scroll (`onAfterEnter`, or `page:transition:finish` plus a frame), and refresh in `onAfterEnter`. Do not add a second scroll reset.
+
+Override `scrollBehavior` only to change the position logic. Keep the wait: returning a promise that resolves after `page:transition:finish` is Vue Router's documented way to delay scroll for a transition.
+
+Focus: in `onAfterEnter`, move focus to the page root or its heading only if focus is on `body`. Give the target `tabindex="-1"` and a visible focus style. `autoAlpha: 0` is `visibility: hidden` and refuses focus, so focus at settled, not at insert. Keep `<NuxtRouteAnnouncer>` for the announcement.
+
+## Outro before navigation
+
+Vue keeps the old page through `onLeave`, so an outro that merely plays before the old page disappears needs no interception. But Vue Router commits the URL before `onLeave` runs: by the time the hooks see the old root, the address bar already shows the destination and the incoming page has loaded. If the outro must play with the URL unchanged, which is what "outro before navigation" usually means, the hooks cannot do it; the outro has to run in a global route middleware that awaits it, and `onLeave` then only hands `done` over for an element that is already at its end state. Do not port a Next.js transition-aware link that prevents default, animates, then pushes; here it doubles the outro or races the hooks.
+
+The ways to move the outro earlier:
+
+- **The outro must cover the load.** By default the leave waits for the incoming page. To start the outro at click time, use `<NuxtLink custom v-slot="{ href, navigate }">`, start the outro and call `navigate()` together, and let `onLeave` call `done` at once when the outro has already reached end state, or attach `done` to the running timeline. Make the page non-interactive from the click. Leave modified clicks, external URLs, `target`, and `download` to the native anchor.
+- **Nothing may load and the URL must wait until the outro ends.** A global route middleware `await`s the outro on the client (`import.meta.client && !useNuxtApp().isHydrating`) and then returns. Route middleware runs after `page:loading:start` and before guards, chunk loading, the URL commit, and the incoming setup. Never await it on history navigation. The lock cannot live in this middleware: returning `false` for a second click while the first is awaiting makes Vue Router cancel the first as well, since the pending navigation is now the second, and both are lost. Put the lock in front of the router, in the link component, so the second click never becomes a navigation.
+- **A leave must be refused.** `onBeforeRouteLeave` returning `false` cancels the navigation before anything moves. Use it for unsaved work, not for animation locks; returning `false` on back or forward also rewrites the URL back.
+
+Shared elements need no interception. `Flip.getState` in `onBeforeLeave` (the old page is laid out and the new page is not yet inserted in either mode), hand the state through the transition module, `Flip.from(state, { targets })` in `onEnter`. Under no `mode` the old element is still in the DOM, so pass `targets` explicitly.
+
+## Back and forward
+
+History navigation runs the same middleware, hooks, and transition as a click, and Vue Router does not tell a guard how a navigation started. What works:
+
+- `useRouter().options.history.listen((to, from, info) => ...)` fires for `popstate` navigations only, before the router runs, with `info.direction` of `back`, `forward`, or empty. Record the destination it reports and let the hooks compare it with the route they are entering; do not clear a boolean on `page:loading:end`, which fires before `onLeave` and `onEnter` and so wipes the flag before the hooks read it. Vue Router marks this API alpha; check `node_modules/vue-router` after upgrades.
+- A `popstate` listener on `window` fires in the same dispatch, before any guard. `event.hasUAVisualTransition` means the browser already animated a swipe gesture; skip the intro then, as Nuxt's own view-transition plugin does.
+- `scrollBehavior` receives `savedPosition` only on history navigation, but that is after commit and after the leave.
+
+Give history navigation a quieter path: a short outro or an immediate `done`, then intro-only with no travel, since the user is returning. The hooks still fire; do not skip `done`.
+
+The bfcache does not apply to same-document navigation. A full reload of a Nuxt page is a fresh hydration and takes the first-load path.
+
+## View Transitions
+
+`experimental.viewTransition: true` (or `'always'`, or `{ enabled, types }`) calls `document.startViewTransition` in `router.beforeResolve` for navigations that change the page, runs the route swap and Suspense inside its update callback, and finishes it on `page:finish`. `true` skips it under `prefers-reduced-motion`; `'always'` does not. Per page: `definePageMeta({ viewTransition })` with `enabled`, `types`, `toTypes`, and `fromTypes` (4.4+; functions of `to` and `from` work here, not in `nuxt.config`). Style with `::view-transition-*` and `html:active-view-transition-type(...)`. `page:view-transition:start` hands you the `ViewTransition` to read or add types. A `popstate` with `hasUAVisualTransition` skips it.
+
+Vue's `<Transition>` has no View Transitions mode of its own; this plugin is the integration.
+
+Rules for mixing:
+
+- Never run the `pageTransition` hooks and a view transition on the same navigation. The DOM is frozen while the browser captures, and Suspense resolves while the old page is still leaving, so the new snapshot is wrong or blank. Follow Nuxt's recipe: a global middleware sets `to.meta.pageTransition = false` and `to.meta.layoutTransition = false` when `document.startViewTransition` exists, and your GSAP path lives in the page's `onMounted`.
+- One engine per element per transition. Name only elements that morph, set the name only for that navigation, and clear it.
+- GSAP intros for elements the transition touched start after `transition.finished`; take the `ViewTransition` from `page:view-transition:start`. Elements outside it can start at `onMounted`.
+- Data fetched in page setup runs inside the frozen update; Nuxt's docs list this as a known issue. Prefer prefetched or cached data on routes that use it.
+- Add `::view-transition { pointer-events: none }`.
+- Reduced motion covers both: `true` already skips the browser side; take the GSAP reduced path.
+
+Use view transitions for a shared-element morph or a whole-page slide keyed by types. Use the GSAP hooks for everything sequenced, interruptible, or scroll-linked. Pick per route, not per element.
+
+## SSR and first paint
+
+GSAP runs only in the browser.
+
+- Register GSAP and plugins in a `.client.ts` plugin or the `useGSAP` composable from `gsap-frameworks`; guard module-level side effects with `import.meta.client`.
+- `onMounted`, `onActivated`, and the transition hooks never run on the server. `<script setup>` top level and `watchEffect` do.
+- `<ClientOnly>` renders its slot only after mount and its `fallback` on the server; the slot is not in the server HTML at all. Use it for a canvas or a plugin-driven widget that cannot render as HTML, not to hide a page.
+- With `ssr: false` the client renders everything and first-paint hiding is unnecessary.
+
+Hydration happens after the server HTML has painted, so a first-load intro needs initial state before first paint, applied by CSS under a mark that only JavaScript sets:
+
+- Add an inline script through `app.head.script` in `nuxt.config` with `innerHTML` and `tagPosition: 'head'`. It runs before the body parses. It sets a root mark such as `data-motion="js"` on `<html>`, and skips the mark under `prefers-reduced-motion` so that path paints settled. Do not put a `data-phase` on `<html>`: the page root owns that attribute, and a second one on the document root reads to CSS, tests, and observers as another page changing phase.
+- Vue hydrates `#__nuxt`, not `<html>`, so attributes set there cause no hydration mismatch.
+- One CSS rule hides intro targets only under the mark and only while the page root is in its initial phase, such as `html[data-motion="js"] [data-page][data-phase="initial"] [data-intro] { visibility: hidden }`. The server renders the page root with `data-phase="initial"`, so the rule applies from first paint and releases when the controller advances the phase. Use `visibility`, not `display`, so layout is measured with the elements in place.
+- The first `onMounted` registers recovery, writes start values, attaches completion handlers, then advances the phase and plays. A setup exception rolls back partial changes before revealing content.
+- Keep the early failsafe active until preparation succeeds and the intro can run, not merely until a controller registers. Register rollback before setup, preserve the original deadline, and take the settled path after recovery. Follow [Initialization and recovery](initialization.md).
+- Content stays readable without JavaScript: no mark, no rule.
+- `onPrehydrate` inlines a callback before `</body>`, after the content has parsed and possibly painted. It is for DOM fixes right before hydration, not for the pre-paint mark.
+
+Route navigations do not go through this: `onBeforeEnter` runs before the incoming root is inserted.
+
+## Cases to design for
+
+- Navigation requested mid-intro.
+- Two destinations clicked before the first resolves.
+- Back or forward, including a swipe the browser already animated.
+- A keepalive page shown again with settled DOM.
+- A change of only query or hash.
+- A slow incoming page: the old page stays on screen. Decide what the user sees for two seconds.
+- A layout change, where the page transition does not run.
+- A leave that reverts a pinned ScrollTrigger.
+- Reload on a slow network: no settled flash, then a clean intro.
+- Development hot reload, which re-runs setup on a live page.
+
+Each case must end on one visible, interactive page with stable layout, no stale inline styles, and every `done` called.

package/skills/ui/gsap-nuxt/references/page-transitions.md

@@ -0,0 +1,107 @@
+# Page transitions
+
+Read this when changing route-level motion: the hooks, `done`, modes, what dies when the leave starts, first load, layouts, direction, and interruptions.
+
+## What Nuxt gives you
+
+`<NuxtPage>` renders `<RouterView>` → `<Transition>` → `<KeepAlive>` → `<Suspense>` → page. The `<Transition>` and `<KeepAlive>` layers exist only when configured. Nothing is on by default: `app.pageTransition`, `app.layoutTransition`, and `app.keepalive` all default to `false`.
+
+`pageTransition` and `layoutTransition` take Vue `TransitionProps`: `name`, `mode`, `css`, `appear`, `duration`, the class props, and the JavaScript hooks. Three places set them, merged key by key with the first defined value winning:
+
+1. `<NuxtPage :transition="...">` in `app.vue`. Keys set here cannot be overridden by a page.
+2. `definePageMeta({ pageTransition })` in the page. It is a compiler macro: the object is hoisted out of the component, so hook functions must be imported or module-level, never closures over refs, template refs, or component state.
+3. `app.pageTransition` in `nuxt.config`. JSON-serializable only, so no hooks; use it for `name`, `mode`, and `css` defaults.
+
+Nuxt appends its own `onAfterLeave`, which fires the `page:transition:finish` app hook, alongside yours.
+
+`pageTransition: false` in `definePageMeta` (or in `nuxt.config` with no prop) removes the `<Transition>` for that route: the old page unmounts at once and nothing leaves. Use it for routes that must swap with no motion.
+
+Pages and layouts must render a single root element. A fragment root cannot be animated; Nuxt warns in development and the transition does not run. A layout's root cannot be its `<slot />`.
+
+## GSAP owns the hooks
+
+Set `css: false` and implement the JavaScript hooks. With `css: false`, Vue adds no `*-enter-*` or `*-leave-*` classes and does not wait for `transitionend`; the transition ends when you call `done`. Without it, a leftover `.page-enter-active` rule runs a CSS transition on the element GSAP is tweening.
+
+Declare the `done` parameter. Vue calls a hook declared with only `el` synchronously and finishes the transition at once.
+
+The hooks and the phases they own:
+
+- `onBeforeEnter(el)`. The incoming root exists with its children but is not in the document: selectors work, measurement does not. Write initial values that need no layout, such as `autoAlpha` and transforms.
+- `onEnter(el, done)`. The root is in the document, in the same task as insertion and before paint. Measure, finish initial state, then advance the phase to `intro` and build the intro from a microtask, not in the same task as the `initial` write, or `initial` is never observable. Call `done` on completion.
+- `onAfterEnter(el)`. Settled. Clear temporary styles with `clearProps`, refresh ScrollTrigger, move focus. Do not revert the enter context here: a revert restores the inline values from before the tween, which are the `autoAlpha: 0` and transform written in `onBeforeEnter`, and the settled page vanishes.
+- `onEnterCancelled(el)`. A new navigation arrived mid-intro. Kill the intro; the element is about to leave.
+- `onBeforeLeave(el)` and `onLeave(el, done)`. The outgoing root is still in the document with its layout. Build the outro from current values, call `done` on completion.
+- `onAfterLeave(el)`. `el` has been removed. End state and cleanup of anything the outro owned.
+- `onLeaveCancelled` fires only for `v-show`. Page roots never get it.
+
+Hooks receive `el` and nothing else. By `onLeave` the page component is gone, so there are no template refs, no component state, and `useRoute()` already means the new page. Mark targets with data attributes and query them inside `el`, or run the builder inside `gsap.context(fn, el)`.
+
+`done` is a contract:
+
+- Call it once per hook call. Extra calls are ignored.
+- Call it from the timeline's `onComplete` and from `onInterrupt`, since a killed timeline never completes. Put that in one helper every builder uses.
+- Call it synchronously under reduced motion after writing end values.
+- An enter that never calls `done` never fires `onAfterEnter`, and the next leave cancels it.
+- A leave that never calls `done` keeps the old root in the DOM forever, never fires `page:transition:finish`, holds Nuxt's scroll, and under `out-in` never inserts the new page. If something outside the hook can kill the timeline, keep the `done` call outside the timeline too.
+
+Race the leave's `done` against a short timeout. GSAP's ticker and `requestAnimationFrame` stop in a hidden tab, and a navigation started from a background tab must still finish.
+
+## The component dies when the leave starts
+
+When Vue removes a page whose root has a leave transition, it unmounts the component first and keeps only the root element: `onBeforeUnmount` runs synchronously, the component's effect scope stops, the element is handed to `onLeave`, and `onUnmounted` runs in the same flush. All of that happens before the outro plays a frame. Under keepalive, `onDeactivated` fires at that moment instead.
+
+What this means:
+
+- A `gsap.context` the page reverts on unmount kills the page's tweens and triggers, and restores their inline styles, as the outro begins. Let it. It must leave the DOM readable, because that is the picture the outro starts from.
+- Build the outro in `onLeave` inside a context the transition module owns, scoped to `el`. Revert that context in `onAfterLeave`.
+- The outgoing page loses its reactivity, watchers, and listeners at leave start. Nothing in it updates during the outro. Do not plan on it responding.
+- A ScrollTrigger reverted at leave start removes its pin spacer and restores the pinned element, so a page leaving mid-pin changes height as the outro begins. Hold the stable wrapper's height through the outro, or design the outro so the collapse is covered.
+- Template refs are null in `onLeave`. `el` is the only handle.
+
+## Modes and who is on screen
+
+`mode` decides overlap. Nuxt's examples use `out-in`; Vue's default is simultaneous.
+
+- **`out-in`.** The outro plays alone. When `done` is called, Vue removes the old root, inserts the new one, and runs `onBeforeEnter` and `onEnter`. One page owns the geometry at a time.
+- **No `mode`.** The old root starts leaving and the new root is inserted in the same tick. Both are in the document through the outro. Give the container the geometry: reserve its size, or overlap the children so only the wrapper takes space in flow.
+- **`in-out`** behaves like no `mode` under `<NuxtPage>`. Do not use it.
+
+In both modes the outro cannot start before the incoming page is ready. `<NuxtPage>` renders the incoming page under `<Suspense>`: its setup, top-level `await`, `useAsyncData`, and `useFetch` run off-screen while the outgoing page stays visible and interactive. The leave begins when that resolves. So the outro never overlaps loading, the user never sees a half-loaded page, and a slow page shows only the old page and the loading indicator until it is ready. If the design wants the outro to cover the wait, see [Outro before navigation](navigation.md#outro-before-navigation).
+
+Under `out-in` the incoming page's `onMounted` runs after the old root is gone and the new one is inserted; under no `mode` it runs at leave start. The order between that `onMounted` and `onEnter` differs between modes. Do not depend on it. Page-level phases belong to the hooks; component-level setup belongs to `onMounted`.
+
+## First load and `appear`
+
+Do not use `appear` on a server-rendered page. Vue's SSR compiler wraps the child of `<Transition appear>` in `<template>`, so the server HTML ships the page inert and invisible until hydration replaces it. No JavaScript, no page. On hydration, `appear` also runs the enter hooks after the server HTML has painted, so it cannot hide the settled state either.
+
+The first load is its own lifecycle:
+
+- Mount is hydration. The page's `onMounted` runs after hydration, which is after first paint.
+- Initial state must be written before first paint by an inline head script plus a CSS rule, not by GSAP. See [SSR and first paint](navigation.md#ssr-and-first-paint).
+- The intro starts in the page's `onMounted` (or on `app:suspense:resolve` for a shell-level intro) and releases the pre-paint rule as its first act.
+- Without `appear`, the hooks do not run on first load, so first load and navigation are two entry points to the same intro builder.
+
+With `ssr: false` nothing paints before Vue renders, so `onMounted` is early enough, no pre-paint rule is needed, and `appear` is safe.
+
+## Layouts
+
+`layoutTransition` wraps the layout's root the same way. When a navigation changes layouts, the page transition does not run; the layout transition does, and the layout's chrome leaves and enters with the page. Give layout changes their own hooks or disable one of the two. Do not make `<NuxtLayout>` the root element of a page.
+
+Chrome that must never move on navigation lives in `app.vue` outside `<NuxtLayout>`, or in one layout every route shares.
+
+## Direction and dynamic transitions
+
+Route middleware runs before the transition starts and may rewrite `to.meta.pageTransition`; check it is not `false` first. Nuxt documents changing `name` this way. The hooks can read the same object through `useRouter().currentRoute.value.meta.pageTransition`, because the route has already changed when `onLeave` fires. Keep `name` in sync even with `css: false`; it lets a CSS fallback share the vocabulary.
+
+Alternatives: a `useState` the middleware writes and the hooks read, or a computed `:transition` on `<NuxtPage>`.
+
+Direction from the route pair is the honest signal. History direction is a separate problem; see [Back and forward](navigation.md#back-and-forward).
+
+## Interruptions
+
+Nuxt remounts the `<Suspense>` when a navigation starts while another is still pending, and Vue cancels a running enter when its element must leave. Handle:
+
+- `onEnterCancelled`: kill the intro. The same element then gets `onBeforeLeave` and `onLeave`; start the outro from current values.
+- A leave still running when a third route arrives: Vue removes the element through the pending `done` guard, so your `done` may run late or twice. Both are harmless. Kill the timeline in `onAfterLeave`.
+- A killed timeline never resolves its promise. Use the `done` helper for every `await`.
+- Two clicks before the first navigation is confirmed: Vue Router cancels the first as a navigation failure and Nuxt fires `page:loading:end` for it. No hooks run for the cancelled one.

package/skills/ui/gsap-nuxt/references/verification.md

@@ -0,0 +1,42 @@
+# Verification
+
+Check in proportion to what changed. Do not turn a focused animation task into a full audit.
+
+## Always
+
+- Run the repo's type, lint, format, and test commands where they exist, including `nuxt typecheck` when the project uses it.
+- Confirm settled content is visible, interactive, and free of leftover GSAP inline styles.
+- Confirm timelines, triggers, listeners, and plugin DOM changes are cleaned up, on unmount and on deactivate.
+- Confirm every transition hook calls `done` on completion, on interruption, and under reduced motion.
+- On server-rendered projects, confirm the page is readable with JavaScript disabled and with the pre-paint mark set but the client bundle blocked.
+- Test reduced motion when the change has a reduced-motion branch.
+
+## Initially hidden content
+
+Run the [failure verification matrix](initialization.md#failure-verification) when adding or changing hiding, preparation, or recovery. It covers disabled JavaScript, a blocked bundle after the marker, throws before/after styles and splits, stalled fonts/media, late initialization, no-flash success, reduced motion, and interruption/repeated setup. Assert text and native links, not opacity alone. Include shell/footer and intentionally hidden content.
+
+Use this framework's [integration rules](motion-system.md#initialization-and-recovery) for rendering and navigation expectations. Measure document-load LCP separately from transitions when first-load behavior changes; report measured results and untested paths.
+
+## Runtime changes
+
+Check the changed lifecycle in a real browser when practical:
+
+- Initial state is applied before reveal. For the first load, throttle the network and reload; no settled content flashes.
+- Intro ends in one settled state.
+- Outro keeps the node in the DOM until `done`, and the node is gone right after.
+- Rapid or interrupted input ends in one coherent state.
+- Layout boxes do not jump, including at leave start when the page's context reverts.
+
+For route navigation, test the paths the change affects: an ordinary `<NuxtLink>`, back and forward, a second click before the first navigation resolves, a query-only change (no transition should run), a route with `pageTransition: false`, and a layout change. Confirm URL, visible page, focus, history, and scroll agree, and that exactly one page root remains in the DOM after each transition.
+
+With keepalive, also navigate away and back. The returning page must re-run initial state and intro on its preserved DOM with no doubled tweens, and scroll triggers must measure correctly after reactivation.
+
+With `experimental.viewTransition`, confirm the Vue transition is disabled on those navigations, no element is animated by both engines, names are cleared afterward, and clicks land during a running transition.
+
+For conditional components, test show, hide, and one interruption. Confirm removal happens after the outro, and that a `v-show` re-show during an outro reverses or restarts as intended.
+
+## Builds and wider checks
+
+Run `nuxt build` and check the output with `nuxt preview` for changes to pages, layouts, `nuxt.config`, router options, middleware, dependencies, or client and server boundaries. Run wider browser, accessibility, responsive, and performance checks only when the change touches them or the user asks for a full audit.
+
+Report which checks ran and which could not. Do not claim runtime behavior was verified when only static review was possible.

package/skills/ui/gsap-performance/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: gsap-performance
+description: Official GSAP skill for performance — prefer transforms, avoid layout thrashing, will-change, batching. Use when optimizing GSAP animations, reducing jank, or when the user asks about animation performance, FPS, or smooth 60fps.
+license: MIT
+---
+
+# GSAP Performance
+
+## When to Use This Skill
+
+Apply when optimizing GSAP animations for smooth 60fps, reducing layout/paint cost, or when the user asks about performance, jank, or best practices for fast animations.
+
+**Related skills:** Build animations with **gsap-core** (transforms, autoAlpha) and **gsap-timeline**; for ScrollTrigger performance see **gsap-scrolltrigger**.
+
+## Prefer Transform and Opacity
+
+Animating **transform** (`x`, `y`, `scaleX`, `scaleY`, `rotation`, `rotationX`, `rotationY`, `skewX`, `skewY`) and **opacity** keeps work on the compositor and avoids layout and most paint. Avoid animating layout-heavy properties when a transform can achieve the same effect.
+
+- ✅ Prefer: **x**, **y**, **scale**, **rotation**, **opacity**.
+- ❌ Avoid when possible: **width**, **height**, **top**, **left**, **margin**, **padding** (they trigger layout and can cause jank).
+
+GSAP’s **x** and **y** use transforms (translate) by default; use them instead of **left**/**top** for movement.
+
+## will-change
+
+Use **will-change** in CSS on elements that will animate. It hints the browser to promote the layer.
+
+```css
+will-change: transform;
+```
+
+## Batch Reads and Writes
+
+GSAP batches updates internally. When mixing GSAP with direct DOM reads/writes or layout-dependent code, avoid interleaving reads and writes in a way that causes repeated layout thrashing. Prefer doing all reads first, then all writes (or let GSAP handle the writes in one go).
+
+## Many Elements (Stagger, Lists)
+
+- Use **stagger** instead of many separate tweens with manual delays when the animation is the same; it’s more efficient.
+- For long lists, consider **virtualization** or animating only visible items; avoid creating hundreds of simultaneous tweens if it causes jank.
+- Reuse timelines where possible; avoid creating new timelines every frame.
+
+## Frequently updated properties (e.g. mouse followers)
+
+Prefer **gsap.quickTo()** for properties that are updated often (e.g. mouse-follower x/y). It reuses a single tween instead of creating new tweens on each update. 
+
+```javascript
+let xTo = gsap.quickTo("#id", "x", { duration: 0.4, ease: "power3" }),
+    yTo = gsap.quickTo("#id", "y", { duration: 0.4, ease: "power3" });
+
+document.querySelector("#container").addEventListener("mousemove", (e) => {
+  xTo(e.pageX);
+  yTo(e.pageY);
+});
+```
+
+## ScrollTrigger and Performance
+
+- **pin: true** promotes the pinned element; pin only what’s needed.
+- **scrub** with a small value (e.g. `scrub: 1`) can reduce work during scroll; test on low-end devices.
+- Call **ScrollTrigger.refresh()** only when layout actually changes (e.g. after content load), not on every resize; debounce when possible.
+
+## Reduce Simultaneous Work
+
+- Pause or kill off-screen or inactive animations when they’re not visible (e.g. when the user navigates away).
+- Avoid animating huge numbers of properties on many elements at once; simplify or sequence if needed.
+
+## Best practices
+
+- ✅ Animate **transform** and **opacity**; use **will-change** in CSS only on elements that animate.
+- ✅ Use **stagger** instead of many separate tweens with manual delays when the animation is the same.
+- ✅ Use **gsap.quickTo()** for frequently updated properties (e.g. mouse followers).
+- ✅ Clean up or kill off-screen animations; call **ScrollTrigger.refresh()** when layout changes, debounced when possible.
+
+## Do Not
+
+- ❌ Animate **width**/ **height**/ **top**/ **left** for movement when **x**/ **y**/ **scale** can achieve the same look.
+- ❌ Set **will-change** or **force3D** on every element “just in case”; use for elements that are actually animating.
+- ❌ Create hundreds of overlapping tweens or ScrollTriggers without testing on low-end devices.
+- ❌ Ignore cleanup; stray tweens and ScrollTriggers keep running and can hurt performance and correctness.