@nerdev/skillset 0.2.1

package/skills/ui/gsap-sveltekit/references/page-lifetime.md

@@ -0,0 +1,63 @@
+# Page lifetime
+
+Read this to know when a page mounts, updates in place, or unmounts, how the Svelte 5 lifecycle fits GSAP, and how Svelte's own transitions coexist with it.
+
+## Reuse versus remount
+
+SvelteKit renders a route as a pyramid: root layout, nested layouts, page. A navigation swaps only the levels whose component changed.
+
+- Same route, new params or search params: the `+page.svelte` is reused. Its `data` and `page` update; `onMount`, `onDestroy`, and effects without a changed dependency do not run.
+- Different route under the same layouts: the page unmounts and the new one mounts. The shared layouts stay, with their state, timelines, and listeners.
+- A route that breaks out of a layout with `+page@` or a group: the layouts below the break remount too.
+- `invalidate` and `invalidateAll` re-run `load` and update props. Nothing remounts.
+- Shallow routing with `pushState` changes `page.state` only.
+
+So a page intro tied to `onMount` plays once per mount, not once per visit. Two fixes:
+
+- **`afterNavigate` in the page, the default for GSAP.** It fires on mount and after every navigation while the page stays mounted, with `type`, `from`, and `to`. Compare `from?.url.pathname` with `to?.url.pathname`, adding params when they mean a different screen, and skip when only search params changed. The page keeps its state and the DOM already holds settled values, so kill the previous timeline first and write initial state with `set` or `fromTo`, never a `from` tween that trusts a fresh node.
+- **`{#key page.url.pathname}` around `{@render children()}` in the layout.** Every pathname change destroys and recreates the page, so `onMount` intros replay and `in:` and `out:` directives on the wrapper play. Use it when the page must be re-instantiated anyway or the effect is a Svelte transition. It discards page state and inner scroll positions, and it remounts on param changes, which is what the docs offer for that case.
+
+Do not key the whole layout on `page.url`. That remounts the shell and its chrome on every navigation.
+
+## Layouts and the controller
+
+The root `+layout.svelte` mounts once per document and outlives every client-side navigation. That makes it the home of the route transition controller: one `bind:this` route container around `{@render children()}`, the navigation hooks, the phase in `$state`, and the cover. Nested layouts persist for their subtree and are the place for section-level chrome motion.
+
+Pages register intro and outro builders with the controller through context or a shared module and unregister in their teardown. The controller calls the outgoing page's outro from `onNavigate` and the incoming page's intro from `afterNavigate`. A page that registers nothing gets the container-level default.
+
+Hooks registered in a page are removed when it unmounts. A `beforeNavigate` in a page sees the navigation away from that page. An `afterNavigate` in a page sees its own arrival and every navigation while it stays mounted.
+
+## Svelte 5 lifecycle for GSAP
+
+- `onMount` with a synchronous callback returning cleanup, or `$effect` returning teardown, both run only in the browser after the DOM exists. `gsap-frameworks` covers the `gsap.context` and `revert` pattern. Use it unchanged.
+- `$effect` re-runs when state it read synchronously changes, running its teardown first. An effect that reads `page.url`, `data`, or `navigating` re-runs on navigation, reverting and rebuilding the context, including on search-param changes. Read those values inside `afterNavigate` or through `untrack`, not in the effect body, unless the rebuild is intended.
+- `bind:this` values are `undefined` during initialization. Read them in an effect or `onMount`.
+- `$effect.pre` runs before the DOM update it is scheduled with. `tick()` resolves after pending changes are applied. Use them to measure before and after an update. `beforeUpdate` and `afterUpdate` do not exist in runes mode.
+- `{@attach}` runs a function in an effect when its element mounts, again when state it reads changes, with an optional teardown. It suits per-element GSAP setup that must follow an element through `{#each}` blocks.
+- Store the phase in `$state` and render a data attribute from it. Do not infer the phase from opacity or DOM presence.
+- `onDestroy` runs during server rendering. Keep GSAP out of it, or guard with `browser`.
+
+## Combining engines
+
+Svelte transitions, GSAP, and View Transitions can share a page but not a node.
+
+- A `transition:`, `in:`, or `out:` directive drives its node through the Web Animations API or a `tick` function. A GSAP tween on the same node writes the same properties and one of them loses. Put the directive on a wrapper and GSAP inside it, or use one engine.
+- When a block with an `out:` directive is removed, every element in the block stays in the DOM until every outro in it finishes, and the new content is inserted at once, so old and new are in flow together. Use that when the effect is a crossfade in a stacked container. Avoid it when GSAP owns the outro: the block lingers past the GSAP end state after the router has moved on.
+- Directives are local by default: one plays when its own block is created or destroyed, including when the router swaps a page whose root carries it, but not when an outer `{#if}` in the same component toggles. Add `|global` only when that outer toggle should play it.
+- Svelte transitions ignore `@media (prefers-reduced-motion)` rules that zero CSS durations. Zero their `duration` from `prefersReducedMotion.current` in `svelte/motion` and take the GSAP reduced path in the same condition.
+- `svelte/animate` on `{#each}` items and GSAP Flip solve the same problem. Pick one per list.
+- View Transitions snapshot whatever the DOM shows, including a half-finished directive or a GSAP end state. Start them only after both have reached the state you want photographed.
+
+## Conditional content
+
+`{#if}` removes a block synchronously unless a directive inside it is outroing. For GSAP-driven show and hide, keep the node mounted with a presence controller: render while `visible || leaving`, play the outro, and clear `leaving` from the end callback. For a plain fade, `out:fade` on the block is the presence controller and needs no GSAP.
+
+A shallow-routed modal is a presence controller with history as its close. Open with `pushState`, close by playing the outro and then calling `history.back()`, and treat the resulting `popstate` as the removal, not as a page navigation. Undo scroll locks, key listeners, and focus in the modal's teardown, which also covers a back navigation you did not initiate.
+
+## SSR and hydration
+
+- `$effect` and `onMount` do not run on the server. Keep GSAP out of module scope, or guard with `browser` from `$app/environment`. Importing GSAP on the server is harmless; running it is not.
+- Register plugins once in a browser-guarded module that other modules import.
+- Hydration paints server HTML first. The first-paint rule in [The swap gap and initial state](sveltekit-navigation.md#the-swap-gap-and-initial-state) is the only sanctioned way to hide before the first intro.
+- `csr = false` on a page removes the client router; navigation hooks never fire there. `ssr = false` gives an empty shell until the client renders, so the first intro can wait for mount without a pre-paint rule.
+- `afterNavigate` with `type: 'enter'` is the first-load intro. A prerendered page gets it on hydration like any other. A bfcache restore runs no hook at all.

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

@@ -0,0 +1,160 @@
+# SvelteKit navigation
+
+Read this when changing route-level motion or navigation.
+
+## Router APIs
+
+Check the installed SvelteKit types before using these. Everything below comes from `$app/navigation` unless noted. The hooks must be called during component initialization and stay active while that component is mounted.
+
+- `beforeNavigate(cb)`: fires before every navigation the router sees: link clicks, `goto`, GET forms, back and forward, and leaving the document. Receives `type`, `from`, `to`, `willUnload`, `delta` (popstate only), `complete`, and `cancel()`. Not called for a redirect issued while a navigation is already in flight.
+- `onNavigate(cb)`: fires immediately before the new page renders, only for client-side navigation. Return a promise and SvelteKit waits for it before updating the DOM. Return a function, or a promise resolving to one, and it runs once after the DOM has updated.
+- `afterNavigate(cb)`: fires after every navigation while the calling component stays mounted, and once with `type: 'enter'` after hydration. That first call is dispatched from the router's initialization one microtask after the root mounts, so whether a page component has registered by then is a race; the intro path must also work when the page mounts after the `enter` call has passed. `to.scroll` is the position actually applied.
+- `goto(url, { replaceState, noScroll, keepFocus, invalidateAll, invalidate, state })`: programmatic navigation. Resolves when the navigation completes and rejects when it is cancelled or aborted. Not for external URLs; assign `location` instead.
+- `preloadData(href)`: imports the destination's code and runs its `load` now. If the next navigation goes there, the result is reused.
+- `disableScrollHandling()`: skips the router's scroll for the navigation in progress. Legal only while the page is updating.
+- `pushState` and `replaceState`: history entries without navigation, for shallow routing.
+- `navigating` from `$app/state`: `from`, `to`, `type`, and `delta` while a navigation is in flight, `null` otherwise. `page` from `$app/state`: current `url`, `route`, `params`, and `state`. Both are reactive only in runes mode.
+- Link attributes: `data-sveltekit-preload-data`, `data-sveltekit-preload-code`, `data-sveltekit-noscroll`, `data-sveltekit-replacestate`, `data-sveltekit-keepfocus`, `data-sveltekit-reload`. They apply to an `a` or any ancestor, and to GET forms.
+
+`type` values: `link`, `goto` (also redirects), `form` (GET forms), `popstate` (back and forward), `enter` (hydration, `afterNavigate` only), `leave` (document unload, `beforeNavigate` only).
+
+The navigation object carries an undocumented `event`. Do not build on it.
+
+## Order of one navigation
+
+Read from the client runtime. Confirm against the installed version when timing matters.
+
+1. `beforeNavigate` callbacks. Any `cancel()` stops here. Cancelling a `popstate` also moves history back by `delta`.
+2. `navigating` is set. `load` functions run, reusing a matching preload.
+3. The outgoing page's snapshot is captured. History is pushed or replaced, so the URL bar already shows the destination.
+4. `onNavigate` callbacks, awaited together. The old page is still mounted and live, and `page` still reports the old URL.
+5. Focus is blurred, the component tree updates, and Svelte flushes. Reused components receive new props; new ones mount and run `onMount` and `$effect`.
+6. Scroll: restored for `popstate`, kept for `noScroll`, moved to a hash target, otherwise top. Skipped after `disableScrollHandling()`.
+7. Focus is reset to `body`, or an `autofocus` element, unless `keepFocus` was set or something already moved it.
+8. `complete` resolves, `afterNavigate` callbacks and the functions returned from `onNavigate` run, the snapshot is restored for `popstate`, and `navigating` returns to `null`.
+
+The router checks for a newer navigation after step 2 and after step 5 and abandons the older one there, rejecting its `complete`. It does not check between steps 4 and 5, so an older `onNavigate` that resolves late still updates the DOM once before it is abandoned. The lock below exists for this.
+
+## 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 router waits. Stop competing component animations and play one outro timeline.
+5. **End state.** Finalize outgoing targets and run completion once while still mounted. Resolve the router's wait. The outgoing tree goes away as the incoming one renders.
+
+A controller may track internal states like `waiting` or `preparing`, but they serve these five phases.
+
+Store the phase in `$state` owned by the layout controller and render it as a data attribute on the route container, so CSS and tests can read it. Svelte batches state, so two phase writes in one tick reach the DOM as one attribute change and an observer sees only the last; `await tick()` between them, or write the attribute on the container directly when consecutive phases must each be visible.
+
+## Outro before navigation: two hooks
+
+Both run on the old page. Pick one per project and use it everywhere. The choice turns on one fact: `history.pushState` runs before the router awaits `onNavigate`, so on that path the address bar already shows the destination while the old page animates. If the outro must play with the URL unchanged, which is what "outro before navigation" usually means, only `beforeNavigate` does it.
+
+**`beforeNavigate`, the default.** Call `cancel()`, play the outro on the untouched page, then `goto(to.url)` from the end callback. The outro starts on click and the URL waits. The costs: the re-issued navigation re-enters `beforeNavigate`, so set a guard before `goto` and consume it inside the callback that sees the re-issued navigation, not on the `goto` promise, which resolves too late and leaves a window where the next real click passes unblocked; the re-issued navigation is `type: 'goto'` and drops the link's `replaceState`, `noScroll`, and `keepFocus` intent unless the controller reads those attributes from the link itself; a GET form cannot be re-issued cleanly; and `load` runs after the outro, so the end state sits on screen until the new page arrives and needs a cover or a presentable look. Call `preloadData(to.url.href)` when the outro starts so the fetch overlaps it. Never cancel `popstate`.
+
+**`onNavigate`, the alternative.** Return the outro's promise; SvelteKit renders the new page when it resolves. Nothing is cancelled or re-issued, so `data-sveltekit-*` options, `goto` options, GET forms, and `type` survive, `afterNavigate` reports what really happened, and there is no swap gap: `load` has already finished, so the new page renders the moment the outro ends and no cover is needed. The costs: the URL changes before the outro, and the outro starts after `load`, not on click, so a slow route shows a still page first. Mitigate the second with `data-sveltekit-preload-data="hover"`, the template default, and a pending style from `navigating`. Return nothing for `popstate`. Use it when a URL that leads the animation is acceptable.
+
+Neither hook delays a `willUnload` navigation. `type: 'leave'` cannot be delayed; `cancel()` there only raises the browser's unload dialog. An external link, where `to.route.id` is `null`, can be cancelled in `beforeNavigate`, outroed, and followed with `location.assign`, which is the `gsap-vanilla` path.
+
+## One navigation at a time
+
+The lock depends on the path.
+
+- On the `beforeNavigate` path the first click cancelled its navigation, so the router is idle during the outro and `beforeNavigate` fires again for a second click. While the phase is `outro` or the incoming page is preparing, `cancel()` `link`, `goto`, and `form` navigations, or record the destination and `goto` it from the end callback if the design retargets.
+- On the `onNavigate` path there is no lock to hold. The router runs `beforeNavigate` callbacks only while it is idle, and it is busy from the moment it accepted the first click until just before `afterNavigate`, so a second click never reaches them. It starts a newer navigation that supersedes the first; the router abandons the old one at its next check. Kill the outro so its promise settles and let the newer navigation own the page.
+- Do not cancel `popstate`. Kill the running outro so its promise resolves at once and the pending navigation commits before the history navigation renders.
+- 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.
+
+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 `onNavigate` pending.
+
+GSAP's ticker stops in a hidden tab. Race the outro against a timeout so a click from a background tab still navigates.
+
+## Two kinds of navigation
+
+- **Requested** (`link`, `goto`, `form`): the full lifecycle. The outgoing page plays its outro on live DOM, the router waits, the incoming page prepares and plays its intro.
+- **Unrequested** (`popstate`, redirects from `load`, `invalidateAll` re-renders, links marked `data-sveltekit-reload`): the tree changes without an outro, or the document reloads. Run initial state and intro only, without travel. Keep the shell stable. Optionally wrap the swap in `document.startViewTransition` from `onNavigate` so it is not a hard cut.
+
+Do not keep a copy of the old page to fake an outro for unrequested navigation. Support fewer outro paths instead.
+
+## Back and forward
+
+`popstate` goes through `beforeNavigate`, `onNavigate`, and `afterNavigate` like any navigation, with `delta` and, before the DOM updates, `to.scroll` holding the position that will be restored.
+
+- Never run an outro. Return nothing from `onNavigate`.
+- The router restores scroll before `afterNavigate`. Start the intro from `afterNavigate`, then refresh ScrollTrigger. Reveal-on-scroll targets above the restored position must not stay hidden.
+- Snapshots are restored after `afterNavigate`. Do not put the phase in a snapshot.
+- A page reached by back that was reused rather than remounted still holds settled values. Write initial state explicitly.
+- Leaving the site and coming back may restore the document from the bfcache. SvelteKit only clears `navigating` on `pageshow`; no hook runs. Leave the page readable whenever `willUnload` is true.
+
+## Overlapping the old and new page
+
+The router shows one page tree. An effect that needs both on screen at once has three honest options.
+
+- **The browser.** `document.startViewTransition` in `onNavigate` snapshots both. A class on `html` gives the CSS the direction.
+- **A Svelte `out:` directive** on the page root, or on a `{#key}` wrapper in the layout. Svelte inserts the new page at once and keeps the old one until its outro ends, both in normal flow, so stack them with a grid or position the outgoing one absolutely inside the route container, and keep GSAP off the node that carries the directive. See [Combining engines](page-lifetime.md#combining-engines).
+- **A DOM snapshot.** After the outgoing page reaches end state and before resolving `onNavigate`, 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. The incoming intro reveals the new page over the clone and removes it at settle, on a ready timeout, on `popstate`, and at the start of any new navigation.
+
+The clone is a static picture, not a component: nothing in it updates, and it is gone before the page is interactive.
+
+## The swap gap and initial state
+
+With `onNavigate` there is no gap: the new page renders as soon as the promise resolves. With `beforeNavigate` the old page sits at end state while `load` runs. 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.
+
+Server-rendered HTML paints before hydration. Do not hide it unconditionally. If initial state must hide before first paint:
+
+- Put an inline script first in `body` in `src/app.html` that marks `html` 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.
+- Skip the mark under `prefers-reduced-motion` so the page paints settled.
+- 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).
+- Register recovery before setup. Advance the phase only after start values and completion handlers are ready, in the same turn that starts the intro.
+- Keep content readable without JavaScript and keep the swap cover separate from the first-paint 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.
+
+## Preloading and streaming
+
+- Hover and tap preloading run `load` before the click. With `onNavigate` this is what lets the outro start promptly. With `beforeNavigate`, `preloadData` at outro start does the same.
+- Preloaded data is dropped by invalidation or by a navigation elsewhere. Do not assume it survives a long outro.
+- Promises streamed from `load` resolve after the page renders. Treat each streamed region as a component with its own controller: explicit initial state on arrival, a short intro, settled, cleanup. Reserve its block size so arrival moves nothing. Query outro targets when the outro is built, not at setup, so content that streamed in after setup leaves with the page.
+
+## 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.
+
+- SvelteKit focuses `body`, or an `autofocus` element, before `afterNavigate`. Move focus to the main heading from `afterNavigate` only 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. Call `disableScrollHandling()` only while the page is updating, from the incoming page's `onMount` or an effect, then own the scroll yourself. In the current runtime `afterNavigate` runs after the scroll has been applied; check the installed version before calling it there.
+- Refresh ScrollTrigger after scroll restoration, and after the intro if anything above a trigger changed height.
+- SvelteKit's live region announces the new `title`. Give every page a title in `svelte:head` so an animated navigation is still announced.
+
+## Combining with View Transitions
+
+The documented recipe wraps the update: `onNavigate` returns a promise that `document.startViewTransition`'s callback resolves, and the callback then awaits `navigation.complete`, so the old snapshot is taken before the DOM updates and the new one after. GSAP runs before it, outro on live DOM awaited before the transition starts, and after it, intro on the new tree after `finished` for elements the transition touched. Keep their jobs separate:
+
+- 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.
+- Set a direction class on `html` before starting the transition and remove it in `finished`. 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 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.
+- Programmatic `goto` and a GET form that bypass any link wrapper.
+- A hash-only link, which the router leaves to the browser.
+- A redirect from `load`, which skips `beforeNavigate`.
+- An external link and a `data-sveltekit-reload` link, which unload the document.
+- Split text or scroll plugins that changed the DOM before cleanup.
+- Streamed data arriving after the intro.
+
+Each case must end on one visible, interactive page with stable layout and no stale inline styles.

package/skills/ui/gsap-sveltekit/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 `svelte-check`, lint, format, and test commands where they exist.
+- 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 a reused page's re-run.
+- 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 Svelte directive.
+
+## 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. 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 only then does the held navigation re-issue or the `onNavigate` promise resolve. On the `beforeNavigate` path the URL is unchanged for the whole outro.
+- Rapid or interrupted input ends in one coherent state.
+- 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 `goto`, and a reload. Confirm URL, visible page, focus, history, and scroll agree, and that `navigating` returns to `null`.
+
+For a reused page, the returning lifecycle must run initial state and intro on its preserved DOM with no doubled tweens, and scroll triggers must measure correctly after new data renders.
+
+When Svelte directives or View Transitions are involved, confirm no element is animated by two engines, outroing blocks are gone once their outro ends, and clicks land during a running transition.
+
+For conditional components, test show, hide, and one interruption. Confirm removal happens after the outro.
+
+## Builds and wider checks
+
+Run a production build for changes to routes, `svelte.config.js`, page options, dependencies, `src/app.html`, or anything release-facing; the dev server hydrates differently from the built output. Serve the build the way the adapter does: under `adapter-node` that is `node build`, since `vite preview` serves no server-rendered routes there. 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-tanstack-router/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: gsap-tanstack-router
+description: "Build or review TanStack Router for React and TanStack Start animation: GSAP page transitions, component enter/exit, scroll effects, useBlocker, pending UI, route reuse, and cleanup. Use even when GSAP is unnamed, including choosing viewTransition. Also covers hidden-content recovery and first-load performance. Not for Solid, other routers, React without routing, or isolated GSAP API questions."
+license: MIT
+metadata:
+  short-description: GSAP page and component lifecycles in TanStack Router
+---
+
+# GSAP TanStack Router
+
+**mount → initial state → intro → settled → outro → end state → unmount**
+
+Mount and unmount belong to React; animation owns the five phases between them. TanStack Router preserves shared layouts and can reuse routes on parameter changes; pending UI and loaders also affect when the new page appears.
+
+Keep the requested look and existing project conventions. Add GSAP/plugins only as needed; do not replace the chosen animation library unless asked.
+
+## Start with the project
+
+Read repository instructions, existing animation, layouts, navigation, CSS, accessibility conventions, and checks. Then:
+
+1. Confirm `@tanstack/react-router`. Next.js belongs to `gsap-nextjs`, React Router to `gsap-react-router`, React without a router to `gsap-react`. Solid Router is out of scope.
+2. Read the installed `@tanstack/react-router` version and, when present, `@tanstack/react-start`. Prefer their bundled types over memory: `node_modules/@tanstack/router-core/dist/esm/router.d.ts` for `RouterOptions`, `RouterState`, and `RouterEvents`, `node_modules/@tanstack/react-router/dist/esm/useBlocker.d.ts` for the blocker, `node_modules/@tanstack/history/dist/esm/index.d.ts` for history actions. The TanStack/router repository's `docs/router/` and `docs/start/` are the source of truth. The loading architecture changed during the 1.16x and 1.17x releases; `RouterState.isTransitioning` is gone from router-core 1.171.2x, and `useBlocker` is still marked experimental.
+3. Tell file-based routes (`createFileRoute`, `routeTree.gen.ts`, `__root.tsx`) from code-based routes (`createRoute`, `createRootRoute`). The lifecycle is the same; only where route options live differs.
+4. Tell TanStack Start (SSR, a root document shell with `HeadContent` and `Scripts`) from a client-only Vite app (`RouterProvider` rendered into a div). Client-only apps paint nothing before React, so they need no pre-paint rule. Check `ssr` per route, `defaultSsr`, `spa.enabled`, and prerendering.
+5. Read the router options: `defaultPreload`, `defaultPendingComponent`, `defaultPendingMs`, `defaultPendingMinMs`, `defaultViewTransition`, `scrollRestoration`, `defaultStaleTime`, `defaultRemountDeps`. Each changes when pages mount and what the user sees while they load.
+
+## Choose the engine
+
+Use `defaultViewTransition` or Link/`navigate` `viewTransition` for snapshot morphs or page crossfades. Use GSAP for live-DOM outros that gate navigation, interruptible sequences, split text, or scroll-linked motion. One engine per element; see [combining engines](references/tanstack-navigation.md#combining-with-view-transitions).
+
+## Read only what you need
+
+- Invisible entrances, failed initialization, indexing, and first-load performance: [Initialization and recovery](references/initialization.md), plus the [framework integration](references/motion-system.md#initialization-and-recovery).
+- Router APIs and the order of one navigation, outro before navigation with `useBlocker` or an intercepted Link, the lock, back and forward, pending UI, the swap gap, scroll, focus, View Transitions: [TanStack navigation](references/tanstack-navigation.md).
+- Route reuse versus `remountDeps`, layouts and `Outlet`, the React lifecycle for GSAP, conditional content, TanStack Start SSR and hydration, deferred data: [Route lifetime](references/route-lifetime.md).
+- The five phases, GSAP setup, show and hide, layout stability, scroll, text, plugins: [Lifecycle implementation](references/motion-system.md).
+- Before calling work done: [Verification](references/verification.md).
+
+Install the [official GSAP skills](https://github.com/greensock/gsap-skills) alongside this repository. Load `gsap-core` for API details and `gsap-react` for component setup only as needed.
+
+## Rules
+
+- Preserve invisible intros on successful setup; recover the current incoming owner on failure. Follow the initialization contract before adding hiding rules.
+- GSAP runs only on the client. `useGSAP` never runs on the server; keep GSAP calls out of module scope in files Start renders on the server. Scope selectors. Clean up every tween, trigger, split, and listener.
+- Reserve final geometry with normal CSS and a stable wrapper; overlap outgoing/incoming content without doubling layout space.
+- Mount, then set initial values, then paint. Successful initialization never flashes settled content before the intro. Under Start, server HTML paints before hydration, so hide intro targets only under a root attribute set by a `ScriptOnce` inline script, only during the initial phase, with a no-JavaScript path.
+- Animate to one settled state and clear temporary styles there.
+- Keep outgoing pages mounted and visible through outro and end state. The router swaps only after every blocker allows the navigation and the loaders finish; resolve the blocker from the end callback.
+- No router event fires before the URL changes. `onBeforeNavigate` runs after the history commit; only a blocker runs before it.
+- A navigation to the same route with new params reuses the component. Run the lifecycle again against DOM that already holds settled values, keyed on the params, or set `remountDeps`.
+- Back and forward arrive with `action` `BACK`, `FORWARD`, or `GO`. Never run an outro for them; the URL has already moved when the blocker runs. Give them an intro-only path after scroll restoration.
+- `useLocation` moves to the destination when loading starts, before the new page mounts. Do not key route content on it; key on the presented matches or on `resolvedLocation`.
+- Keep native link behavior, preloading, `activeProps`, focus, scroll, and no-JavaScript readability.
+- Reduced motion reaches the same settled state and still fires every completion callback, including the one that lets the blocked navigation proceed.
+- Define interruption and rapid-click behavior; completion must release navigation waits exactly once.
+- Verify in a real browser when practical. Use a production build for route, config, dependency, or release changes.

package/skills/ui/gsap-tanstack-router/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "GSAP TanStack Router"
+  short_description: "GSAP page and component lifecycles in TanStack Router"
+  default_prompt: "Use $gsap-tanstack-router to add GSAP page transitions and component animation to this TanStack Router app."
+
+policy:
+  allow_implicit_invocation: true

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

@@ -0,0 +1,87 @@
+<!-- Generated from shared/initialization.md; run scripts/sync_initialization.py. -->
+
+# Invisible intros, recovery, and first load
+
+Read this whenever an entrance hides meaningful content. The matching framework skill owns initialization, navigation, recovery, and interruption. Motion recipes own teardown and restoration of their changes. Styles select the look and pacing only.
+
+## Keep the successful intro
+
+Build readable, settled HTML and CSS first. Preserve invisible-to-visible entrances with a small early script and scoped pre-paint CSS:
+
+```css
+html[data-motion-boot="pending"] [data-motion-owner][data-phase="initial"][data-intro],
+html[data-motion-boot="pending"] [data-motion-owner][data-phase="initial"] [data-intro] {
+  visibility: hidden;
+}
+```
+
+Names are examples. Use separate attributes for boot status, motion preference, and lifecycle phase. Rename a `data-motion="js"` boot example if the app already uses `data-motion="full|reduced"` for preference. Opt in only targets intended to enter visibly, including hidden ancestors, shell, cards, and footer. Give independent owners their own readiness records. One ready page must not cancel a footer's protection.
+
+- Run the marker before content can paint, using the framework's document integration and CSP nonce/hash support. Arm its recovery timer before setting the marker. It must work without GSAP or the application bundle. If the marker is blocked, content stays readable.
+- Never emit the active marker in server HTML. JavaScript disabled means no marker and readable HTML. A `noscript` override alone does not cover JavaScript enabled with a failed bundle.
+- Skip hiding under reduced motion. Preserve completion, focus, navigation, and removal semantics through the instant path.
+- Before releasing CSS hiding, prepare all required start values and attach the entrance's completion/interruption handlers. Start the timeline in the same turn. Do not flip the phase early to claim readiness: that can flash settled content.
+- Do not hide server content through unconditional CSS, inline styles, client-only wrappers, or a hidden ancestor that the fallback cannot restore.
+
+## Bound initialization, not choreography
+
+Give each incoming owner an initialization deadline, measured from its first pre-paint hiding. Choose and document a short budget; roughly one second is a starting point, not a universal performance target.
+
+The early timer covers bundle delivery and hydration. Register recovery before any setup work, including plugin registration, selectors, initial writes, and splits. Keep the deadline armed through required font/media preparation and timeline construction. Registration or a `live` flag is not readiness. Handing off timers must leave no unprotected interval and must not restart the budget.
+
+A successful handoff occurs only when the prepared intro can run with its handlers attached. Cancel the initialization timer then. A deliberate hold or stagger inside that timeline belongs to animation duration, even if it exceeds the initialization budget. Handle runtime exceptions and interruptions separately; if a running timeline needs a watchdog, derive it from its planned duration, delay, repeats, and pause policy. Never cut a healthy intro short with the boot timer. Recheck deadlines on return from a suspended tab; timers cannot recover a blocked main thread.
+
+Wait only for dependencies the effect needs. Bound font readiness, image load/decode, SplitText auto-split preparation, and frame waits. Prefer reserved image dimensions and a fallback font or unsplit heading over waiting for every font, image, or window `load`. A timed-out promise may still resolve: racing it does not cancel its continuation.
+
+## Recover one owner
+
+Track an owner, a visit/generation token, and a terminal recovery decision outside disposable effect setup. Use boot status such as `pending`, `running`, `recovered`, `disposed` separately from the framework's lifecycle phases. A recovery is permanent for that visit; a genuine later navigation may create a new visit. Repeated setup is not a new visit.
+
+On timeout, rejection, setup exception, or failed entrance:
+
+1. Verify the captured owner and generation are still current and intended to be visible. Invalidate the generation first. Mark it recovered so reentrant handlers cannot restart it.
+2. Abort preparation where supported. Cancel queued frames, timers, event listeners, observers, and subscriptions that can recreate motion. Kill owned timelines, delayed calls, triggers, and ambient effects before restoring content. Do not kill unrelated GSAP work globally.
+3. Run registered effect teardown in reverse order. Each builder must roll back partial changes if it throws before returning a handle. Continue other cleanup if one disposer throws; always reach the final readable fallback.
+4. Revert split wrappers, masks, cloned accessibility text, and plugin DOM changes. Preserve framework-owned nodes and nested links/controls; never overwrite their subtree with a stale HTML snapshot. SplitText revert can reconstruct descendants: split a dedicated text leaf or visual copy when controls, state, or framework bindings must survive. Restore only owned inline properties to their original values, then apply the owner's readable settled state. A marker removal or `autoAlpha: 1` alone cannot undo clipping, transforms, child opacity, or a hidden parent. Avoid `clearProps: "all"` on application-owned styles.
+5. Release only this owner's hiding, cover, busy/inert state, and navigation lock. Apply essential settled completion once, including appropriate focus and transition `done`. Do not replay decorative effects or call an outgoing navigation callback as entrance completion.
+
+The bootstrap must retain a terminal recovery record even before the bundle arrives. With no application changes yet, it can release its CSS gate alone. Once setup starts, it must invoke the registered rollback as well. Releasing a shared document gate must not expose other still-preparing owners; use per-owner gates or transfer every owner's initial values before releasing it.
+
+Every async continuation and controller entry point checks its captured token **before any DOM write or effect creation**, including `set`, `fromTo`, `onSplit`, resize/font callbacks, and `contextSafe` callbacks. Context ownership does not cancel promises. Catch failures inside those callbacks too. Late controller registration reads the terminal boot record and settles without hiding or splitting. Do not infer recovery only from an absent marker that navigation can later recreate.
+
+On navigation, deactivate the outgoing owner's entrance recovery before the outro. Cancel stale work without revealing that owner. Recovery must exclude outgoing/end-state pages, cached hidden routes, closed dialogs, inactive tabs/panels, and decorative clones. Restore the outgoing page only if navigation itself is cancelled and that page becomes current again. Persistent shell elements keep separate visits. Dispose obsolete recovery timers on removal; never let them unlock or focus a newer route.
+
+## Rendering and indexing
+
+Keep primary text, headings, and meaningful links in server-rendered or prerendered HTML where supported. Preserve real `a[href]` links and independently accessible route URLs. Client-only rendering cannot reveal HTML that was never sent; provide a useful static shell/fallback and report that limit. Do not turn an entire page client-only to facilitate animation.
+
+Google renders JavaScript and uses rendered HTML for indexing. An automatic intro does not inherently prevent indexing; that is an inference from Google's rendering model, not a guarantee for a particular page. Check rendered output when indexing is in question. Static hiding rules alone do not establish production indexing failures. See [JavaScript SEO basics](https://developers.google.com/search/docs/crawling-indexing/javascript/javascript-seo-basics).
+
+Do not require a click, scroll, or hover to load primary indexable content. Keep primary hero media eagerly discoverable; reserve lazy loading for appropriate offscreen content. See [Google's lazy-loading guidance](https://developers.google.com/search/docs/crawling-indexing/javascript/lazy-loading).
+
+## First-load performance
+
+Initially hidden primary content can delay Largest Contentful Paint. LCP concerns eligible visible content painted in the viewport, not the end of a GSAP timeline. A heading or hero may become a candidate before the remaining stagger, footer, or ambient animation completes. Browser eligibility and candidate changes matter; do not calculate LCP from total timeline duration. See [Largest Contentful Paint](https://web.dev/articles/lcp).
+
+Reveal primary headings and hero imagery without waiting for unrelated plugins, particle setup, below-fold media, or every font weight. Keep ambitious motion where requested; reduce unnecessary preparation and deliberate blank holds before weakening the effect. Never serve crawler-specific content or use near-zero opacity tricks to manipulate metrics.
+
+Measure cold first loads separately from client-side transitions. Record the LCP element and timestamp, resource timing, layout shift, and a filmstrip under representative network/CPU conditions. Compare normal and reduced motion; use field data when available. Smooth route transitions do not prove fast document loads. Better performance does not promise ranking or indexing outcomes. See [Google's page-experience guidance](https://developers.google.com/search/docs/appearance/page-experience).
+
+## Failure verification
+
+Use the framework's production build and actual rendering mode. For every supported failure, assert meaningful text, usable links, restored owned styles/DOM, and absence of stale cover, lock, focus, or completion effects. Check page and shell owners separately.
+
+| Case | Required observation |
+|---|---|
+| JavaScript disabled | Server/static content and native links work. Client-only routes get their documented static fallback, not invented SSR content. |
+| Bundle blocked after marker | Prove the early marker executed; let its deadline expire. Content becomes readable without application cleanup. |
+| Setup throws before initial writes | Readable settled state; no unresolved completion or navigation wait. |
+| Setup throws after styles or split DOM | Timelines stop, original text/links return, temporary styles and masks disappear. |
+| Fonts/media stall or reject | Bounded fallback. Resolve them afterward and confirm no new hiding or splitting. |
+| Initialization arrives after recovery | Observe multiple frames after release and beyond the old timeline/deadline. No hidden frame or duplicate completion. |
+| Successful delayed startup within budget | Hidden first frame, then full intended intro. No flash of settled content; intentional duration may exceed the boot budget. |
+| Reduced motion | Readable first paint, functional links, normal completion semantics without travel. |
+| Navigation during preparation or intro | One correct destination; stale recovery cannot reveal outgoing/hidden content or unlock/focus the new visit. |
+| Repeated setup, history, and preserved nodes | No duplicate wrappers, listeners, callbacks, or replay after recovery within the same visit. |
+
+Block only application resources in the bundle test, not the early script or stylesheet. Distinguish an intentionally delayed intro from stalled preparation. Record what ran, rendering limitations, and remaining browser/production gaps; these checks do not prove Google indexed the page or establish field LCP.

package/skills/ui/gsap-tanstack-router/references/motion-system.md

@@ -0,0 +1,160 @@
+# Lifecycle implementation
+
+Read this to implement the five phases for pages and components without layout shift.
+
+## The contract
+
+**mount → initial state → intro → settled → outro → end state → unmount**
+
+One controller owns a node from mount to unmount and exposes one current phase:
+
+1. **Initial state.** Mounted, final size reserved, measured, start values applied, not yet shown.
+2. **Intro.** One timeline from initial values to settled.
+3. **Settled.** Visible, stable, interactive, and controlled by normal CSS.
+4. **Outro.** Still mounted while one timeline moves it toward removal.
+5. **End state.** Still mounted, final values applied, completion run once. Safe to unmount.
+
+The user's request defines how each phase looks. If it only describes an intro or outro, implement the other phases as the minimum needed to enter and leave cleanly.
+
+Store the current phase in state, a ref, or a data attribute. Do not infer it from opacity, DOM presence, or timeline progress.
+
+## Setup and React lifecycle
+
+Create one client-only module that imports GSAP, `useGSAP`, and only the plugins the project uses, and registers them once. Other modules import from it.
+
+Use `useGSAP` in components:
+
+- Pass a root ref as `scope`.
+- Use refs for single targets and scoped selectors for repeated ones.
+- Add dependencies only when the animation must rebuild. A reused route component needs its params, or its loader data, as dependencies with `revertOnUpdate` so a param change reruns the lifecycle.
+- Wrap callbacks and event handlers that create GSAP work in `contextSafe`.
+- Return a teardown for listeners and other non-GSAP resources.
+
+Never run GSAP or plugin code during server rendering. Under TanStack Start every route file can render on the server; keep GSAP inside effects.
+
+Do not call another component's `contextSafe` synchronously inside `useGSAP`: its context becomes a child and dies on the outer revert. Hand shared-controller work off through a microtask, effect, or event.
+
+Write setup so it is correct when it runs more than once on the same node. React development checks do this, and a route component reused across a param change hands you a node that already holds settled values. Async work started by the first run can still be in flight when the second run starts, so anything a setup triggers outside its own context, such as a shared cover, must be safe to request twice. So: explicit initial writes (`set` or `fromTo`) rather than `from` tweens that trust a fresh node, and cleanup that leaves the node readable. Use a ref guard only for work that should happen once per visit rather than once per setup.
+
+## Initial state
+
+Build the final layout with normal CSS first. The initial state changes appearance, not layout. The element that owns geometry must exist before the animated node mounts.
+
+- Mount content before measuring or animating it.
+- Give images and media dimensions or an aspect ratio.
+- Reserve async and streamed regions with a wrapper when their size is known.
+- Prefer transforms, `autoAlpha`, masks, or clipping, which keep the layout box.
+
+If the effect changes width, height, or position:
+
+- Animate a transform on an inner element while an outer wrapper holds the settled size.
+- For a real expand or collapse, measure start and end sizes first, animate the wrapper, and decide how surrounding content moves.
+- For layout-to-layout changes, use Flip: capture the old state, apply the new layout, animate.
+- When old and new content share one region, reserve the parent and overlap the children so only the parent affects layout.
+
+Content must stay readable without JavaScript. The pre-paint rule in [SSR and hydration](route-lifetime.md#ssr-and-hydration-with-tanstack-start) is the only sanctioned way to hide server-rendered content before the intro; client-only apps need none.
+
+## Initialization and recovery
+
+Apply the [initialization contract](initialization.md) whenever content starts hidden. It includes recovery ordering, indexing/performance limits, and failure checks.
+
+- With TanStack Start, use the installed `ScriptOnce` document integration described in [SSR and hydration](route-lifetime.md#ssr-and-hydration-with-tanstack-start). Include the independent deadline in that early script. Do not mutate split DOM before hydration.
+- Router-only client rendering and Start routes using `ssr: false` or `ssr: 'data-only'` cannot expose missing route HTML without JavaScript. Verify their rendered shell/`pendingComponent`, preserve native links there, and start component recovery when real targets mount.
+- Keep visit records in the persistent root controller. Register rollback before `useGSAP` initial writes; report ready only after required preparation and timeline handlers exist. Neither page registration nor `onRendered` alone proves readiness. Guard late loader, subscription, font, and media callbacks.
+- Invalidate before the blocker runs an outro and before cleanup/remount. Reused matches, `remountDeps`, and React effect replay must respect the current visit's terminal recovery. Resolve only its blocker/cover wait; persisted layouts and shell have separate owners.
+
+## Intro and settled
+
+Write reusable intro and outro builders only when behavior repeats. Each returns a timeline so the controller can compose, kill, reverse, or await it.
+
+- Make settled the source of truth. It must not depend on a paused timeline.
+- Clear temporary transform, visibility, transition, and `will-change` styles once settled.
+- Run intro completion and settled callbacks once, including under reduced motion.
+- On rapid state changes, replace, kill, or reverse the active timeline. Do not stack conflicting tweens.
+- Update assistive text and state immediately. Animate the visual, not the meaning.
+
+## Outro and end state
+
+Start the outro from current rendered values. Keep the node mounted, laid out, and owned until the timeline completes.
+
+- Reject duplicate outro requests or define which wins.
+- If an intro is running, reverse it only when the outro is its exact inverse. Otherwise kill it and build the outro from current values.
+- Disable pointer events when the visual can no longer support them, without removing the layout box.
+- Run end-state work once. Only then resolve the blocker, unmount, replace, hide, or hand off.
+- Kill the active timeline on cleanup, but do not erase state the route cover still needs.
+- No `display: none`, conditional removal, or DOM replacement before the outro completes.
+
+## Conditional show and hide
+
+React unmounts conditional content before an outro can play. Add a presence controller where that matters. It should:
+
+- Mount into initial state before the intro.
+- Stay mounted through settled and outro.
+- Keep the active timeline.
+- On re-show during an outro, reverse only if that gives the intended intro. Otherwise kill, set from current values, and build a fresh intro.
+- Remove the node only after the end-state callback.
+- Keep all five phases under reduced motion.
+
+When content in a shared region changes size, decide who owns the region's geometry before mounting either child. Overlap old and new inside a reserved wrapper, or animate a measured wrapper between known sizes. Do not let unmount then mount push surrounding content twice.
+
+Do not use presence for content that can simply appear, or for routes the root controller already manages.
+
+- Focus a panel when its intro completes, not when it mounts. An element at `visibility: hidden` refuses focus silently, and `autoAlpha: 0` is exactly that. Reduced motion jumps to completion synchronously, so the focus still lands.
+- When the outro ends and React is asked to unmount the children, clear only `will-change` from the wrapper. The unmount is queued, not immediate; clearing the collapsed height or visibility in the same tick flashes the content at full size for a frame.
+
+A modal that is a child route is a presence controller whose unmount is a navigation. See [Conditional content](route-lifetime.md#conditional-content).
+
+## Reduced and responsive motion
+
+The OS preference is the default. Add an app override only if the product needs one.
+
+Every effect needs initial, settled, and end states under reduced motion. Do not just shorten a disorienting effect. Skip travel, rotation, scale, parallax, and scrambling unless essential. A zero-duration timeline or an immediate `set` still fires completion for anything that depends on it, including the callback that lets a blocked navigation proceed.
+
+Use `gsap.matchMedia()` for responsive and reduced-motion variants that must rebuild when conditions change. Revert it through the owning component. Do not nest a second GSAP context for the same setup.
+
+An app-level override is not a media query, so `matchMedia` cannot see it. Read it in a shared `prefersReducedMotion()` helper that every timeline consults, mirror it as a root attribute so CSS can key on it, and for setups that live inside a `matchMedia` block either gate the block on the store through a hook dependency or accept that the block follows the OS alone and say so. Feed the router's `viewTransition` `types` function from the same decision.
+
+## Scroll
+
+Use `gsap-scrolltrigger` for the API; these rules cover route lifetime and measurement.
+
+- Create triggers in document order. Refresh after fonts, images, streamed data, or dynamic content change layout.
+- Create triggers inside the owning context. Do not kill all triggers globally when one page leaves. A layout route's triggers survive child navigations; a page's leave with it.
+- A route reused with new params keeps its triggers against changed content. Refresh them after the new data renders.
+- The router restores scroll in `onRendered`, after the page's layout effects. Triggers created in `useGSAP` measured before that; refresh from `onRendered`, and once more when the page settles if anything above a trigger changed height during the intro.
+- A `useGSAP` context revert calls `revert()` on each trigger with no arguments, which ScrollTrigger treats as `kill(true)`: the pin spacer is removed and the pinned element's original inline styles are restored. Leaving a route mid-pin needs no extra cleanup. `gsap.matchMedia()` created inside the same setup registers with that context and is reverted with it; it is not a second context for the same setup.
+- A `will-change` written from an `onToggle` callback is outside the context and survives its revert. Write it as a plain style and undo it in the matchMedia cleanup, or write it before the trigger is created.
+
+Under reduced motion, go straight from initial to settled without unnecessary triggers. Keep outro and end callbacks that control navigation or unmount.
+
+## Text
+
+Use SplitText when the effect needs per-character, word, or line targets.
+
+- For character splits, keep scoped `font-kerning: none; text-rendering: optimizeSpeed` before, during, and after revert, including reduced motion. Wrappers disrupt kerning and can cause horizontal snapping; use words/lines if natural kerning is essential. See [SplitText limitations](https://gsap.com/docs/v3/Plugins/SplitText/#tips--limitations).
+- Apparent weight changes can be clipped ink: check computed fonts/readiness, then mask edges, punctuation, and descenders. For confirmed clipping, add scoped mask padding with compensating negative margins; verify spacing and both hidden endpoints before trying compositing workarounds.
+- Keep reading accessible with the plugin's ARIA support. If text contains links or controls, keep an unsplit accessible version instead of hiding them.
+- Use word-aware wrapping for character animation. Use auto re-split for line animation that must survive width or font changes.
+- When line measurement needs fonts, bound the wait or auto-split preparation by the [initialization deadline](initialization.md#bound-initialization-not-choreography). Reserve settled height before splitting if wrappers could shift layout.
+- Keep a handle to the split's animation so re-split and cleanup can dispose of it. With `autoSplit`, build the animation inside `onSplit` and return it: the plugin records its playhead before a re-split and restores it on the new lines, and `revert()` undoes the tween's values. With line splitting and `autoSplit`, the plugin waits for fonts itself; no separate font wait is needed.
+- A split heading inside a page takes its timing from the page phase, not its own clock. Hold at initial while the page is initial, rise when the page enters, drop when it leaves. Give it its own pre-paint rule rather than marking it as a page target, or the page's stagger and the split's rise fight over one element.
+- Loader data changing in a reused route re-renders the heading's text node in place, which breaks a split that replaced it with spans. Revert before the data-dependent render and re-split after it, or key the split on the data.
+- Revert splits on interruption and unmount. Do not leave wrapper spans in stale content.
+
+Revert when the owning phase no longer needs the split. Compare glyph appearance, character positions, wrapping, and height immediately before/after cleanup at desktop/mobile widths, with reduced motion and interruption. Stable boxes alone do not prove stable ink; distinguish subpixel rounding from visible movement.
+
+## Interaction
+
+Pointer motion needs keyboard parity. Pair hover with focus on interactive elements. Do not animate a non-interactive element like a control.
+
+Keep gestures bounded, provide a non-gesture path, and dispose of interaction plugins with their owner. See `gsap-plugins` for Draggable, Observer, and Flip APIs.
+
+## Layout stability and performance
+
+- Prefer `x`, `y`, scale, rotation, and `autoAlpha` over layout properties.
+- Use `clip-path`, filters, and variable-font axes deliberately; they can cost paint or shift layout.
+- Batch reads before writes.
+- The stable wrapper's box should not jump between mount, initial, settled, outro, end, and unmount. Intentional transforms move pixels; layout boxes do not.
+- Set `will-change` just before animating and clear it after. Do not promote everything.
+- Do not animate hundreds of nodes at once. Reduce targets, batch, or virtualize.
+- Do not add a CSS transition on a property GSAP controls.