@nerdev/skillset 0.2.1

package/skills/ui/gsap-tanstack-router/references/route-lifetime.md

@@ -0,0 +1,66 @@
+# Route lifetime
+
+Read this to know when a route component mounts, updates in place, or unmounts, how the React lifecycle fits GSAP under this router, and what TanStack Start's server rendering changes.
+
+## Reuse versus remount
+
+The router renders matches as a chain: root, layouts, page, each in its own memoized `Match`. A navigation swaps only the levels whose route changed.
+
+- Same route, new params or search: the component is reused. Its loader reruns when `loaderDeps` or `staleTime` say so; `useParams`, `useSearch`, and `useLoaderData` update in the commit. No mount, no unmount, no `useGSAP` with an empty dependency list.
+- Different route under the same layouts: the page unmounts and the new one mounts. The layouts stay, with their state, timelines, and listeners.
+- Layout routes (`route.tsx`, `_pathless` layouts, the root) persist for their subtree and unmount only when the tree leaves them.
+- `router.invalidate` reruns loaders and updates props. Nothing remounts.
+- `remountDeps({ routeId, params, search, loaderDeps })` on a route, or `defaultRemountDeps` on the router, forces a remount whenever its JSON-serializable return value changes. `({ params }) => params` is the documented way to remount per param.
+
+So a page intro tied to a mount plays once per mount, not once per visit. Two fixes:
+
+- **Rerun the lifecycle on the reused node, the default for GSAP.** Give `useGSAP` the params, or the loader data, as dependencies with `revertOnUpdate`. The DOM already holds settled values and the previous timeline may still be running, so kill it first and write initial state with `set` or `fromTo`, never a `from` tween that trusts a fresh node. Skip when only search params changed unless they mean a different screen.
+- **`remountDeps`.** Every param change destroys and recreates the component, so the mount path replays. It discards component state and inner scroll positions, which is what the docs offer for that case.
+
+Do not wrap `<Outlet />` in an element keyed on `useLocation().pathname`. That location moves when loading starts, before the new matches commit, so the wrapper remounts the old page once while it waits and again when the new page arrives. If a keyed wrapper is unavoidable, key it on the leaf of the presented matches, and expect it to remount every nested layout inside it.
+
+## Layouts and the controller
+
+The root route's component mounts once per document and outlives every client-side navigation. That makes it the home of the route transition controller: one ref'd route container around `<Outlet />`, the blocker, the history subscription, the phase, and the cover. Nested layout routes persist for their subtree and are the place for section-level chrome motion.
+
+`Wrap` and `InnerWrap` on the router are for providers only; the docs forbid DOM-rendering components there. Keep the container in the root component.
+
+Pages register intro and outro builders with the controller through context and unregister in their effect cleanup. The controller runs the outgoing page's outro from `shouldBlockFn` and the incoming page's intro when it reports ready. Ready is reported through that context only after required preparation, initial writes, and timeline handlers are ready. It drops the cover and releases the matching lock. If readiness times out, recover that incoming owner through [Initialization and recovery](initialization.md) before releasing its cover. A page that registers nothing gets the container-level default.
+
+A `useBlocker` in a page sees only navigations away from that page and unregisters when it unmounts. One blocker in the root is simpler than one per page.
+
+## React lifecycle for GSAP
+
+- `useGSAP` runs in a layout effect after the tree commits, before `onRendered` and before scroll restoration. `gsap-react` covers `scope`, `contextSafe`, `revertOnUpdate`, and cleanup. Use it unchanged.
+- Route components render on the client inside `React.startTransition`. A component that suspends keeps the old tree on screen; the new tree mounts as a whole when it can. Layout effects, and so `useGSAP`, run in that single commit.
+- Never call another component's `contextSafe` function from inside a `useGSAP` callback. GSAP nests contexts: a context whose function runs while another context's callback is executing becomes a child of that outer context, and the outer context's next revert kills it. A page's setup must not synchronously trigger the root controller's builders. Hand off through a microtask, an effect, or an event.
+- Write setup so it is correct when it runs more than once on the same node. React development checks do this, and a reused route runs its keyed effect again on settled DOM. Async work started by the first run can still be in flight when the second starts, so anything a setup triggers outside its own context, such as the cover, must be safe to request twice. Use a ref guard only for work that should happen once per visit.
+- Store the phase in a ref and mirror it as a data attribute. Do not infer it from opacity, DOM presence, or timeline progress.
+- `onEnter`, `onStay`, and `onLeave` on a route run with the match during the load commit, before React renders it. They are for data and analytics, not for DOM work.
+
+## Conditional content
+
+React unmounts conditional content before an outro can play. Keep the node mounted with a presence controller: render while `visible || leaving`, play the outro, and clear `leaving` from the end callback. See [Conditional show and hide](motion-system.md#conditional-show-and-hide).
+
+A modal that is a child route unmounts when the URL leaves it. Close it by playing its outro and then navigating, with `router.history.back()` when it was pushed or `navigate` to the parent otherwise, and tell the root controller that navigation is an overlay close so it runs no page outro and no cover. Undo scroll locks, key listeners, and focus in the effect teardown, which also covers a back navigation you did not initiate. Route masking (`mask`) changes only the URL shown; the component lifetime follows the real route.
+
+## SSR and hydration with TanStack Start
+
+- The root route renders the document. Its `component`, or its `shellComponent` when the root itself has `ssr: false`, returns `html`, `head` with `<HeadContent />`, and `body` with the children and `<Scripts />` last. `HeadContent` belongs in `head`; `Scripts` belongs at the end of `body`. The client entry, optional, is `hydrateRoot(document, <StartClient />)`.
+- Server HTML paints before hydration, before any effect. If initial state must hide before first paint, render `<ScriptOnce>` from `@tanstack/react-router` as the first child of `body` with an inline script that marks `documentElement` as JavaScript-active, and a CSS rule that hides intro targets only under that mark and only while the root is in its initial phase. `ScriptOnce` renders the script on the server with a trailing `document.currentScript.remove()`, so it runs once during parsing and is gone before hydration, and it returns `null` on the client. Skip the mark under `prefers-reduced-motion` so the page paints settled. Add `suppressHydrationWarning` to `html`, since the server markup does not carry the attribute. Register recovery before setup; advance the phase only after start values and completion handlers are ready. Keep content readable without JavaScript and keep the swap cover separate from the first-paint rule.
+- 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).
+- Hydration is the first mount. `useGSAP` runs once React attaches, and `onRendered` fires once with nothing changed. No `onBeforeNavigate` or `onBeforeLoad` precedes it.
+- Do not write inline styles or move DOM before hydration. The pre-paint rule is CSS keyed on the root attribute, which is why it does not break hydration.
+- `ssr: false` or `ssr: 'data-only'` on a route skips server rendering of its component: the server renders the route's `pendingComponent` as a fallback and the client shows it for at least `pendingMinMs` before the real component mounts. That mount is the first lifecycle for the route; nothing settled was painted, so it needs no pre-paint rule. The setting inherits downward and can only become more restrictive. `defaultSsr` in `createStart` sets the default.
+- SPA mode (`spa.enabled`) prerenders only the root and the pending fallback; every route is a client mount. Prerendered routes hydrate like SSR routes.
+- `<ClientOnly fallback>` and `useHydrated` render browser-only content after hydration. Use them for content whose server markup would differ, not as a way to hide intro targets.
+- Deferred hydration (`<Hydrate when>`, experimental) keeps a boundary's server HTML on screen and hydrates it later. GSAP inside it starts only then. Treat it as a component that mounts late with its server HTML as the initial paint, and keep its targets out of the page's pre-paint rule.
+- `useGSAP` never runs on the server. Importing GSAP in a route file is harmless; calling it at module scope is not. Register plugins in one client-only module that route files import lazily or inside effects.
+
+## Deferred data and streaming
+
+- A loader returns unawaited promises alongside awaited data; the route renders when the awaited data resolves and the rest streams, on the server through the HTML stream and on the client after mount. `<Await promise fallback>` or React 19 `use()` suspends the nearest boundary until each resolves.
+- Treat each streamed region as a component with its own controller: explicit initial state on arrival, a short intro, settled, cleanup. It never reports page ready. Reserve its block size in the fallback so arrival moves nothing.
+- The page outro owns everything present at leave time. Query outro targets when the outro is built, not at setup, so content that streamed in after setup leaves with the page. Intros stay separate: the page intro reveals what mounted with it, the region intro reveals what arrived later.
+- Preloaded loader data lives in the router cache for `preloadStaleTime`; a navigation reuses it or joins the loader still in flight. Do not assume it survives a long outro plus an invalidation.
+- With an external cache such as TanStack Query the loader only primes the cache; the same region rules apply to whatever suspends in the component.

package/skills/ui/gsap-tanstack-router/references/tanstack-navigation.md

@@ -0,0 +1,156 @@
+# TanStack navigation
+
+Read this when changing route-level motion or navigation.
+
+## Router APIs
+
+Check the installed types before using these. Everything below comes from `@tanstack/react-router` unless noted, and describes the current 1.17x releases.
+
+- `useBlocker({ shouldBlockFn, withResolver, disabled, enableBeforeUnload })`, marked experimental in the docs. `shouldBlockFn({ current, next, action })` returns `boolean | Promise<boolean>`; `true` blocks. `current` and `next` carry `routeId`, `fullPath`, `pathname`, `params`, and `search`. `action` is `PUSH`, `REPLACE`, `BACK`, `FORWARD`, or `GO`. With `withResolver: true` the hook returns `status` (`blocked` or `idle`), `current`, `next`, `action`, `proceed`, and `reset`; without it, the function's own return value decides. `disabled` removes the blocker. `enableBeforeUnload` defaults to `true` and also raises the browser's unload dialog on reload and tab close; set it `false` for a motion-only blocker. The older `blockerFn` and `condition` forms are deprecated. The hook re-registers whenever `shouldBlockFn` changes identity, so keep it stable and read live state through a ref.
+- Blockers live in the history layer, one list for the whole router, run in order and awaited one at a time. For `PUSH` and `REPLACE` they run before the URL changes and before any loader starts. For back and forward the browser has already moved: the blocker runs from `popstate` with the new entry in the address bar, a block reverses the move with `history.go`, and an allow keeps it. `ignoreBlocker` on a Link or `navigate` skips every blocker.
+- `Link` props: `to`, `params`, `search`, `hash`, `state`, `replace`, `resetScroll`, `hashScrollIntoView`, `viewTransition`, `startTransition`, `ignoreBlocker`, `reloadDocument`, `preload` (`false`, `'intent'`, `'viewport'`, `'render'`), `preloadDelay` (50 ms default), `activeProps`, `inactiveProps`, `activeOptions`, `disabled`, `target`. An active link renders `data-status="active"` and `aria-current="page"`. The router's click handler runs after your `onClick` and skips navigation when the event is `defaultPrevented`, carries a modifier key, is not the primary button, targets anything but `_self`, or the link is `disabled`. An external `href` renders a plain anchor with no router handling. `createLink` builds a typed Link around your own component.
+- `useNavigate({ from })` returns `navigate(options)` taking `NavigateOptions`: `to`, `params`, `search`, `hash`, `state`, `replace`, `resetScroll`, `hashScrollIntoView`, `viewTransition`, `ignoreBlocker`, `reloadDocument`, `href`. It resolves after the destination has rendered, and never if a blocker cancels it, so do not await it for a navigation that may be blocked. `router.navigate` is the same outside components; `Route.useNavigate` presets `from`. `href` to another origin or `reloadDocument` performs a document navigation; blockers still run for it, with `next` equal to `current`.
+- `useRouterState({ select })`: `status` (`pending` or `idle`), `isLoading` (true while pending), `location`, `resolvedLocation`, `matches`. `isTransitioning` existed through router-core 1.171.1x and is gone from current releases; check the installed `RouterState`. Always select a slice.
+- `useLocation({ select })` follows `state.location`, which moves to the destination when loading starts while the old page is still on screen. `resolvedLocation` moves after the new page has rendered.
+- `useMatches`, `useMatch({ from, select })`, `useParams`, `useSearch`, `Route.useLoaderData`: the presented matches, updated in the commit that mounts the new page. `useMatchRoute()({ to, pending: true })` and `<MatchRoute pending>` say whether a destination is the one currently loading.
+- `router.subscribe(event, fn)` returns an unsubscribe. Events: `onBeforeNavigate`, `onBeforeLoad`, `onLoad`, `onBeforeRouteMount`, `onResolved`, `onRendered`, each with `fromLocation` (undefined on the first load), `toLocation`, `pathChanged`, `hrefChanged`, and `hashChanged`.
+- `router.history.subscribe(({ location, action }) => ...)` fires on every history change with `action.type` `PUSH`, `REPLACE`, `BACK`, `FORWARD`, or `GO`. `useCanGoBack()` reads the history index; `router.history.back()` goes back.
+- `location.state.__TSR_index` is the history index and `__TSR_key` the entry key; the router's own view-transition example derives direction from the index. Both are internal fields on a public type; prefer the history action.
+- Route options that shape timing: `pendingComponent`, `pendingMs` (default 1000), `pendingMinMs` (default 500), `staleTime` (default 0), `preloadStaleTime` (30 s), `loaderDeps`, `shouldReload`, `remountDeps`, `ssr`. Router-level defaults carry the `default` prefix. `onEnter`, `onStay`, and `onLeave` receive the match during commit; they are data callbacks, not DOM hooks.
+
+## Order of one navigation
+
+Read from the client runtime. Confirm against the installed version when timing matters.
+
+1. A Link click or `navigate` builds the location. Blockers run, each awaited. A `true` stops here; nothing has changed. A preload that started on hover keeps running.
+2. History push or replace. The URL changes. `history.subscribe` listeners run with the action; the router's own subscription calls `load`.
+3. `onBeforeNavigate`, then `onBeforeLoad`. The outgoing page's scroll positions are snapshotted here.
+4. `status` becomes `pending` and `location` moves to the destination. The old matches are still presented; the old page stays mounted and interactive.
+5. `beforeLoad` and loaders run, reusing a fresh preload or joining one in flight. Past `pendingMs`, the pending component is presented in place of the pending route inside a React transition and held at least `pendingMinMs`.
+6. If a view transition applies, `document.startViewTransition` wraps the next two steps.
+7. Inside `React.startTransition`: the matches commit, `onLoad`, then `onBeforeRouteMount`. React renders the new tree. Reused components receive new params and loader data; new ones mount and run their layout effects, including `useGSAP`.
+8. After the new tree has committed: `resolvedLocation` is set, `status` returns to `idle`, `onResolved`, then `onRendered`. Scroll restoration, the top reset, and hash scrolling run in `onRendered`. The `navigate` promise resolves.
+
+A newer navigation abandons an older one at every await, and the abandoned one emits nothing further. Nothing in this list precedes the URL change except the blocker, which is why the outro lives there.
+
+`onRendered` runs from a microtask after the root layout effect, so it sees the committed DOM, normally before paint. A page's `useGSAP` runs before it, and before scroll restoration.
+
+First load differs: a client-only app runs a full load, so every event fires with `fromLocation` undefined; after TanStack Start hydration the router acknowledges the server-rendered matches and emits only `onRendered`, with nothing changed. In both cases the page's first `useGSAP` is the mount.
+
+## Page lifecycle
+
+**mount → initial state → intro → settled → outro → end state → unmount**
+
+1. **Initial state.** The incoming page has mounted or updated in place, its final size is reserved, measurements are taken, and start values are set before anything is shown.
+2. **Intro.** Reveal the route and play one timeline to the final layout.
+3. **Settled.** Clear temporary styles. CSS owns the page. Everything is interactive.
+4. **Outro.** The outgoing page stays mounted while the blocker holds the navigation. Stop competing component animations and play one outro timeline.
+5. **End state.** Finalize outgoing targets and run completion once while still mounted. Let the navigation proceed. The outgoing tree goes away when the router commits the loaded destination.
+
+A controller may track internal states like `waiting` or `preparing`, but they serve these five phases.
+
+Store the phase in a ref owned by the root controller and mirror it as a data attribute on the route container, so CSS and tests can read it.
+
+## Outro before navigation: two paths
+
+Both run on the old page. Pick one per project and use it everywhere.
+
+**`useBlocker`, the default.** Mount it once in the root controller. `shouldBlockFn` returns `false` for `BACK`, `FORWARD`, and `GO`, for hash-only and same-location changes, and for anything the design does not transition. Otherwise it returns a promise that the outro's end callback resolves with `false`, which allows the navigation. Never return `false` because an outro or swap is already in progress: that lets the second push commit at once, the outgoing page unmounts mid-outro, its context revert kills the timeline, `onComplete` never fires, and the first promise hangs forever. A navigation that arrives during an outro is blocked too, and the lock decides which promise resolves with `true`. See [One navigation at a time](#one-navigation-at-a-time). Nothing is cancelled or re-issued: the original push continues, so `replace`, `resetScroll`, `viewTransition`, and the Link's intent survive, no blocker re-enters, and `navigate` calls and redirects get the same outro as links. The costs: the URL waits, and so do the loaders, so the end state sits on screen until the destination loads unless `preload="intent"` or `defaultPreload: 'intent'` already started the fetch on hover. Turn intent preloading on when using this path; the navigation reuses the preload or joins the loader still in flight. Set `enableBeforeUnload: false` unless the app also wants the unload dialog.
+
+`withResolver: true` is the docs' form for rendering a prompt. In a controller it has a trap: one resolver is shared by every navigation, and resolving any of them resets `status` to `idle`, so a second click during an outro replaces `proceed` and strands the first navigation. If you use it, capture `proceed` and `reset` in a ref the moment `status` turns `blocked` and keep them past the state change. The promise-returning `shouldBlockFn` gives each navigation its own promise and needs no React state; prefer it.
+
+**An intercepted Link, the alternative.** Wrap `Link` with an `onClick` that applies the router's own exclusions (modifier keys, non-primary button, `target`, `disabled`, external href), calls `preventDefault`, plays the outro, then calls `navigate` with the same `to`, `params`, `search`, `hash`, `state`, `replace`, `resetScroll`, `hashScrollIntoView`, and `viewTransition`. Because the `Link` still renders, `href`, `preload`, `activeProps`, and `data-status` survive. The costs: buttons, `navigate` calls, redirects, and forms bypass it; every option must be forwarded by hand; and if a `useBlocker` also exists, the re-issued push hits it, so pass `ignoreBlocker: true` or set a guard first. Use it only when a blocker cannot be mounted where the outro is decided.
+
+Neither path delays a document unload. `reloadDocument`, external hrefs, and the close button get at most the browser's unload dialog. A hash-only change goes through the same push; return `false` when `next.pathname` equals `current.pathname`.
+
+## One navigation at a time
+
+- Keep the pending navigation's resolver in a ref. When a second navigation is blocked during outro or preparing, decide once: resolve the earlier promise with `true` to cancel it and adopt the new destination, or resolve the new one with `true` and keep the first. Never leave a promise pending; a pending blocker holds its navigation forever.
+- Release the lock when the incoming intro starts, not when it ends: a click during the intro must kill the intro and start the outro from current values, and holding the lock through the intro leaves every link dead until it finishes.
+- Back or forward during an outro: return `false` at once, kill the outro, resolve its pending promise with `true` so the requested push never commits over the history move, and take the intro-only path.
+- A killed timeline never resolves its promise. Wrap `await` in a helper that also resolves on `onInterrupt` and returns whether the timeline completed, so an interrupted outro never leaves a blocker pending.
+- GSAP's ticker stops in a hidden tab. Race the outro against a timeout so a click from a background tab still navigates.
+- React development runs the controller's effects twice, so the blocker registers, unregisters, and registers again. Keep the phase and resolver in refs so the second run sees the first's state.
+
+## Two kinds of navigation
+
+- **Requested** (`PUSH` and `REPLACE` from a Link, `navigate`, or a submit handler): the full lifecycle. The blocker holds, the outgoing page plays its outro on live DOM, the router loads and commits, the incoming page prepares and plays its intro.
+- **Unrequested** (`BACK`, `FORWARD`, `GO`, a redirect thrown from `beforeLoad` or a loader, `router.invalidate`, `reloadDocument`, external links): the tree changes without an outro, or the document reloads. Run initial state and intro only, without travel. Keep the shell stable. Optionally give these a `viewTransition` crossfade so the swap is not a hard cut.
+
+A redirect during a requested navigation pushes again and reaches the blocker; the in-progress guard above returns `false` for it. Do not keep a copy of the old React tree to fake an outro for unrequested navigation. The outgoing route unmounts on commit, so a copy is stale immediately. Support fewer outro paths instead.
+
+## Back and forward
+
+- Detect them from `action` in `shouldBlockFn` and from `router.history.subscribe`, which fires before any router event because the history change is what starts the load. Record the action in a ref there and read it when the incoming page reports ready.
+- Never run an outro. The URL has already changed when the blocker runs; blocking reverses history and the user sees a bounce.
+- Scroll restoration runs in `onRendered`, after the page's `useGSAP`. Start history intros from `onRendered` or later, then refresh ScrollTrigger. Reveal-on-scroll targets above the restored position must not stay hidden.
+- A page reached by back that stayed matched with different params is reused, not remounted, and holds settled values. Write initial state explicitly.
+- Leaving the site and coming back may restore the document from the bfcache. No router event runs; `pagehide` only saves scroll. Leave the page readable whenever the document may unload.
+
+## Pending UI and the loading gap
+
+The router waits for loaders before it swaps, so the old page stays presented and `status` is `pending`. After `pendingMs` it presents `pendingComponent` in place of the pending route, parent layouts included, for at least `pendingMinMs`. Without a pending component the old page stays until the data arrives.
+
+- With the blocker path the outro has already finished, so the end state, or the cover, is what the user sees during the wait. Intent preloading shortens it.
+- A pending component mounts inside the route container. Give it the same geometry, treat it as unrequested content with no intro handoff, and let the boundary's ready timeout release the cover. The real page then mounts through the normal path.
+- For a pending hint in chrome, select `status` from `useRouterState` or use `useMatchRoute` with `pending: true` on the link's destination. There is no per-link status hook.
+- Data returned from a loader as an unawaited promise streams: `<Await promise fallback>` or React 19 `use()` suspends the nearest boundary. Treat each such region as a component with its own controller. See [Deferred data](route-lifetime.md#deferred-data-and-streaming).
+
+## Overlapping the old and new page
+
+The router shows one route tree. An effect that needs both pages on screen at once has two honest options:
+
+- **The browser.** `viewTransition` snapshots both trees itself. Types give the CSS the direction and the clip.
+- **A DOM snapshot.** After the outgoing page reaches end state and before resolving the blocker, deep-clone the route container into a fixed layer: strip ids and every data attribute your lifecycle selects on, set `inert` and `aria-hidden`, position it at the container's document offset shifted by the scroll. Let the navigation proceed with no cover. The incoming intro reveals the new page over the clone and removes it at settle, on a ready timeout, on back or forward mid-transition, and at the start of any new navigation.
+
+The clone is a static picture, not a React tree: nothing in it updates, and it is gone before the page is interactive. Skip the outgoing outro for this archetype; a faded end state gives the reveal nothing to sit on.
+
+## The swap gap and initial state
+
+With the blocker path the old page sits at end state while the loaders run and React commits. Cover the route container during that gap, inside the element that wraps route content and never fixed to the viewport, or the header and footer flash on every click. Uncover only after every incoming target has its size and start styles.
+
+The initial state must occupy the same layout as the settled state. Prefer `autoAlpha` and transforms. Size images, media, masks, and async regions before the intro. If the effect changes geometry, reserve the settled size with a wrapper or measure both states before writing either.
+
+The route container owns geometry during the swap: hold a stable height while trees exchange, or animate it between measured sizes on purpose; if old and new are both mounted, overlap them so only one takes up space; reserve scrollbar space if route height changes would shift it.
+
+Under TanStack Start, server HTML paints before hydration. Do not hide it unconditionally; the pre-paint rule in [SSR and hydration](route-lifetime.md#ssr-and-hydration-with-tanstack-start) is the only sanctioned way to hide before the first intro. A client-only app paints nothing before React and needs no such rule.
+
+Do not rely only on inline styles: a context revert clears them during a swap. The cover must survive cleanup until the new tree is ready.
+
+## Settled state, focus, and scroll
+
+On intro completion, mark settled once, clear temporary transforms, visibility, and `will-change`, and do not keep the page inside an active timeline to hold values.
+
+- TanStack Router moves no focus. After a client navigation focus stays wherever it was, usually on a link that has unmounted, which drops it to `body`. Move focus to the route container or main heading from the intro's completion when the design needs it, with `tabIndex={-1}` and a visible focus style. Do not steal focus from an active control.
+- Keep the router's scroll behavior. `scrollRestoration: true` restores per history entry and resets new entries to the top, both in `onRendered` before paint; the `<ScrollRestoration />` component is deprecated. `resetScroll: false` on a Link or `navigate` keeps the current position. `scrollToTopSelectors` adds nested scrollers; `scrollRestorationBehavior: 'instant'` stops a smooth scroll from running under an intro; `getScrollRestorationKey` keys by pathname instead of history entry. Without `scrollRestoration` the router still scrolls to the top and to the hash.
+- Refresh ScrollTrigger after `onRendered`, and after the intro if anything above a trigger changed height.
+- The router announces nothing. `head()` updates the title through `HeadContent`; add your own live region if the product needs navigation announced.
+
+## Combining with View Transitions
+
+`defaultViewTransition: true` or `{ types }` on the router, or `viewTransition` on a Link or `navigate`, wraps the match commit and React render in `document.startViewTransition`. `types` is an array or a function of the location change info that returns an array or `false` to skip; typed transitions need `:active-view-transition-type` support and otherwise run untyped. GSAP runs before it, outro on live DOM held by the blocker, and after it, intro on the new tree. Keep their jobs separate:
+
+- The router awaits `updateCallbackDone`, not `finished`. `onResolved`, `onRendered`, and the `navigate` promise fire while the browser animation may still be running.
+- The router does not expose the `ViewTransition` object. Either keep GSAP off the elements the transition animates so the intro can start at mount, or install a thin wrapper around `document.startViewTransition` in the client entry that remembers the active transition, and await its `finished` before the intro.
+- One engine per element per transition. A named morph and a GSAP tween on the same node fight, and a GSAP end state becomes the old snapshot. If the outro fades content the browser will morph, leave the shared element lit at end state or skip the view transition for that navigation.
+- Name only elements that morph, per page, and clear names after each transition. Name chrome to hold it still.
+- Compute direction once, from the recorded history action or from `fromLocation.state.__TSR_index` against `toLocation.state.__TSR_index` as the router's example does, return it as a type, and read the same decision in the GSAP builders.
+- Add `::view-transition { pointer-events: none }` so a running transition does not swallow clicks.
+- Feature-detect `document.startViewTransition`. Every GSAP path must run when it is missing.
+- Reduced motion covers both: zero view transition durations in CSS, return `false` from `types` under the media query, and take the GSAP reduced path.
+
+## Cases to design for
+
+- Navigation requested mid-intro.
+- Two destinations clicked quickly.
+- Back or forward with no outro, including mid-outro.
+- A page reused with new params, and a search-param-only change.
+- A `navigate` call or redirect that bypasses any Link wrapper.
+- A hash-only link.
+- A slow loader that shows the pending component.
+- An external link and a `reloadDocument` link, which unload the document.
+- Split text or scroll plugins that changed the DOM before cleanup.
+- Streamed data arriving after the intro.
+- React development double-running the controller's effects.
+
+Each case must end on one visible, interactive page with stable layout and no stale inline styles.

package/skills/ui/gsap-tanstack-router/references/verification.md

@@ -0,0 +1,41 @@
+# 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. Regenerate `routeTree.gen.ts` if file-based routes changed.
+- Confirm settled content is visible, interactive, and free of leftover GSAP inline styles.
+- Confirm timelines, triggers, listeners, plugin DOM changes, the blocker, and the history subscription are cleaned up on unmount and on a reused route's rerun.
+- Under TanStack Start, confirm the page is readable with JavaScript disabled and with the pre-paint mark set but hydration blocked.
+- Test reduced motion when the change has a reduced-motion branch, for GSAP and for any `viewTransition` types.
+
+## 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. Under Start, throttle the network and reload; no settled server HTML flashes before hydration.
+- Intro ends in one settled state.
+- Outro keeps the node mounted until completion runs, and the blocked navigation proceeds only then.
+- Rapid or interrupted input ends in one coherent state, with no blocker promise left pending.
+- Layout boxes do not jump.
+
+For route navigation, test the paths the change affects: an ordinary internal link, back and forward, a rapid double navigation, a same-route param change, a search-param-only change, a `navigate` call, a slow loader that shows the pending component, and a reload. Confirm URL, visible route, focus, history, and scroll agree, and that `status` returns to `idle`.
+
+For a reused route, the returning lifecycle must run initial state and intro on its preserved DOM with no doubled tweens, and scroll triggers must measure correctly after the new data renders.
+
+When both `viewTransition` and GSAP are involved, confirm no element is animated by both and that clicks land during a running transition.
+
+For conditional components, test show, hide, and one interruption. Confirm unmount happens after the outro.
+
+## Builds and wider checks
+
+Run a production build, and `vite preview` or the Start server, for changes to routes, the router options, the Vite or Start config, dependencies, the root document shell, or anything release-facing; the dev server hydrates differently from the built output and React development runs effects twice. Run wider browser, accessibility, responsive, streaming, 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-timeline/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: gsap-timeline
+description: Official GSAP skill for timelines ,  gsap.timeline(), position parameter, nesting, playback. Use when sequencing animations, choreographing keyframes, or when the user asks about animation sequencing, timelines, or animation order (in GSAP or when recommending a library that supports timelines).
+license: MIT
+---
+
+# GSAP Timeline
+
+## When to Use This Skill
+
+Apply when building multi-step animations, coordinating several tweens in sequence or parallel, or when the user asks about timelines, sequencing, or keyframe-style animation in GSAP.
+
+**Related skills:** For single tweens and eases use **gsap-core**; for scroll-driven timelines use **gsap-scrolltrigger**; for React use **gsap-react**.
+
+## Creating a Timeline
+
+```javascript
+const tl = gsap.timeline();
+tl.to(".a", { x: 100, duration: 1 })
+  .to(".b", { y: 50, duration: 0.5 })
+  .to(".c", { opacity: 0, duration: 0.3 });
+```
+
+By default, tweens are **appended** one after another. Use the **position parameter** to place tweens at specific times or relative to other tweens.
+
+## Position Parameter
+
+Third argument (or position property in vars) controls placement:
+
+- **Absolute**: `1` ,  start at 1 second.
+- **Relative (default)**: `"+=0.5"` ,  0.5s after end; `"-=0.2"` ,  0.2s before end.
+- **Label**: `"labelName"` ,  at that label; `"labelName+=0.3"` ,  0.3s after label.
+- **Placement**: `"<"` ,  start when recently-added animation starts; `">"` ,  start when recently-added animation ends (default); `"<0.2"` ,  0.2s after recently-added animation start.
+
+Examples:
+
+```javascript
+tl.to(".a", { x: 100 }, 0);           // at 0
+tl.to(".b", { y: 50 }, "+=0.5");      // 0.5s after last end
+tl.to(".c", { opacity: 0 }, "<");     // same start as previous
+tl.to(".d", { scale: 2 }, "<0.2");    // 0.2s after previous start
+```
+
+## Timeline Defaults
+
+Pass defaults into the timeline so all child tweens inherit:
+
+```javascript
+const tl = gsap.timeline({ defaults: { duration: 0.5, ease: "power2.out" } });
+tl.to(".a", { x: 100 }).to(".b", { y: 50 }); // both use 0.5s and power2.out
+```
+
+## Timeline Options (constructor)
+
+- **paused: true** ,  create paused; call `.play()` to start.
+- **repeat**, **yoyo** ,  same as tweens; apply to whole timeline.
+- **onComplete**, **onStart**, **onUpdate** ,  timeline-level callbacks.
+- **defaults** ,  vars merged into every child tween.
+
+## Labels
+
+Add and use labels for readable, maintainable sequencing:
+
+```javascript
+tl.addLabel("intro", 0);
+tl.to(".a", { x: 100 }, "intro");
+tl.addLabel("outro", "+=0.5");
+tl.to(".b", { opacity: 0 }, "outro");
+tl.play("outro");  // start from "outro"
+tl.tweenFromTo("intro", "outro"); // pauses the timeline and returns a new Tween that animates the timeline's playhead from intro to outro with no ease.
+```
+
+## Nesting Timelines
+
+Timelines can contain other timelines.
+
+```javascript
+const master = gsap.timeline();
+const child = gsap.timeline();
+child.to(".a", { x: 100 }).to(".b", { y: 50 });
+master.add(child, 0);
+master.to(".c", { opacity: 0 }, "+=0.2");
+```
+
+## Controlling Playback
+
+- **tl.play()** / **tl.pause()**
+- **tl.reverse()** / **tl.progress(1)** then **tl.reverse()**
+- **tl.restart()** ,  from start.
+- **tl.time(2)** ,  seek to 2 seconds.
+- **tl.progress(0.5)** ,  seek to 50%.
+- **tl.kill()** ,  kill timeline and (by default) its children.
+
+## Official GSAP Best practices
+
+- ✅ Prefer timelines for sequencing
+- ✅ Use the **position parameter** (third argument) to place tweens at specific times or relative to labels.
+- ✅ Add **labels** with `addLabel()` for readable, maintainable sequencing.
+- ✅ Pass **defaults** into the timeline constructor so child tweens inherit duration, ease, etc.
+- ✅ Put ScrollTrigger on the timeline (or top-level tween), not on tweens inside a timeline.
+
+## Do Not
+
+- ❌ Chain animations with **delay** when a **timeline** can sequence them; prefer `gsap.timeline()` and the position parameter for multi-step animation.
+- ❌ Forget to pass **defaults** (e.g. `defaults: { duration: 0.5, ease: "power2.out" }`) when many child tweens share the same duration or ease.
+- ❌ Forget that **duration** on the timeline constructor is not the same as tween duration; timeline “duration” is determined by its children.
+- ❌ Nest animations that contain a ScrollTrigger; ScrollTriggers should only be on top-level Tweens/Timelines.